DissolveTransitionEffectLib — Plan9Basic Documentation

DissolveTransitionEffectLib — Dissolve Transition

Dissolves the source image into the target by randomly revealing pixels, creating a classic film dissolve or “noise” transition. Wraps FireMonkey’s TDissolveTransitionEffect. A timeless transition style used in film, television, and slideshows for decades. 18 functions.

Category	Count	Description
Error Handling	4	dissolvetrans_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	dissolvetrans# (create), dissolvetrans_free (destroy)
Target Image	4	target (get/set), loadtarget, targetfromimage
Progress & Seed	4	progress, seed (get/set)
Effect Control	4	enabled, trigger (get/set)

⚠ Target Required: Without a target image, the effect dissolves to transparent/empty. Always load or set a target before animating progress.

ⓘ Extra vs. Crumple: DissolveTransitionEffectLib has 18 functions — two more than CrumpleTransitionEffectLib. It includes both trigger (get/set) and the unique targetfromimage# function for copying textures from TImage controls.

How Dissolve Works

The dissolve randomly replaces source pixels with target pixels as progress increases. Unlike a fade (which blends globally), dissolve operates on individual pixels, creating a grainy, film-like appearance.

Progress	What You See
0.0	100% source image — no dissolve
0.25	~25% target pixels scattered randomly over source
0.5	50/50 mix — half source, half target pixels
0.75	~75% target — source nearly gone
1.0	100% target image — dissolve complete

Dissolve vs. Fade

Aspect	Dissolve	Fade
Mechanism	Individual pixels switch randomly	Global alpha blend between images
Visual Character	Grainy, film-like, noisy	Smooth, gradual, clean
Randomness	Controlled by seed value	No randomness involved
Best For	Retro/film aesthetics, dramatic changes	Clean UI transitions, subtle changes

Cross-Platform Support

Platform	Status	Notes
Windows	✅ Full Support	GPU-accelerated via Direct2D
Linux	✅ Full Support	Software rendering fallback
Android	✅ Full Support	GPU-accelerated

Error Handling

Function	Signature	Description
`dissolvetrans_error()`	`dissolvetrans_error@`	Returns last error code (0 = no error)
`dissolvetrans_errormsg$()`	`dissolvetrans_errormsg$@`	Returns last error message as string
`dissolvetrans_strerror$(code)`	`dissolvetrans_strerror$@n`	Converts an error code to descriptive text
`dissolvetrans_clearerror()`	`dissolvetrans_clearerror@`	Clears the error state

Error Codes

Code	Constant	Meaning
0	ERR_NONE	No error
1	ERR_NIL_EFFECT	Effect pointer is nil
2	ERR_INVALID_EFFECT	Pointer is not a valid TDissolveTransitionEffect
3	ERR_INVALID_VALUE	Property value out of range
4	ERR_NIL_PARENT	Parent control pointer is nil
5	ERR_INVALID_PARENT	Pointer is not a valid TFmxObject

Creation & Destruction

Function	Signature	Description
`dissolvetrans#(parent#)`	`dissolvetrans#@#`	Creates a dissolve transition effect on the given control. Returns the effect pointer.
`dissolvetrans_free(effect#)`	`dissolvetrans_free@#`	Destroys the effect and removes it from the parent.

Target Image

The target is the image to dissolve into. Three methods are available for setting the target.

Function	Signature	Description
`dissolvetrans_target#(effect#, bitmap#)`	`dissolvetrans_target#@##`	Sets the target bitmap pointer directly
`dissolvetrans_target#(effect#)`	`dissolvetrans_target#@#`	Gets the current target bitmap pointer
`dissolvetrans_loadtarget#(effect#, url$)`	`dissolvetrans_loadtarget#@#$`	Loads the target image from a URL or file path
`dissolvetrans_targetfromimage#(effect#, image#)`	`dissolvetrans_targetfromimage#@##`	Copies target texture from an existing TImage control

ⓘ targetfromimage#: Unique to DissolveTransitionEffectLib. Copies the current bitmap from a TImage control, allowing you to use another on-screen image as the dissolve target without loading from URL/file.

╯ target-methods.bas─◻✕
' Method 1: Load from URL (most common)
dissolvetrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")

' Method 2: Load from local file
dissolvetrans_loadtarget#(trans#, "photos/sunset.jpg")

' Method 3: Copy from another TImage on screen
dissolvetrans_targetfromimage#(trans#, otherImg#)

Progress

Controls how far through the dissolve we are. Animate from 0.0 to 1.0 for the full dissolve effect.

Function	Signature	Description
`dissolvetrans_progress#(effect#, value)`	`dissolvetrans_progress#@#n`	Sets progress (0.0–1.0)
`dissolvetrans_progress(effect#)`	`dissolvetrans_progress@#`	Gets current progress

Random Seed

Changes the pixel reveal pattern. Different seeds produce different dissolve textures. Set before starting the animation for consistent, reproducible results.

Function	Signature	Description
`dissolvetrans_seed#(effect#, value)`	`dissolvetrans_seed#@#n`	Sets random seed (0.0–1.0)
`dissolvetrans_seed(effect#)`	`dissolvetrans_seed@#`	Gets current seed

Seed	Effect
0.0	Default dissolve pattern
0.1–0.4	Varied fine-grain dissolve textures
0.5	Mid-range pattern
0.6–0.9	Varied coarse-grain dissolve textures
1.0	Alternate extreme pattern

Effect Control

Enabled

Function	Signature	Description
`dissolvetrans_enabled#(effect#, value)`	`dissolvetrans_enabled#@#n`	Enables (1) or disables (0)
`dissolvetrans_enabled(effect#)`	`dissolvetrans_enabled@#`	Gets enabled state

Trigger

Trigger functions are present in the source code but were omitted from the original markdown. Documented here from source verification.

Function	Signature	Description
`dissolvetrans_trigger#(effect#, trigger$)`	`dissolvetrans_trigger#@#$`	Sets trigger string
`dissolvetrans_trigger$(effect#)`	`dissolvetrans_trigger$@#`	Gets current trigger string

Complete Examples

Slider-Controlled Dissolve

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

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

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

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

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
  dissolvetrans_progress#(trans#, p)
  label_text#(lblProg#, "Progress: " + stri$(p, 2))
endfunction

Animated Dissolve with Timer

╯ dissolve-animated.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 Dissolve", 400, 350)

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

trans# = dissolvetrans#(img#)
dissolvetrans_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#, "Dissolve!")
button_bounds#(btn#, 150, 210, 100, 30)
button_onclick#(btn#, "StartDissolve")

form_show(frm#)

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

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

Dual Sliders — Progress + Seed

╯ dissolve-patterns.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let trkProg# = Pointer#(0)
let trkSeed# = Pointer#(0)
let lblProg# = Pointer#(0)
let lblSeed# = Pointer#(0)

frm# = form#("Dissolve Patterns", 500, 420)

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

trans# = dissolvetrans#(img#)
dissolvetrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
dissolvetrans_progress#(trans#, 0.5)

lblProg# = label#(frm#, "Progress: 0.50", 30, 190)
trkProg# = trackbar#(frm#)
trackbar_bounds#(trkProg#, 30, 215, 440, 25)
trackbar_max#(trkProg#, 100)
trackbar_value#(trkProg#, 50)
trackbar_onchange#(trkProg#, "OnProgress")

lblSeed# = label#(frm#, "Random Seed: 0.00", 30, 260)
trkSeed# = trackbar#(frm#)
trackbar_bounds#(trkSeed#, 30, 285, 440, 25)
trackbar_max#(trkSeed#, 100)
trackbar_value#(trkSeed#, 0)
trackbar_onchange#(trkSeed#, "OnSeed")

form_show(frm#)

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

function OnSeed(sender#) local s
  let s = trackbar_value(trkSeed#) / 100
  dissolvetrans_seed#(trans#, s)
  label_text#(lblSeed#, "Random Seed: " + stri$(s, 2))
endfunction

Best Practices

Practice	Why
Always load a target image before animating	Without a target, the effect dissolves to transparent/empty
Use `loadtarget#` for simplest target loading	Handles URL and file paths automatically
Use `targetfromimage#` for dynamic sources	Capture another on-screen image as dissolve target without file I/O
Set seed before starting animation	Changing seed mid-transition produces jarring pixel pattern jumps
Animate at ~30ms timer interval	~33 FPS provides smooth pixel-by-pixel reveal
Use step size 0.02 for ~1.5s dissolve	50 frames × 30ms = natural film-like timing
Dissolve for drama, fade for clean UI	Dissolve has grainy film character; fade is smooth and modern
Try different seeds for variety	Each seed generates a unique pixel reveal pattern
Disable button during animation	Prevents overlapping transitions

Quick Reference

Function	Signature	Description
ERROR HANDLING
`dissolvetrans_error()`	`dissolvetrans_error@`	Last error code
`dissolvetrans_errormsg$()`	`dissolvetrans_errormsg$@`	Last error message
`dissolvetrans_strerror$(code)`	`dissolvetrans_strerror$@n`	Error code to text
`dissolvetrans_clearerror()`	`dissolvetrans_clearerror@`	Clear error state
CREATION & DESTRUCTION
`dissolvetrans#(parent#)`	`dissolvetrans#@#`	Create effect on control
`dissolvetrans_free(effect#)`	`dissolvetrans_free@#`	Destroy effect
TARGET IMAGE
`dissolvetrans_target#(effect#, bmp#)`	`dissolvetrans_target#@##`	Set target bitmap
`dissolvetrans_target#(effect#)`	`dissolvetrans_target#@#`	Get target bitmap
`dissolvetrans_loadtarget#(effect#, url$)`	`dissolvetrans_loadtarget#@#$`	Load target from URL/file
`dissolvetrans_targetfromimage#(effect#, img#)`	`dissolvetrans_targetfromimage#@##`	Copy target from TImage control
PROGRESS & SEED
`dissolvetrans_progress#(effect#, val)`	`dissolvetrans_progress#@#n`	Set progress (0.0–1.0)
`dissolvetrans_progress(effect#)`	`dissolvetrans_progress@#`	Get progress
`dissolvetrans_seed#(effect#, val)`	`dissolvetrans_seed#@#n`	Set seed (0.0–1.0)
`dissolvetrans_seed(effect#)`	`dissolvetrans_seed@#`	Get seed
EFFECT CONTROL
`dissolvetrans_enabled#(effect#, val)`	`dissolvetrans_enabled#@#n`	Enable (1) / disable (0)
`dissolvetrans_enabled(effect#)`	`dissolvetrans_enabled@#`	Get enabled state
`dissolvetrans_trigger#(effect#, str$)`	`dissolvetrans_trigger#@#$`	Set trigger string
`dissolvetrans_trigger$(effect#)`	`dissolvetrans_trigger$@#`	Get trigger string

18 functions. Part of the Plan9Basic transition effects library system.