SwirlEffectLib — Plan9Basic Documentation

Overview

SwirlEffectLib creates a swirl/twist distortion around a center point, wrapping the FireMonkey TSwirlEffect component. Pixels are rotated in a spiral pattern, with the rotation amount decreasing toward the edges — creating mesmerizing vortex effects.

Property	Details
Library	`SwirlEffectLib`
Prefix	`swirl_`
Wraps	`TSwirlEffect`
Functions	16
Type	Visual effect (distortion)

Category	Count	Description
Creation / Destruction	2	Create and free effect
Strength	2	Get/set swirl intensity
Center Position	4	Get/set X and Y center
Effect Control	4	Enabled and trigger get/set
Error Handling	4	Error codes and messages

🌀 Vortex Distortion: Positive strength spirals clockwise, negative counter-clockwise. Animate the strength with sin() for a mesmerizing pulsating swirl effect.

Cross-Platform Support

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

Creation & Destruction

swirl#(parent#)

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

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

swirl_free(effect#)

Destroys the effect and releases associated resources.

Error Handling

Function	Signature	Description
`swirl_error()`	`swirl_error@`	Returns last error code (0 = none)
`swirl_errormsg$()`	`swirl_errormsg$@`	Returns last error message
`swirl_strerror$(code)`	`swirl_strerror$@n`	Converts error code to text
`swirl_clearerror()`	`swirl_clearerror@`	Clears the error state

Strength

Controls the swirl intensity. The range is unbounded — larger absolute values create more dramatic spirals.

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

Value	Effect
`-3 to -1`	Strong counter-clockwise
`-0.5`	Gentle counter-clockwise
`0`	No swirl (original image)
`0.5`	Gentle clockwise (default)
`1 to 3`	Strong clockwise

Center Position

Sets the center point of the swirl using normalized coordinates (0–1).

Function	Signature	Description
`swirl_centerx#(effect#, value)`	`swirl_centerx#@#n`	Set X center (0–1)
`swirl_centerx(effect#)`	`swirl_centerx@#`	Get X center
`swirl_centery#(effect#, value)`	`swirl_centery#@#n`	Set Y center (0–1)
`swirl_centery(effect#)`	`swirl_centery@#`	Get Y center

Effect Control

Function	Signature	Description
`swirl_enabled#(effect#, value)`	`swirl_enabled#@#n`	Enable (1) or disable (0)
`swirl_enabled(effect#)`	`swirl_enabled@#`	Gets enabled state
`swirl_trigger#(effect#, trigger$)`	`swirl_trigger#@#$`	Sets trigger string
`swirl_trigger$(effect#)`	`swirl_trigger$@#`	Gets trigger string

Complete Examples

Example 1: Adjustable Swirl

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

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

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

swirl# = swirl#(img#)
swirl_strength#(swirl#, 0)

' Strength slider (-3 to +3)
lblStr# = label#(frm#, "Strength: 0.0", 180, 200)
trkStr# = trackbar#(frm#)
trackbar_bounds#(trkStr#, 50, 230, 350, 30)
trackbar_max#(trkStr#, 60)
trackbar_value#(trkStr#, 30)
trackbar_onchange#(trkStr#, "OnStrength")

form_show(frm#)

function OnStrength(sender#) local s
  let s = (trackbar_value(trkStr#) - 30) / 10
  swirl_strength#(swirl#, s)
  label_text#(lblStr#, "Strength: " + stri$(s, 1))
endfunction

Example 2: Animated Pulsating Swirl

╯ animated-swirl.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let swirl# = Pointer#(0)
let tmr# = Pointer#(0)
let btn# = Pointer#(0)
let strength = 0
let running = 0

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

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

swirl# = swirl#(img#)
swirl_strength#(swirl#, 0)

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

btn# = button#(frm#, "Start Swirl")
button_bounds#(btn#, 140, 210, 120, 30)
button_onclick#(btn#, "ToggleAnimation")

form_show(frm#)

function ToggleAnimation(sender#)
  if running = 0 then
    running = 1
    timer_enabled#(tmr#, 1)
    button_text#(btn#, "Stop Swirl")
  else
    running = 0
    timer_enabled#(tmr#, 0)
    button_text#(btn#, "Start Swirl")
  endif
endfunction

function Animate(sender#)
  strength = strength + 0.05
  swirl_strength#(swirl#, sin(strength) * 2)
endfunction

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`swirl#(parent#)`	`swirl#@#`	Create effect
`swirl_free(effect#)`	`swirl_free@#`	Destroy effect
STRENGTH
`swirl_strength#(effect#, value)`	`swirl_strength#@#n`	Set intensity
`swirl_strength(effect#)`	`swirl_strength@#`	Get strength
CENTER POSITION
`swirl_centerx#(effect#, value)`	`swirl_centerx#@#n`	Set X center (0–1)
`swirl_centerx(effect#)`	`swirl_centerx@#`	Get X center
`swirl_centery#(effect#, value)`	`swirl_centery#@#n`	Set Y center (0–1)
`swirl_centery(effect#)`	`swirl_centery@#`	Get Y center
EFFECT CONTROL
`swirl_enabled#(effect#, value)`	`swirl_enabled#@#n`	Enable/disable
`swirl_enabled(effect#)`	`swirl_enabled@#`	Get enabled state
`swirl_trigger#(effect#, trigger$)`	`swirl_trigger#@#$`	Set trigger
`swirl_trigger$(effect#)`	`swirl_trigger$@#`	Get trigger
ERROR HANDLING
`swirl_error()`	`swirl_error@`	Last error code
`swirl_errormsg$()`	`swirl_errormsg$@`	Last error message
`swirl_strerror$(code)`	`swirl_strerror$@n`	Code to text
`swirl_clearerror()`	`swirl_clearerror@`	Clear error state

Library	Description
`SwirlTransitionEffectLib`	Swirl-based transition
`RippleEffectLib`	Water ripple distortion
`PinchEffectLib`	Pinch/bulge distortion
`WaveEffectLib`	Wave distortion