CrumpleTransitionEffectLib — Plan9Basic Documentation

CrumpleTransitionEffectLib — Crumple Transition

Simulates paper being crumpled as it transitions from a source image to a target image. Creates an organic, chaotic distortion where parts of both images appear crumpled and interwoven during the transition. Wraps FireMonkey’s TCrumpleTransitionEffect. Ideal for dramatic scene changes, artistic transitions, and playful UI effects. 15 functions.

Category	Count	Description
Error Handling	4	crumpletrans_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	crumpletrans# (create), crumpletrans_free (destroy)
Target Image	3	target (get/set), loadtarget
Progress & Seed	4	progress, randomseed (get/set)
Effect Control	2	enabled (get/set)

⚠ Target Required: Transition effects need a target image to transition to. Without a target, the effect transitions to transparent/empty. Always load or set a target before animating progress.

How Transitions Work

All transition effects in Plan9Basic follow the same pattern: a source image (the parent control) transitions to a target image as the progress value moves from 0.0 to 1.0.

Progress	What You See
0.0	100% source image (no transition)
0.25	Crumple distortion begins — source starts warping
0.5	Peak crumple — both images heavily distorted and mixed
0.75	Crumple resolving — target image emerging
1.0	100% target image (transition complete)

ⓘ RandomSeed: The randomseed property changes the crumple distortion pattern. Different seeds produce completely different crumple shapes. Set the seed before starting the animation for consistent results.

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

Function	Signature	Description
`crumpletrans_error()`	`crumpletrans_error@`	Returns last error code (0 = no error)
`crumpletrans_errormsg$()`	`crumpletrans_errormsg$@`	Returns last error message as string
`crumpletrans_strerror$(code)`	`crumpletrans_strerror$@n`	Converts an error code to descriptive text
`crumpletrans_clearerror()`	`crumpletrans_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 TCrumpleTransitionEffect
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
`crumpletrans#(parent#)`	`crumpletrans#@#`	Creates a crumple transition effect on the given control. Returns the effect pointer.
`crumpletrans_free(effect#)`	`crumpletrans_free@#`	Destroys the effect and removes it from the parent.

Target Image

The target is the image to transition to. The source (parent control’s current texture) transitions toward this target as progress increases.

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

╯ target.bas─◻✕
' Load target from URL (easiest method)
crumpletrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")

' Or load from local file
crumpletrans_loadtarget#(trans#, "photos/sunset.jpg")

Progress

Controls how far through the transition we are. Animate from 0.0 to 1.0 for the full crumple effect.

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

Random Seed

Changes the crumple distortion pattern. Different seed values produce different crumple shapes. Set before starting the animation for consistent, reproducible results.

Function	Signature	Description
`crumpletrans_randomseed#(effect#, value)`	`crumpletrans_randomseed#@#n`	Sets random seed (0.0–1.0)
`crumpletrans_randomseed(effect#)`	`crumpletrans_randomseed@#`	Gets current seed

Effect Control

Function	Signature	Description
`crumpletrans_enabled#(effect#, value)`	`crumpletrans_enabled#@#n`	Enables (1) or disables (0)
`crumpletrans_enabled(effect#)`	`crumpletrans_enabled@#`	Gets enabled state

Complete Examples

Slider-Controlled Crumple

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

frm# = form#("Crumple Transition", 450, 400)

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

trans# = crumpletrans#(img#)
crumpletrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")

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

Animated Crumple with Timer

╯ crumple-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

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

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

trans# = crumpletrans#(img#)
crumpletrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")

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

btn# = button#(frm#, "Crumple!")
button_bounds#(btn#, 150, 210, 100, 30)
button_onclick#(btn#, "StartCrumple")

form_show(frm#)

function StartCrumple(sender#)
  progress = 0
  timer_enabled#(tmr#, 1)
  button_enabled#(btn#, 0)
endfunction

function Animate(sender#)
  progress = progress + 0.02
  crumpletrans_progress#(trans#, progress)
  if progress >= 1 then
    timer_enabled#(tmr#, 0)
    button_enabled#(btn#, 1)
  endif
endfunction

Dual Sliders — Progress + Random Seed

╯ crumple-patterns.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let trkProg# = Pointer#(0)
let trkSeed# = Pointer#(0)
let lblProg# = Pointer#(0)
let lblSeed# = Pointer#(0)

frm# = form#("Crumple Patterns", 500, 420)

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

trans# = crumpletrans#(img#)
crumpletrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
crumpletrans_progress#(trans#, 0.5)

lblProg# = label#(frm#, "Progress: 0.50", 30, 190)
trkProg# = trackbar#(frm#)
trackbar_bounds#(trkProg#, 30, 215, 440, 25)
trackbar_max#(trkProg#, 100)
trackbar_value#(trkProg#, 50)
trackbar_onchange#(trkProg#, "OnProgress")

lblSeed# = label#(frm#, "Random Seed: 0.00", 30, 260)
trkSeed# = trackbar#(frm#)
trackbar_bounds#(trkSeed#, 30, 285, 440, 25)
trackbar_max#(trkSeed#, 100)
trackbar_value#(trkSeed#, 0)
trackbar_onchange#(trkSeed#, "OnSeed")

form_show(frm#)

function OnProgress(sender#) local p
  let p = trackbar_value(trkProg#) / 100
  crumpletrans_progress#(trans#, p)
  label_text#(lblProg#, "Progress: " + stri$(p, 2))
endfunction

function OnSeed(sender#) local s
  let s = trackbar_value(trkSeed#) / 100
  crumpletrans_randomseed#(trans#, s)
  label_text#(lblSeed#, "Random Seed: " + stri$(s, 2))
endfunction

Best Practices

Practice	Why
Always load a target image before animating	Without a target, the effect transitions to transparent/empty
Use `loadtarget#` for simplest target loading	Handles URL and file paths automatically
Set random seed before starting animation	Changing seed mid-transition produces jarring jumps
Animate at ~30ms timer interval for smooth crumple	~33 FPS gives smooth paper-like distortion
Use step size of 0.02 per frame for ~1.5s transition	50 frames × 30ms = ~1.5 second crumple
Disable button during animation	Prevents starting multiple overlapping transitions
Try different random seeds for variety	Each seed creates a unique crumple distortion pattern
Combine with `RotateCrumpleTransitionEffectLib`	Adds rotation to the crumple for even more dramatic effect

Quick Reference

Function	Signature	Description
ERROR HANDLING
`crumpletrans_error()`	`crumpletrans_error@`	Last error code
`crumpletrans_errormsg$()`	`crumpletrans_errormsg$@`	Last error message
`crumpletrans_strerror$(code)`	`crumpletrans_strerror$@n`	Error code to text
`crumpletrans_clearerror()`	`crumpletrans_clearerror@`	Clear error state
CREATION & DESTRUCTION
`crumpletrans#(parent#)`	`crumpletrans#@#`	Create effect on control
`crumpletrans_free(effect#)`	`crumpletrans_free@#`	Destroy effect
TARGET IMAGE
`crumpletrans_target#(effect#, bmp#)`	`crumpletrans_target#@##`	Set target bitmap
`crumpletrans_target#(effect#)`	`crumpletrans_target#@#`	Get target bitmap
`crumpletrans_loadtarget#(effect#, url$)`	`crumpletrans_loadtarget#@#$`	Load target from URL/file
PROGRESS & SEED
`crumpletrans_progress#(effect#, val)`	`crumpletrans_progress#@#n`	Set progress (0.0–1.0)
`crumpletrans_progress(effect#)`	`crumpletrans_progress@#`	Get progress
`crumpletrans_randomseed#(effect#, val)`	`crumpletrans_randomseed#@#n`	Set seed (0.0–1.0)
`crumpletrans_randomseed(effect#)`	`crumpletrans_randomseed@#`	Get seed
EFFECT CONTROL
`crumpletrans_enabled#(effect#, val)`	`crumpletrans_enabled#@#n`	Enable (1) / disable (0)
`crumpletrans_enabled(effect#)`	`crumpletrans_enabled@#`	Get enabled state

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