SwirlTransitionEffectLib — Plan9Basic Documentation

Overview

SwirlTransitionEffectLib uses a swirling/spinning animation to transition between source and target images, wrapping the FireMonkey TSwirlTransitionEffect component. Creates a dynamic vortex that twists the source image while revealing the target — ideal for dramatic or magical transitions.

Property	Details
Library	`SwirlTransitionEffectLib`
Prefix	`swirltrans_`
Wraps	`TSwirlTransitionEffect`
Functions	15
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
Strength	2	Get/set swirl intensity
Effect Control	2	Enabled get/set
Error Handling	4	Error codes and messages

🌀 Vortex Transition: Higher Strength values create more dramatic spinning. The default of 10 gives a strong vortex — use 5–15 for good results, or go higher for extreme effects.

Cross-Platform Support

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

Creation & Destruction

swirltrans#(parent#)

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

Parameter	Type	Description
`parent#`	Pointer	Target visual control
Returns	Pointer	Effect handle, or 0 on failure

swirltrans_free(effect#)

Destroys the effect and releases associated resources.

Error Handling

Function	Signature	Description
`swirltrans_error()`	`swirltrans_error@`	Returns last error code (0 = none)
`swirltrans_errormsg$()`	`swirltrans_errormsg$@`	Returns last error message
`swirltrans_strerror$(code)`	`swirltrans_strerror$@n`	Converts error code to text
`swirltrans_clearerror()`	`swirltrans_clearerror@`	Clears the error state

Target Image

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

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

Progress

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

At progress 0, the source image is shown normally. As progress increases, the swirl intensifies and the target emerges. At 1, the target is fully revealed.

Strength

Controls how dramatic the swirling vortex appears during the transition.

Function	Signature	Description
`swirltrans_strength#(effect#, value)`	`swirltrans_strength#@#n`	Set swirl intensity
`swirltrans_strength(effect#)`	`swirltrans_strength@#`	Get strength

Value	Effect
`1–5`	Subtle swirl
`10`	Default — moderate vortex
`15–20`	Strong spinning effect
`25+`	Very dramatic/extreme swirl

Effect Control

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

Complete Examples

Example 1: Animated Swirl Transition

╯ swirl-transition.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#("Swirl Transition", 400, 350)

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

trans# = swirltrans#(img#)
swirltrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
swirltrans_strength#(trans#, 15)

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

btn# = button#(frm#, "Swirl!")
button_bounds#(btn#, 150, 210, 100, 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
  swirltrans_progress#(trans#, progress)
  
  if progress >= 1 then
    timer_enabled#(tmr#, 0)
    button_enabled#(btn#, 1)
  endif
endfunction

Example 2: Strength Control

╯ swirl-strength.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let trkStr# = Pointer#(0)
let lblStr# = Pointer#(0)

frm# = form#("Swirl Strength", 450, 400)

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

trans# = swirltrans#(img#)
swirltrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
swirltrans_progress#(trans#, 0.5)

lblStr# = label#(frm#, "Strength: 10", 50, 200)
trkStr# = trackbar#(frm#)
trackbar_bounds#(trkStr#, 50, 230, 350, 30)
trackbar_max#(trkStr#, 30)
trackbar_value#(trkStr#, 10)
trackbar_onchange#(trkStr#, "OnStrength")

form_show(frm#)

function OnStrength(sender#) local s
  let s = trackbar_value(trkStr#)
  swirltrans_strength#(trans#, s)
  label_text#(lblStr#, "Strength: " + str$(s))
endfunction

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`swirltrans#(parent#)`	`swirltrans#@#`	Create effect
`swirltrans_free(effect#)`	`swirltrans_free@#`	Destroy effect
TARGET IMAGE
`swirltrans_target#(effect#, bitmap#)`	`swirltrans_target#@##`	Set target bitmap
`swirltrans_target#(effect#)`	`swirltrans_target#@#`	Get target bitmap
`swirltrans_loadtarget#(effect#, url$)`	`swirltrans_loadtarget#@#$`	Load target
PROGRESS
`swirltrans_progress#(effect#, value)`	`swirltrans_progress#@#n`	Set progress (0–1)
`swirltrans_progress(effect#)`	`swirltrans_progress@#`	Get progress
STRENGTH
`swirltrans_strength#(effect#, value)`	`swirltrans_strength#@#n`	Set swirl intensity
`swirltrans_strength(effect#)`	`swirltrans_strength@#`	Get strength
EFFECT CONTROL
`swirltrans_enabled#(effect#, value)`	`swirltrans_enabled#@#n`	Enable/disable
`swirltrans_enabled(effect#)`	`swirltrans_enabled@#`	Get enabled state
ERROR HANDLING
`swirltrans_error()`	`swirltrans_error@`	Last error code
`swirltrans_errormsg$()`	`swirltrans_errormsg$@`	Last error message
`swirltrans_strerror$(code)`	`swirltrans_strerror$@n`	Code to text
`swirltrans_clearerror()`	`swirltrans_clearerror@`	Clear error state

Library	Description
`SwirlEffectLib`	Static swirl distortion
`RippleTransitionEffectLib`	Ripple-based transition
`RotateCrumpleTransitionEffectLib`	Rotate/crumple transition