BandedSwirlTransitionEffectLib — Plan9Basic Documentation

BandedSwirlTransitionEffectLib — Banded Swirl Transition

A GPU-accelerated transition effect that blends between two images using a banded swirl pattern. As the progress property animates from 0.0 to 1.0, pixels from the source image spiral outward while the target image swirls in, creating a dramatic visual crossfade. Wraps FireMonkey’s TBandedSwirlTransitionEffect. 21 functions.

Category	Count	Description
Error Handling	4	error, errormsg$, strerror$, clearerror
Creation & Destruction	2	bandedswirltr# (create), _free (destroy)
Progress	2	progress (get/set) — drives the transition
Target Image	3	target# (get/set), loadtarget# (from URL)
Swirl Properties	4	strength, frequency (get/set)
Center Point	4	centerx, centery (get/set)
Effect Control	2	enabled (get/set)

ⓘ Transition Effect Pattern: All Plan9Basic transition effects follow the same workflow: attach to a control showing the source image, set the target image, then animate progress from 0.0 (source) to 1.0 (target). The visual style of the transition is what differs between libraries.

How Transitions Work

Transition effects blend between two images based on a progress value:

Progress	What’s Visible
`0.0`	100% source image (original control content)
`0.25`	Swirl begins — source starts distorting, target peeks through
`0.5`	Midpoint — equal blend of source and target in swirl pattern
`0.75`	Target dominates — source fading into swirl bands
`1.0`	100% target image

⚠ Important: Always set the target image before animating progress. If no target is set, the transition blends to a blank/black image.

Cross-Platform Support

Platform	Status	Notes
Windows	✅ Full Support	GPU-accelerated via Direct2D
macOS	✅ Full Support	GPU-accelerated via Metal/Quartz
Linux	✅ Full Support	Software rendering fallback
Android	✅ Full Support	GPU-accelerated
iOS	✅ Full Support	GPU-accelerated via Metal

Error Handling

All functions set an error code on failure. Check with bandedswirltr_error() after operations. Error code 0 means success.

Function	Signature	Description
`bandedswirltr_error()`	`bandedswirltr_error@`	Returns last error code (0 = no error)
`bandedswirltr_errormsg$()`	`bandedswirltr_errormsg$@`	Returns last error message as string
`bandedswirltr_strerror$(code)`	`bandedswirltr_strerror$@n`	Converts an error code to descriptive text
`bandedswirltr_clearerror()`	`bandedswirltr_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 TBandedSwirlTransitionEffect
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
`bandedswirltr#(parent#)`	`bandedswirltr#@#`	Creates a banded swirl transition effect on the given control. Returns the effect pointer.
`bandedswirltr_free(effect#)`	`bandedswirltr_free@#`	Destroys the effect and removes it from the parent control.

The parent# is typically an image control showing the source picture. The effect is created with default values (progress 0.0, strength 1.0, frequency 20, center 0.5/0.5).

╯ create-transition.bas─◻✕
' Create transition on an image showing the source
let trans# = bandedswirltr#(img#)

' Set the target image
bandedswirltr_loadtarget#(trans#, "https://picsum.photos/200/150")

' Animate progress to reveal target
bandedswirltr_progress#(trans#, 0.5)

Progress

The progress property drives the entire transition. Animate it from 0.0 to 1.0 to transition from source to target, or set it directly for manual control.

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

╯ progress.bas─◻✕
' Jump to midpoint
bandedswirltr_progress#(trans#, 0.5)

' Read current progress
let p = bandedswirltr_progress(trans#)
print "Progress: " + str$(p)

Target Image

The target image is what the transition reveals as progress approaches 1.0. You can set it from a bitmap pointer or load it directly from a URL.

Function	Signature	Description
`bandedswirltr_target#(effect#, bitmap#)`	`bandedswirltr_target#@##`	Sets target from a bitmap pointer
`bandedswirltr_target#(effect#)`	`bandedswirltr_target#@#`	Gets current target bitmap pointer
`bandedswirltr_loadtarget#(effect#, url$)`	`bandedswirltr_loadtarget#@#$`	Loads target image from a URL or file path

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

' Or set from an existing bitmap pointer
bandedswirltr_target#(trans#, myBitmap#)

Swirl Properties

Strength

Controls the intensity of the swirl distortion during transition. Higher values produce more dramatic spiraling. Default is 1.0.

Function	Signature	Description
`bandedswirltr_strength#(effect#, value)`	`bandedswirltr_strength#@#n`	Sets swirl strength
`bandedswirltr_strength(effect#)`	`bandedswirltr_strength@#`	Gets current strength

Strength	Visual Effect
0.0–0.5	Subtle swirl, gentle blending
0.5–1.0	Moderate swirl (default range)
1.0–3.0	Strong, dramatic spiral transition
5.0+	Extreme distortion during transition

Frequency

Controls the number of concentric bands in the swirl pattern. More bands create a tighter, more detailed spiral during the transition. Default is 20.

Function	Signature	Description
`bandedswirltr_frequency#(effect#, value)`	`bandedswirltr_frequency#@#n`	Sets band frequency
`bandedswirltr_frequency(effect#)`	`bandedswirltr_frequency@#`	Gets current frequency

Frequency	Visual Effect
3–8	Wide, dramatic spiral bands
10–20	Balanced pattern (default range)
30–50	Fine, tightly packed concentric rings

╯ swirl-properties.bas─◻✕
' Dramatic transition with fewer bands
bandedswirltr_strength#(trans#, 2.0)
bandedswirltr_frequency#(trans#, 5)

' Subtle transition with fine bands
bandedswirltr_strength#(trans#, 0.5)
bandedswirltr_frequency#(trans#, 40)

Center Point

Defines where the swirl originates, as normalized coordinates (0.0 to 1.0). Default is (0.5, 0.5) — center of the control.

Function	Signature	Description
`bandedswirltr_centerx#(effect#, value)`	`bandedswirltr_centerx#@#n`	Sets horizontal center (0.0 = left, 1.0 = right)
`bandedswirltr_centerx(effect#)`	`bandedswirltr_centerx@#`	Gets horizontal center
`bandedswirltr_centery#(effect#, value)`	`bandedswirltr_centery#@#n`	Sets vertical center (0.0 = top, 1.0 = bottom)
`bandedswirltr_centery(effect#)`	`bandedswirltr_centery@#`	Gets vertical center

╯ center-point.bas─◻✕
' Swirl from the top-left corner
bandedswirltr_centerx#(trans#, 0.0)
bandedswirltr_centery#(trans#, 0.0)

' Swirl from center (default)
bandedswirltr_centerx#(trans#, 0.5)
bandedswirltr_centery#(trans#, 0.5)

Effect Control

Toggles the effect on or off without destroying it. When disabled, the control renders normally showing only the source image.

Function	Signature	Description
`bandedswirltr_enabled#(effect#, value)`	`bandedswirltr_enabled#@#n`	Enables (1) or disables (0) the effect
`bandedswirltr_enabled(effect#)`	`bandedswirltr_enabled@#`	Gets enabled state (1 = on, 0 = off)

Complete Examples

Slider-Controlled Transition

Uses a trackbar to manually scrub through the banded swirl transition between two images.

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

frm# = form#("Banded Swirl Transition", 450, 400)

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

' Create transition effect
trans# = bandedswirltr#(img#)
bandedswirltr_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
bandedswirltr_strength#(trans#, 1.5)
bandedswirltr_frequency#(trans#, 15)

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

Animated Transition with Timer

Automatically animates the transition forward then backward using a timer, creating a ping-pong effect.

╯ bswirl-transition-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
let direction = 1

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

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

trans# = bandedswirltr#(img#)
bandedswirltr_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
bandedswirltr_strength#(trans#, 1.0)

' Timer for animation
tmr# = timer#()
timer_interval#(tmr#, 30)
timer_enabled#(tmr#, 0)
timer_ontimer#(tmr#, "Animate")

btn# = button#(frm#, "Start Transition")
button_bounds#(btn#, 130, 210, 140, 30)
button_onclick#(btn#, "StartAnim")

form_show(frm#)

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

function Animate(sender#)
  progress = progress + (direction * 0.02)
  bandedswirltr_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
Always set target image before animating progress	Without a target, the transition blends to black/empty
Use `loadtarget#` for simple URL-based targets	Easier than manually creating and assigning a bitmap pointer
Animate progress with a timer at 30ms intervals	Produces smooth ~33 FPS animation without overloading the GPU
Use step size of 0.02 for progress increments	Results in ~50 frames for a full transition — smooth and not too fast
Match source and target image dimensions	Different sizes may produce distorted transitions
Use lower frequency (5–10) for dramatic effect	Wide bands are more visually striking during transition
Disable with `bandedswirltr_enabled#` when not transitioning	Avoids GPU overhead when the transition is not active
Ping-pong pattern (0→1→0) for preview	Shows the full transition forward and back, great for demos

Quick Reference

Function	Signature	Description
ERROR HANDLING
`bandedswirltr_error()`	`bandedswirltr_error@`	Last error code
`bandedswirltr_errormsg$()`	`bandedswirltr_errormsg$@`	Last error message
`bandedswirltr_strerror$(code)`	`bandedswirltr_strerror$@n`	Error code to text
`bandedswirltr_clearerror()`	`bandedswirltr_clearerror@`	Clear error state
CREATION & DESTRUCTION
`bandedswirltr#(parent#)`	`bandedswirltr#@#`	Create transition on control
`bandedswirltr_free(effect#)`	`bandedswirltr_free@#`	Destroy effect
PROGRESS
`bandedswirltr_progress#(effect#, val)`	`bandedswirltr_progress#@#n`	Set progress (0.0–1.0)
`bandedswirltr_progress(effect#)`	`bandedswirltr_progress@#`	Get progress
TARGET IMAGE
`bandedswirltr_target#(effect#, bmp#)`	`bandedswirltr_target#@##`	Set target bitmap
`bandedswirltr_target#(effect#)`	`bandedswirltr_target#@#`	Get target bitmap
`bandedswirltr_loadtarget#(effect#, url$)`	`bandedswirltr_loadtarget#@#$`	Load target from URL
SWIRL PROPERTIES
`bandedswirltr_strength#(effect#, val)`	`bandedswirltr_strength#@#n`	Set swirl strength
`bandedswirltr_strength(effect#)`	`bandedswirltr_strength@#`	Get strength
`bandedswirltr_frequency#(effect#, val)`	`bandedswirltr_frequency#@#n`	Set band frequency
`bandedswirltr_frequency(effect#)`	`bandedswirltr_frequency@#`	Get frequency
CENTER POINT
`bandedswirltr_centerx#(effect#, val)`	`bandedswirltr_centerx#@#n`	Set center X (0.0–1.0)
`bandedswirltr_centerx(effect#)`	`bandedswirltr_centerx@#`	Get center X
`bandedswirltr_centery#(effect#, val)`	`bandedswirltr_centery#@#n`	Set center Y (0.0–1.0)
`bandedswirltr_centery(effect#)`	`bandedswirltr_centery@#`	Get center Y
EFFECT CONTROL
`bandedswirltr_enabled#(effect#, val)`	`bandedswirltr_enabled#@#n`	Enable (1) / disable (0)
`bandedswirltr_enabled(effect#)`	`bandedswirltr_enabled@#`	Get enabled state

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