RippleEffectLib — Plan9Basic Documentation

Overview

RippleEffectLib creates a water ripple distortion emanating from a center point, wrapping the FireMonkey TRippleEffect component. With controllable amplitude, frequency, and phase, you can create static ripple patterns or animate them for realistic water surface effects.

Property	Details
Library	`RippleEffectLib`
Prefix	`ripple_`
Wraps	`TRippleEffect`
Functions	22
Type	Visual effect (distortion)

Category	Count	Description
Creation / Destruction	2	Create and free effect
Amplitude	2	Get/set wave height
Frequency	2	Get/set wave count
Phase	2	Get/set wave phase (animate this!)
Aspect Ratio	2	Get/set ripple shape
Center Position	4	Get/set X,Y center (0–1)
Effect Control	4	Enabled and trigger get/set
Error Handling	4	Error codes and messages

🌊 Animated Water: The key to realistic water ripples is animating the Phase property with a timer. Incrementing phase each tick makes the ripples appear to propagate outward from the center — just like a stone dropped in a pond.

Cross-Platform Support

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

Creation & Destruction

ripple#(parent#)

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

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

ripple_free(effect#)

Destroys the effect and releases associated resources.

Error Handling

Function	Signature	Description
`ripple_error()`	`ripple_error@`	Returns last error code (0 = none)
`ripple_errormsg$()`	`ripple_errormsg$@`	Returns last error message
`ripple_strerror$(code)`	`ripple_strerror$@n`	Converts error code to text
`ripple_clearerror()`	`ripple_clearerror@`	Clears the error state

Amplitude

Controls the height/strength of the ripple waves. Higher values create more dramatic distortion.

Function	Signature	Description
`ripple_amplitude#(effect#, value)`	`ripple_amplitude#@#n`	Set wave height
`ripple_amplitude(effect#)`	`ripple_amplitude@#`	Get amplitude

Value	Effect
`0.01–0.03`	Subtle ripple (calm water)
`0.05–0.1`	Moderate ripple (default range)
`0.15–0.3`	Strong distortion (turbulent water)

Frequency

Controls the number of ripple rings. Higher values create more, tighter concentric rings.

Function	Signature	Description
`ripple_frequency#(effect#, value)`	`ripple_frequency#@#n`	Set wave count
`ripple_frequency(effect#)`	`ripple_frequency@#`	Get frequency

Phase

Controls the wave phase offset. Animate this property with a timer to create moving ripples.

Function	Signature	Description
`ripple_phase#(effect#, value)`	`ripple_phase#@#n`	Set wave phase
`ripple_phase(effect#)`	`ripple_phase@#`	Get phase

🔄 Animation Tip: Increment phase by 1 each timer tick (at ~30ms intervals) for smooth outward-propagating ripples.

Aspect Ratio

Controls the width-to-height ratio of the ripple rings. Values > 1.0 stretch horizontally; values < 1.0 stretch vertically.

Function	Signature	Description
`ripple_aspectratio#(effect#, value)`	`ripple_aspectratio#@#n`	Set aspect ratio
`ripple_aspectratio(effect#)`	`ripple_aspectratio@#`	Get aspect ratio

Center Position

Normalized coordinates (0–1) specifying where the ripples emanate from.

Function	Signature	Description
`ripple_centerx#(effect#, value)`	`ripple_centerx#@#n`	Set X center (0=left, 1=right)
`ripple_centerx(effect#)`	`ripple_centerx@#`	Get X center
`ripple_centery#(effect#, value)`	`ripple_centery#@#n`	Set Y center (0=top, 1=bottom)
`ripple_centery(effect#)`	`ripple_centery@#`	Get Y center

Effect Control

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

Complete Examples

Example 1: Animated Water Ripple

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

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

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

ripple# = ripple#(img#)
ripple_amplitude#(ripple#, 0.03)
ripple_frequency#(ripple#, 40)

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

btn# = button#(frm#, "Start Animation")
button_bounds#(btn#, 130, 210, 140, 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 Animation")
  else
    running = 0
    timer_enabled#(tmr#, 0)
    button_text#(btn#, "Start Animation")
  endif
endfunction

function Animate(sender#)
  phase = phase + 1
  ripple_phase#(ripple#, phase)
endfunction

Example 2: Adjustable Ripple Parameters

╯ ripple-control.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let ripple# = Pointer#(0)
let trkAmp# = Pointer#(0)
let trkFreq# = Pointer#(0)
let lblAmp# = Pointer#(0)
let lblFreq# = Pointer#(0)

frm# = form#("Ripple Control", 500, 450)

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

ripple# = ripple#(img#)
ripple_amplitude#(ripple#, 0.05)
ripple_frequency#(ripple#, 50)

lblAmp# = label#(frm#, "Amplitude: 0.05", 30, 190)
trkAmp# = trackbar#(frm#)
trackbar_bounds#(trkAmp#, 30, 215, 440, 25)
trackbar_max#(trkAmp#, 100)
trackbar_value#(trkAmp#, 5)
trackbar_onchange#(trkAmp#, "OnAmplitude")

lblFreq# = label#(frm#, "Frequency: 50", 30, 260)
trkFreq# = trackbar#(frm#)
trackbar_bounds#(trkFreq#, 30, 285, 440, 25)
trackbar_max#(trkFreq#, 100)
trackbar_value#(trkFreq#, 50)
trackbar_onchange#(trkFreq#, "OnFrequency")

form_show(frm#)

function OnAmplitude(sender#) local a
  let a = trackbar_value(trkAmp#) / 100
  ripple_amplitude#(ripple#, a)
  label_text#(lblAmp#, "Amplitude: " + stri$(a, 2))
endfunction

function OnFrequency(sender#) local f
  let f = trackbar_value(trkFreq#)
  ripple_frequency#(ripple#, f)
  label_text#(lblFreq#, "Frequency: " + str$(f))
endfunction

Example 3: Basic Static Ripple

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

frm# = form#("Ripple Effect Demo", 400, 350)

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

ripple# = ripple#(img#)
ripple_amplitude#(ripple#, 0.05)
ripple_frequency#(ripple#, 50)

form_show(frm#)

Best Practices

Practice	Why
Animate Phase for moving ripples	Static ripples look frozen; animation adds realism
Use low amplitude (0.01–0.05) for subtle effects	High amplitude distorts image excessively
Frequency 30–70 works well for most images	Creates visible but not overcrowded ring pattern
Increment phase by 1 per 30ms tick	Smooth, natural-looking ripple propagation
Combine with RippleTransition for scene changes	Consistent ripple aesthetic across effects and transitions

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`ripple#(parent#)`	`ripple#@#`	Create effect
`ripple_free(effect#)`	`ripple_free@#`	Destroy effect
AMPLITUDE
`ripple_amplitude#(effect#, value)`	`ripple_amplitude#@#n`	Set wave height
`ripple_amplitude(effect#)`	`ripple_amplitude@#`	Get amplitude
FREQUENCY
`ripple_frequency#(effect#, value)`	`ripple_frequency#@#n`	Set wave count
`ripple_frequency(effect#)`	`ripple_frequency@#`	Get frequency
PHASE
`ripple_phase#(effect#, value)`	`ripple_phase#@#n`	Set phase (animate!)
`ripple_phase(effect#)`	`ripple_phase@#`	Get phase
ASPECT RATIO
`ripple_aspectratio#(effect#, value)`	`ripple_aspectratio#@#n`	Set aspect ratio
`ripple_aspectratio(effect#)`	`ripple_aspectratio@#`	Get aspect ratio
CENTER POSITION
`ripple_centerx#(effect#, value)`	`ripple_centerx#@#n`	Set X center (0–1)
`ripple_centerx(effect#)`	`ripple_centerx@#`	Get X center
`ripple_centery#(effect#, value)`	`ripple_centery#@#n`	Set Y center (0–1)
`ripple_centery(effect#)`	`ripple_centery@#`	Get Y center
EFFECT CONTROL
`ripple_enabled#(effect#, value)`	`ripple_enabled#@#n`	Enable/disable
`ripple_enabled(effect#)`	`ripple_enabled@#`	Get enabled state
`ripple_trigger#(effect#, trigger$)`	`ripple_trigger#@#$`	Set trigger
`ripple_trigger$(effect#)`	`ripple_trigger$@#`	Get trigger
ERROR HANDLING
`ripple_error()`	`ripple_error@`	Last error code
`ripple_errormsg$()`	`ripple_errormsg$@`	Last error message
`ripple_strerror$(code)`	`ripple_strerror$@n`	Code to text
`ripple_clearerror()`	`ripple_clearerror@`	Clear error state

Library	Description
`RippleTransitionEffectLib`	Ripple-based image transition
`SwirlEffectLib`	Swirl/twist distortion
`WaveEffectLib`	Wave distortion
`WaterTransitionEffectLib`	Water-drop transition