WaveEffectLib — Plan9Basic Documentation

Overview

WaveEffectLib creates a wave distortion effect simulating a rippling water surface, wrapping the FireMonkey TWaveEffect. Increment the Time property with a timer to animate the waves.

Property	Details
Library	`WaveEffectLib`
Prefix	`wave_`
Wraps	`TWaveEffect`
Functions	14
Type	Visual effect

🌊 Animated Waves: Increment Time using a timer for smooth wave animation. WaveSize controls distortion intensity — 32–50 for tight ripples, 128+ for large swells.

Cross-Platform Support

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

Creation & Destruction

wave#(parent#)

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

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

wave_free(effect#)

Destroys the effect and releases associated resources.

Error Handling

Function	Signature	Description
`wave_error()`	`wave_error@`	Returns last error code (0 = none)
`wave_errormsg$()`	`wave_errormsg$@`	Returns last error message
`wave_strerror$(code)`	`wave_strerror$@n`	Converts error code to text
`wave_clearerror()`	`wave_clearerror@`	Clears the error state

Wave Parameters

Function	Signature	Description
`wave_wavesize#(effect#, value)`	`wave_wavesize#@#n`	Set wave size (32–256)
`wave_wavesize(effect#)`	`wave_wavesize@#`	Get wave size
`wave_time#(effect#, value)`	`wave_time#@#n`	Set animation time phase
`wave_time(effect#)`	`wave_time@#`	Get time value

Size	Effect
`32–50`	Small, tight ripples
`64–100`	Medium waves (default 64)
`128–200`	Large, smooth swells
`200+`	Very large distortion

Effect Control

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

Complete Examples

Example: Animated Water Surface

╯ wave-anim.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let wav# = Pointer#(0)
let tmr# = Pointer#(0)
let waveTime = 0

frm# = form#("Animated Wave", 400, 340)
img# = image#(frm#)
image_bounds#(img#, 100, 40, 200, 150)
image_load#(img#, "https://picsum.photos/200/150")

wav# = wave#(img#)
wave_wavesize#(wav#, 64)

tmr# = timer#()
timer_interval#(tmr#, 50)
timer_ontimer#(tmr#, "OnTimer")

let btn1# = button#(frm#, "Start")
button_bounds#(btn1#, 80, 220, 100, 35)
button_onclick#(btn1#, "StartAnim")

let btn2# = button#(frm#, "Stop")
button_bounds#(btn2#, 200, 220, 100, 35)
button_onclick#(btn2#, "StopAnim")

form_show(frm#)

function OnTimer(sender#)
  waveTime = waveTime + 0.1
  wave_time#(wav#, waveTime)
endfunction

function StartAnim(sender#)
  timer_enabled#(tmr#, 1)
endfunction

function StopAnim(sender#)
  timer_enabled#(tmr#, 0)
endfunction

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`wave#(parent#)`	`wave#@#`	Create effect
`wave_free(effect#)`	`wave_free@#`	Destroy effect
WAVE PARAMETERS
`wave_wavesize#(effect#, value)`	`wave_wavesize#@#n`	Set wave size
`wave_wavesize(effect#)`	`wave_wavesize@#`	Get wave size
`wave_time#(effect#, value)`	`wave_time#@#n`	Set time phase
`wave_time(effect#)`	`wave_time@#`	Get time
EFFECT CONTROL
`wave_enabled#(effect#, value)`	`wave_enabled#@#n`	Enable/disable
`wave_enabled(effect#)`	`wave_enabled@#`	Get enabled
`wave_trigger#(effect#, trigger$)`	`wave_trigger#@#$`	Set trigger
`wave_trigger$(effect#)`	`wave_trigger$@#`	Get trigger
ERROR HANDLING
`wave_error()`	`wave_error@`	Last error code
`wave_errormsg$()`	`wave_errormsg$@`	Last error message
`wave_strerror$(code)`	`wave_strerror$@n`	Code to text
`wave_clearerror()`	`wave_clearerror@`	Clear error

Library	Description
`RippleEffectLib`	Circular ripple effect
`SwirlEffectLib`	Swirl distortion