FadeTransitionEffectLib — Plan9Basic Documentation

FadeTransitionEffectLib — Cross-Fade Transition

The classic cross-fade — smoothly blends the source image into the target using alpha interpolation. The most common and natural-looking transition in slideshows, presentations, and UI design. Wraps FireMonkey’s TFadeTransitionEffect. Simple, elegant, and universally understood. 16 functions.

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

ⓘ Simplest Transition: Unlike dissolve, crumple, or drop effects, the fade has no random seed property. It produces a perfectly smooth, deterministic alpha blend every time.

How Cross-Fade Works

At every pixel, the output colour is a weighted blend: output = source × (1 − progress) + target × progress. This produces a smooth, global transparency transition with no noise, columns, or distortion.

Progress	Source Opacity	Target Opacity	What You See
0.0	100%	0%	Full source image
0.25	75%	25%	Source with faint target ghosting
0.5	50%	50%	Equal blend — both images visible
0.75	25%	75%	Target dominant, source fading
1.0	0%	100%	Full target image

Fade vs. Other Transitions

Transition	Character	Best For
Fade	Smooth, clean, global alpha	Professional UI, slideshows, scene changes
Dissolve	Grainy, pixel-by-pixel random	Retro film, dramatic reveals
Crumple	Chaotic paper-like distortion	Playful, artistic transitions
Drop	Columns falling from above	Game UIs, scoreboards
Blind	Venetian blind strips reveal	Presentation slides

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
`fadetrans_error()`	`fadetrans_error@`	Returns last error code (0 = no error)
`fadetrans_errormsg$()`	`fadetrans_errormsg$@`	Returns last error message as string
`fadetrans_strerror$(code)`	`fadetrans_strerror$@n`	Converts an error code to descriptive text
`fadetrans_clearerror()`	`fadetrans_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 TFadeTransitionEffect
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
`fadetrans#(parent#)`	`fadetrans#@#`	Creates a fade transition effect on the given control. Returns the effect pointer.
`fadetrans_free(effect#)`	`fadetrans_free@#`	Destroys the effect and removes it from the parent.

Target Image

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

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

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

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

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

Progress

Controls the blend ratio between source and target. The only property of this effect — no seed, no angle, no randomness. Pure alpha interpolation.

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

Effect Control

Enabled

Function	Signature	Description
`fadetrans_enabled#(effect#, value)`	`fadetrans_enabled#@#n`	Enables (1) or disables (0)
`fadetrans_enabled(effect#)`	`fadetrans_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
`fadetrans_trigger#(effect#, trigger$)`	`fadetrans_trigger#@#$`	Sets trigger string
`fadetrans_trigger$(effect#)`	`fadetrans_trigger$@#`	Gets current trigger string

Complete Examples

Slider-Controlled Fade

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

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

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

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

Animated Cross-Fade

╯ fade-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 Fade", 400, 350)

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

trans# = fadetrans#(img#)
fadetrans_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#, "Fade")
button_bounds#(btn#, 150, 210, 100, 30)
button_onclick#(btn#, "StartFade")

form_show(frm#)

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

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

Bi-Directional Fade Loop

Fades forward to the target then reverses back to the source, creating a breathing/pulsing slideshow effect.

╯ fade-loop.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let tmr# = Pointer#(0)
let btn# = Pointer#(0)
let progress = 0
let direction = 1

frm# = form#("Fade Loop", 400, 350)

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

trans# = fadetrans#(img#)
fadetrans_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#, "Start Loop")
button_bounds#(btn#, 140, 210, 120, 30)
button_onclick#(btn#, "StartLoop")

form_show(frm#)

function StartLoop(sender#)
  timer_enabled#(tmr#, 1)
  button_enabled#(btn#, 0)
endfunction

function Animate(sender#)
  progress = progress + (direction * 0.02)
  fadetrans_progress#(trans#, progress)
  if progress >= 1 then
    direction = -1
  endif
  if progress <= 0 then
    direction = 1
    timer_enabled#(tmr#, 0)
    button_enabled#(btn#, 1)
  endif
endfunction

Best Practices

Practice	Why
Use fade as your default transition	Clean, professional, works everywhere — always a safe choice
Load target before animating	Without a target, the effect fades to transparent/empty
Use `targetfromimage#` for live transitions	Capture another on-screen image as fade target dynamically
Step 0.02 at 30ms = ~1.5s transition	Natural, cinematic cross-fade timing
Step 0.01 at 30ms = ~3s transition	Slow, contemplative fade for dramatic effect
Bi-directional loop for slideshows	Fades forward and back between two images continuously
Use `FloatAnimationLib` for easing	Animate progress with ease-in/ease-out for polished feel
Combine with `BrightTransitionEffectLib`	Fade + brightness flash for cinema-style white-flash transitions
Disable button during animation	Prevents overlapping transitions

Quick Reference

Function	Signature	Description
ERROR HANDLING
`fadetrans_error()`	`fadetrans_error@`	Last error code
`fadetrans_errormsg$()`	`fadetrans_errormsg$@`	Last error message
`fadetrans_strerror$(code)`	`fadetrans_strerror$@n`	Error code to text
`fadetrans_clearerror()`	`fadetrans_clearerror@`	Clear error state
CREATION & DESTRUCTION
`fadetrans#(parent#)`	`fadetrans#@#`	Create effect on control
`fadetrans_free(effect#)`	`fadetrans_free@#`	Destroy effect
TARGET IMAGE
`fadetrans_target#(effect#, bmp#)`	`fadetrans_target#@##`	Set target bitmap
`fadetrans_target#(effect#)`	`fadetrans_target#@#`	Get target bitmap
`fadetrans_loadtarget#(effect#, url$)`	`fadetrans_loadtarget#@#$`	Load target from URL/file
`fadetrans_targetfromimage#(effect#, img#)`	`fadetrans_targetfromimage#@##`	Copy target from TImage control
PROGRESS
`fadetrans_progress#(effect#, val)`	`fadetrans_progress#@#n`	Set progress (0.0–1.0)
`fadetrans_progress(effect#)`	`fadetrans_progress@#`	Get progress
EFFECT CONTROL
`fadetrans_enabled#(effect#, val)`	`fadetrans_enabled#@#n`	Enable (1) / disable (0)
`fadetrans_enabled(effect#)`	`fadetrans_enabled@#`	Get enabled state
`fadetrans_trigger#(effect#, str$)`	`fadetrans_trigger#@#$`	Set trigger string
`fadetrans_trigger$(effect#)`	`fadetrans_trigger$@#`	Get trigger string

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