PixelateTransitionEffectLib — Plan9Basic Documentation

Overview

PixelateTransitionEffectLib creates a retro pixelated transition between a source and target image, wrapping the FireMonkey TPixelateTransitionEffect component. As the transition progresses, the source image pixelates into larger blocks that then resolve into the target image — evoking classic video game scene transitions.

Property	Details
Library	`PixelateTransitionEffectLib`
Prefix	`pixelatetrans_`
Wraps	`TPixelateTransitionEffect`
Functions	13
Type	Transition effect

Category	Count	Description
Creation / Destruction	2	Create and free effect
Target Image	3	Set/get/load target bitmap
Progress	2	Get/set transition progress
Effect Control	2	Enabled get/set
Error Handling	4	Error codes and messages

🎮 Retro Transitions: This effect is perfect for retro video game-style scene changes. The source image breaks into mosaic blocks that reform into the target image — combine with a timer for smooth animated transitions.

Cross-Platform Support

Platform	Support
Windows	✅ Full support
Linux	✅ Full support
Android	✅ Full support

Creation & Destruction

pixelatetrans#(parent#)

Creates a new pixelate transition effect attached to the specified visual control.

Parameter	Type	Description
`parent#`	Pointer	Target visual control (e.g., image)
Returns	Pointer	Effect handle, or 0 on failure

pixelatetrans_free(effect#)

Destroys the effect and releases associated resources.

Error Handling

Function	Signature	Description
`pixelatetrans_error()`	`pixelatetrans_error@`	Returns last error code (0 = none)
`pixelatetrans_errormsg$()`	`pixelatetrans_errormsg$@`	Returns last error message
`pixelatetrans_strerror$(code)`	`pixelatetrans_strerror$@n`	Converts error code to text
`pixelatetrans_clearerror()`	`pixelatetrans_clearerror@`	Clears the error state

Target Image

The target image is what the transition resolves to. You can set it from an existing bitmap pointer or load it directly from a URL or file path.

Function	Signature	Description
`pixelatetrans_target#(effect#, bitmap#)`	`pixelatetrans_target#@##`	Sets target from bitmap pointer
`pixelatetrans_target#(effect#)`	`pixelatetrans_target#@#`	Gets target bitmap pointer
`pixelatetrans_loadtarget#(effect#, url$)`	`pixelatetrans_loadtarget#@#$`	Loads target from URL or file

⚠ Target Required: Transition effects need a target image to work properly. Without a target, the transition has nothing to resolve to. Always call pixelatetrans_loadtarget# or pixelatetrans_target# before animating.

Progress

Controls the transition state between source (0.0) and target (1.0) images.

Function	Signature	Description
`pixelatetrans_progress#(effect#, value)`	`pixelatetrans_progress#@#n`	Set progress (0.0–1.0)
`pixelatetrans_progress(effect#)`	`pixelatetrans_progress@#`	Get current progress

Value	Visual State
`0.0`	Source image (original, no pixelation)
`0.25`	Source begins pixelating into blocks
`0.5`	Maximum pixelation (mosaic midpoint)
`0.75`	Target image forming from blocks
`1.0`	Target image (fully resolved)

Effect Control

Function	Signature	Description
`pixelatetrans_enabled#(effect#, value)`	`pixelatetrans_enabled#@#n`	Enable (1) or disable (0)
`pixelatetrans_enabled(effect#)`	`pixelatetrans_enabled@#`	Gets enabled state

Complete Examples

Example 1: Slider-Controlled Transition

╯ pixelate-slider.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let trkProg# = Pointer#(0)
let lblProg# = Pointer#(0)

frm# = form#("Pixelate Transition", 450, 400)

img# = image#(frm#)
image_bounds#(img#, 125, 30, 200, 150)
image_load#(img#, "https://picsum.photos/200/150?random=1")

' Create pixelate transition effect
trans# = pixelatetrans#(img#)
pixelatetrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")

' Progress slider
lblProg# = label#(frm#, "Progress: 0.00", 50, 200)
trkProg# = trackbar#(frm#)
trackbar_bounds#(trkProg#, 50, 230, 350, 30)
trackbar_max#(trkProg#, 100)
trackbar_value#(trkProg#, 0)
trackbar_onchange#(trkProg#, "OnProgress")

form_show(frm#)

function OnProgress(sender#) local p
  let p = trackbar_value(trkProg#) / 100
  pixelatetrans_progress#(trans#, p)
  label_text#(lblProg#, "Progress: " + stri$(p, 2))
endfunction

Example 2: Animated Transition

╯ animated-pixelate.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let tmr# = Pointer#(0)
let btn# = Pointer#(0)
let progress = 0

frm# = form#("Animated Pixelate", 400, 350)

img# = image#(frm#)
image_bounds#(img#, 100, 30, 200, 150)
image_load#(img#, "https://picsum.photos/200/150?random=1")

trans# = pixelatetrans#(img#)
pixelatetrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")

tmr# = timer#()
timer_interval#(tmr#, 30)
timer_enabled#(tmr#, 0)
timer_ontimer#(tmr#, "Animate")

btn# = button#(frm#, "Pixelate!")
button_bounds#(btn#, 140, 210, 120, 30)
button_onclick#(btn#, "StartTransition")

form_show(frm#)

function StartTransition(sender#)
  progress = 0
  timer_enabled#(tmr#, 1)
  button_enabled#(btn#, 0)
endfunction

function Animate(sender#)
  progress = progress + 0.02
  pixelatetrans_progress#(trans#, progress)
  
  if progress >= 1 then
    timer_enabled#(tmr#, 0)
    button_enabled#(btn#, 1)
  endif
endfunction

Example 3: Toggle Effect

╯ toggle-pixelatetrans.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let btn# = Pointer#(0)
let isOn = 1

frm# = form#("Toggle Pixelate", 400, 350)

img# = image#(frm#)
image_bounds#(img#, 100, 30, 200, 150)
image_load#(img#, "https://picsum.photos/200/150?random=1")

trans# = pixelatetrans#(img#)
pixelatetrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
pixelatetrans_progress#(trans#, 0.5)

btn# = button#(frm#, "Disable Effect")
button_bounds#(btn#, 130, 210, 140, 30)
button_onclick#(btn#, "Toggle")

form_show(frm#)

function Toggle(sender#)
  if isOn = 1 then
    pixelatetrans_enabled#(trans#, 0)
    isOn = 0
    button_text#(btn#, "Enable Effect")
  else
    pixelatetrans_enabled#(trans#, 1)
    isOn = 1
    button_text#(btn#, "Disable Effect")
  endif
endfunction

Best Practices

Practice	Why
Always load a target image before animating	Transitions need a target to resolve to
Use timer with 20–40ms interval for smooth animation	~30ms gives good visual quality at ~33 FPS
Increment progress by 0.01–0.03 per tick	Smaller steps = smoother, slower transition
Disable button during animation	Prevents re-triggering while animating
Match source and target image dimensions	Ensures clean transition without scaling artifacts
Combine with PixelateEffectLib for static pixelation	Use the static effect for permanent pixelation, transition for animated

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`pixelatetrans#(parent#)`	`pixelatetrans#@#`	Create effect
`pixelatetrans_free(effect#)`	`pixelatetrans_free@#`	Destroy effect
TARGET IMAGE
`pixelatetrans_target#(effect#, bitmap#)`	`pixelatetrans_target#@##`	Set target bitmap
`pixelatetrans_target#(effect#)`	`pixelatetrans_target#@#`	Get target bitmap
`pixelatetrans_loadtarget#(effect#, url$)`	`pixelatetrans_loadtarget#@#$`	Load target from URL/file
PROGRESS
`pixelatetrans_progress#(effect#, value)`	`pixelatetrans_progress#@#n`	Set progress (0–1)
`pixelatetrans_progress(effect#)`	`pixelatetrans_progress@#`	Get progress
EFFECT CONTROL
`pixelatetrans_enabled#(effect#, value)`	`pixelatetrans_enabled#@#n`	Enable/disable
`pixelatetrans_enabled(effect#)`	`pixelatetrans_enabled@#`	Get enabled state
ERROR HANDLING
`pixelatetrans_error()`	`pixelatetrans_error@`	Last error code
`pixelatetrans_errormsg$()`	`pixelatetrans_errormsg$@`	Last error message
`pixelatetrans_strerror$(code)`	`pixelatetrans_strerror$@n`	Code to text
`pixelatetrans_clearerror()`	`pixelatetrans_clearerror@`	Clear error state

Library	Description
`PixelateEffectLib`	Static pixelation/mosaic effect
`DissolveTransitionEffectLib`	Random pixel dissolve transition
`FadeTransitionEffectLib`	Cross-fade transition
`BlurTransitionEffectLib`	Blur-based transition