SaturateTransitionEffectLib — Plan9Basic Documentation

Overview

SaturateTransitionEffectLib transitions between images by manipulating color saturation, wrapping the FireMonkey TSaturateTransitionEffect component. During the transition, the source image desaturates toward grayscale at the midpoint, then the target image emerges with increasing saturation — creating a dramatic, cinematic color-drain effect.

Property	Details
Library	`SaturateTransitionEffectLib`
Prefix	`saturatrans_`
Wraps	`TSaturateTransitionEffect`
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

🎨 Color Drama: The saturation transition is ideal for artistic or cinematic effects. The source image fades to near-grayscale at the midpoint, then the target image blooms with color — great for mood-shifting scene changes.

Cross-Platform Support

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

Creation & Destruction

saturatrans#(parent#)

Creates a new saturate 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

saturatrans_free(effect#)

Destroys the effect and releases associated resources.

Error Handling

Function	Signature	Description
`saturatrans_error()`	`saturatrans_error@`	Returns last error code (0 = none)
`saturatrans_errormsg$()`	`saturatrans_errormsg$@`	Returns last error message
`saturatrans_strerror$(code)`	`saturatrans_strerror$@n`	Converts error code to text
`saturatrans_clearerror()`	`saturatrans_clearerror@`	Clears the error state

Target Image

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

⚠ Target Required: Transition effects need a target image. Always load a target before animating progress.

Progress

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

Value	Visual State
`0.0`	Source image (full color)
`0.25`	Source losing saturation
`0.5`	Near-grayscale midpoint
`0.75`	Target gaining color
`1.0`	Target image (full color)

Effect Control

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

Complete Examples

Example 1: Slider-Controlled Transition

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

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

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

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

Example 2: Animated Transition

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

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

trans# = saturatrans#(img#)
saturatrans_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#, "Transition!")
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
  saturatrans_progress#(trans#, progress)
  
  if progress >= 1 then
    timer_enabled#(tmr#, 0)
    button_enabled#(btn#, 1)
  endif
endfunction

Example 3: Toggle Effect

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

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

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

trans# = saturatrans#(img#)
saturatrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
saturatrans_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
    saturatrans_enabled#(trans#, 0)
    isOn = 0
    button_text#(btn#, "Enable Effect")
  else
    saturatrans_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 colorful source images	The desaturation effect is most visible on vibrant photos
Slower progress (0.01 per tick) enhances the mood shift	Gives the grayscale midpoint time to register visually
Pair with BrightTransition for combined effect	Saturation + brightness creates dramatic cinematic transitions

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`saturatrans#(parent#)`	`saturatrans#@#`	Create effect
`saturatrans_free(effect#)`	`saturatrans_free@#`	Destroy effect
TARGET IMAGE
`saturatrans_target#(effect#, bitmap#)`	`saturatrans_target#@##`	Set target bitmap
`saturatrans_target#(effect#)`	`saturatrans_target#@#`	Get target bitmap
`saturatrans_loadtarget#(effect#, url$)`	`saturatrans_loadtarget#@#$`	Load target from URL/file
PROGRESS
`saturatrans_progress#(effect#, value)`	`saturatrans_progress#@#n`	Set progress (0–1)
`saturatrans_progress(effect#)`	`saturatrans_progress@#`	Get progress
EFFECT CONTROL
`saturatrans_enabled#(effect#, value)`	`saturatrans_enabled#@#n`	Enable/disable
`saturatrans_enabled(effect#)`	`saturatrans_enabled@#`	Get enabled state
ERROR HANDLING
`saturatrans_error()`	`saturatrans_error@`	Last error code
`saturatrans_errormsg$()`	`saturatrans_errormsg$@`	Last error message
`saturatrans_strerror$(code)`	`saturatrans_strerror$@n`	Code to text
`saturatrans_clearerror()`	`saturatrans_clearerror@`	Clear error state

Library	Description
`BrightTransitionEffectLib`	Brightness-based transition
`FadeTransitionEffectLib`	Cross-fade transition
`MonochromeEffectLib`	Static grayscale effect