BandedSwirlEffectLib — Plan9Basic Documentation

BandedSwirlEffectLib — Banded Swirl Effect

Creates a GPU-accelerated banded swirl distortion on any visual control. Pixels rotate around a configurable center point in alternating concentric bands, producing a hypnotic spiral pattern. The effect wraps FireMonkey’s TBandedSwirlEffect and is ideal for decorative distortions, loading animations, psychedelic visuals, and interactive image manipulation. 20 functions.

Category	Count	Description
Error Handling	4	bswirl_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	bswirl# (create), bswirl_free (destroy)
Center Point	4	centerx, centery (get/set)
Swirl Properties	6	bands, strength, aspect (get/set)
Effect Control	4	enabled, trigger (get/set)

ⓘ Effect Ownership: The effect is owned by its parent control, not managed by garbage collection. Destroying the parent control also destroys the effect. Use bswirl_free only to remove the effect while keeping the parent alive.

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

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

Function	Signature	Description
`bswirl_error()`	`bswirl_error@`	Returns last error code (0 = no error)
`bswirl_errormsg$()`	`bswirl_errormsg$@`	Returns last error message as string
`bswirl_strerror$(code)`	`bswirl_strerror$@n`	Converts an error code to descriptive text
`bswirl_clearerror()`	`bswirl_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 TBandedSwirlEffect
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

╯ error-check.bas─◻✕
let bsw# = bswirl#(img#)
if bswirl_error() <> 0 then
    print "Error: " + bswirl_errormsg$()
else
    print "Banded swirl created"
endif

Creation & Destruction

Function	Signature	Description
`bswirl#(parent#)`	`bswirl#@#`	Creates a banded swirl effect attached to the given control. Returns the effect pointer.
`bswirl_free(effect#)`	`bswirl_free@#`	Destroys the effect and removes it from the parent control.

The parent# can be any visual control: images, rectangles, panels, labels, shapes, etc. The effect is applied immediately upon creation with default values (center 0.5/0.5, 10 bands, strength 0.5, aspect 1.0).

╯ create-effect.bas─◻✕
' Create banded swirl on an image
let bsw# = bswirl#(img#)

' Later, remove the effect
bswirl_free(bsw#)

Center Point

The center point defines the origin of the swirl, expressed as normalized coordinates (0.0 to 1.0). Default is (0.5, 0.5) — the center of the control.

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

╯ center-point.bas─◻✕
' Swirl from the top-left corner
bswirl_centerx#(bsw#, 0.0)
bswirl_centery#(bsw#, 0.0)

' Swirl from center (default)
bswirl_centerx#(bsw#, 0.5)
bswirl_centery#(bsw#, 0.5)

Swirl Properties

Bands

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

Function	Signature	Description
`bswirl_bands#(effect#, value)`	`bswirl_bands#@#n`	Sets number of bands (1+)
`bswirl_bands(effect#)`	`bswirl_bands@#`	Gets current band count

Bands	Visual Effect
1–3	Wide, dramatic spiral bands
5–10	Balanced swirl pattern (default range)
15–30	Fine, tightly packed concentric rings
50+	Very fine detail, may appear as a blur at distance

Strength

Controls the intensity of the swirl distortion. Higher values rotate pixels further. Negative values reverse the swirl direction. Default is 0.5.

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

Strength	Visual Effect
0.0	No distortion (original image)
0.1–0.5	Subtle swirl, gentle distortion
0.5–1.0	Moderate swirl, clearly visible
1.0–2.0	Strong distortion, psychedelic effect
Negative	Reverse direction (counter-clockwise)

Aspect Ratio

Adjusts the aspect ratio of the swirl. A value of 1.0 produces a circular swirl. Values other than 1.0 stretch the effect horizontally or vertically.

Function	Signature	Description
`bswirl_aspect#(effect#, value)`	`bswirl_aspect#@#n`	Sets aspect ratio
`bswirl_aspect(effect#)`	`bswirl_aspect@#`	Gets current aspect ratio

╯ swirl-properties.bas─◻✕
' Tight spiral with many bands
bswirl_bands#(bsw#, 20)
bswirl_strength#(bsw#, 1.5)

' Wide, gentle swirl
bswirl_bands#(bsw#, 3)
bswirl_strength#(bsw#, 0.3)

' Elliptical swirl (stretched horizontally)
bswirl_aspect#(bsw#, 1.5)

' Reverse the swirl direction
bswirl_strength#(bsw#, -0.8)

Effect Control

Enabled

Toggles the effect on or off without destroying it. When disabled, the control renders as if the effect does not exist.

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

Trigger

The trigger property is a string used by FireMonkey’s animation system. Setting it starts the effect’s animation (if any). Primarily used for integration with animation components.

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

╯ toggle-effect.bas─◻✕
' Disable the effect (control renders normally)
bswirl_enabled#(bsw#, 0)

' Re-enable it
bswirl_enabled#(bsw#, 1)

' Check state
if bswirl_enabled(bsw#) = 1 then
    print "Banded swirl is active"
endif

Complete Examples

Basic Banded Swirl

Applies a 5-band swirl with moderate strength to an image.

╯ bswirl-basic.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let bsw# = Pointer#(0)

frm# = form#("Banded Swirl Demo", 400, 350)

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

' Create banded swirl effect
bsw# = bswirl#(img#)
bswirl_bands#(bsw#, 5)
bswirl_strength#(bsw#, 0.8)

form_show(frm#)

Interactive Strength Control

Uses a trackbar to adjust swirl strength from 0.0 to 2.0 in real time.

╯ bswirl-strength.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let bsw# = 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")

bsw# = bswirl#(img#)
bswirl_bands#(bsw#, 8)
bswirl_strength#(bsw#, 0)

' Strength slider
lblStr# = label#(frm#, "Strength: 0.00", 50, 200)
trkStr# = trackbar#(frm#)
trackbar_bounds#(trkStr#, 50, 230, 350, 30)
trackbar_max#(trkStr#, 100)
trackbar_value#(trkStr#, 0)
trackbar_onchange#(trkStr#, "OnStrChange")

form_show(frm#)

function OnStrChange(sender#) local s
  let s = trackbar_value(trkStr#) / 50
  bswirl_strength#(bsw#, s)
  label_text#(lblStr#, "Strength: " + stri$(s, 2))
endfunction

Toggle Effect On/Off

A button toggles the banded swirl effect without destroying it.

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

frm# = form#("Toggle Banded Swirl", 400, 300)

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

bsw# = bswirl#(img#)
bswirl_bands#(bsw#, 6)
bswirl_strength#(bsw#, 1.2)

btn# = button#(frm#, "Disable Effect")
button_bounds#(btn#, 140, 210, 120, 30)
button_onclick#(btn#, "Toggle")

form_show(frm#)

function Toggle(sender#)
  if isOn = 1 then
    bswirl_enabled#(bsw#, 0)
    isOn = 0
    button_text#(btn#, "Enable Effect")
  else
    bswirl_enabled#(bsw#, 1)
    isOn = 1
    button_text#(btn#, "Disable Effect")
  endif
endfunction

Best Practices

Practice	Why
Use `bswirl_enabled#` to toggle instead of `bswirl_free`	Avoids destroying and recreating the effect; better performance for on/off scenarios
Start with strength 0 and animate up	Creates a smooth “swirl in” transition effect
Keep bands between 3–15 for visible patterns	Very high band counts may look like noise; very low counts produce subtle warping
Combine with `FloatAnimationLib` for animated strength	Animate the strength property for pulsating or spinning effects
Use negative strength for reverse swirl	Useful for “unswirl” animations or directional variety
Adjust aspect ratio for non-square controls	Keeps the swirl looking circular on rectangular images
Check `bswirl_error()` after creation	Catches nil or invalid parent controls early
Compare with `SwirlEffectLib` for simpler needs	The plain swirl has no bands — choose based on visual complexity needed

Quick Reference

Function	Signature	Description
ERROR HANDLING
`bswirl_error()`	`bswirl_error@`	Last error code
`bswirl_errormsg$()`	`bswirl_errormsg$@`	Last error message
`bswirl_strerror$(code)`	`bswirl_strerror$@n`	Error code to text
`bswirl_clearerror()`	`bswirl_clearerror@`	Clear error state
CREATION & DESTRUCTION
`bswirl#(parent#)`	`bswirl#@#`	Create effect on control
`bswirl_free(effect#)`	`bswirl_free@#`	Destroy effect
CENTER POINT
`bswirl_centerx#(effect#, val)`	`bswirl_centerx#@#n`	Set center X (0.0–1.0)
`bswirl_centerx(effect#)`	`bswirl_centerx@#`	Get center X
`bswirl_centery#(effect#, val)`	`bswirl_centery#@#n`	Set center Y (0.0–1.0)
`bswirl_centery(effect#)`	`bswirl_centery@#`	Get center Y
SWIRL PROPERTIES
`bswirl_bands#(effect#, val)`	`bswirl_bands#@#n`	Set band count
`bswirl_bands(effect#)`	`bswirl_bands@#`	Get band count
`bswirl_strength#(effect#, val)`	`bswirl_strength#@#n`	Set swirl strength
`bswirl_strength(effect#)`	`bswirl_strength@#`	Get strength
`bswirl_aspect#(effect#, val)`	`bswirl_aspect#@#n`	Set aspect ratio
`bswirl_aspect(effect#)`	`bswirl_aspect@#`	Get aspect ratio
EFFECT CONTROL
`bswirl_enabled#(effect#, val)`	`bswirl_enabled#@#n`	Enable (1) / disable (0)
`bswirl_enabled(effect#)`	`bswirl_enabled@#`	Get enabled state
`bswirl_trigger#(effect#, str$)`	`bswirl_trigger#@#$`	Set trigger string
`bswirl_trigger$(effect#)`	`bswirl_trigger$@#`	Get trigger string

20 functions. Part of the Plan9Basic visual effects library system.