RotateCrumpleTransitionEffectLib — Plan9Basic Documentation

Overview

RotateCrumpleTransitionEffectLib combines rotation and crumpling animations to transition between source and target images, wrapping the FireMonkey TRotateCrumpleTransitionEffect component. The effect creates a dynamic, paper-like crumpling with rotation — as if the image is being crumpled and twisted away to reveal the next scene.

Property	Details
Library	`RotateCrumpleTransitionEffectLib`
Prefix	`rotcrumpletrans_`
Wraps	`TRotateCrumpleTransitionEffect`
Functions	15
Type	Transition effect

Category	Count	Description
Creation / Destruction	2	Create and free effect
Target Image	3	Set/get/load target bitmap
Progress	2	Get/set transition progress
Random Seed	2	Get/set crumple pattern variation
Effect Control	2	Enabled get/set
Error Handling	4	Error codes and messages

🔄 Dynamic Paper Effect: This transition is one of the most dramatic — the source image appears to crumple and twist like a piece of paper being crushed, revealing the target beneath. Use the RandomSeed property to vary the crumple pattern for unique transitions each time.

Cross-Platform Support

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

Creation & Destruction

rotcrumpletrans#(parent#)

Creates a new rotate crumple transition effect attached to the specified visual control.

Parameter	Type	Description
`parent#`	Pointer	Target visual control (e.g., image)
Returns	Pointer	Effect handle, or 0 on failure

rotcrumpletrans_free(effect#)

Destroys the effect and releases associated resources.

Error Handling

Function	Signature	Description
`rotcrumpletrans_error()`	`rotcrumpletrans_error@`	Returns last error code (0 = none)
`rotcrumpletrans_errormsg$()`	`rotcrumpletrans_errormsg$@`	Returns last error message
`rotcrumpletrans_strerror$(code)`	`rotcrumpletrans_strerror$@n`	Converts error code to text
`rotcrumpletrans_clearerror()`	`rotcrumpletrans_clearerror@`	Clears the error state

Target Image

Function	Signature	Description
`rotcrumpletrans_target#(effect#, bitmap#)`	`rotcrumpletrans_target#@##`	Sets target from bitmap pointer
`rotcrumpletrans_target#(effect#)`	`rotcrumpletrans_target#@#`	Gets target bitmap pointer
`rotcrumpletrans_loadtarget#(effect#, url$)`	`rotcrumpletrans_loadtarget#@#$`	Loads target from URL or file

⚠ Target Required: Transition effects need a target image to work properly. Always load a target before animating.

Progress

Function	Signature	Description
`rotcrumpletrans_progress#(effect#, value)`	`rotcrumpletrans_progress#@#n`	Set progress (0.0–1.0)
`rotcrumpletrans_progress(effect#)`	`rotcrumpletrans_progress@#`	Get current progress

Value	Visual State
`0.0`	Source image (no distortion)
`0.3`	Source begins crumpling and rotating
`0.5`	Peak crumple/rotation (midpoint)
`0.7`	Target emerging from crumpled fragments
`1.0`	Target image (fully resolved)

Random Seed

Controls the crumple pattern variation. Different seed values produce different crumple shapes and rotation patterns, allowing unique transitions each time.

Function	Signature	Description
`rotcrumpletrans_randomseed#(effect#, value)`	`rotcrumpletrans_randomseed#@#n`	Set random seed
`rotcrumpletrans_randomseed(effect#)`	`rotcrumpletrans_randomseed@#`	Get random seed

Effect Control

Function	Signature	Description
`rotcrumpletrans_enabled#(effect#, value)`	`rotcrumpletrans_enabled#@#n`	Enable (1) or disable (0)
`rotcrumpletrans_enabled(effect#)`	`rotcrumpletrans_enabled@#`	Gets enabled state

Complete Examples

Example 1: Slider-Controlled Transition

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

frm# = form#("Rotate 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# = rotcrumpletrans#(img#)
rotcrumpletrans_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
  rotcrumpletrans_progress#(trans#, p)
  label_text#(lblProg#, "Progress: " + stri$(p, 2))
endfunction

Example 2: Animated Transition

╯ animated-rotcrumple.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 Rotate Crumple", 400, 350)

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

trans# = rotcrumpletrans#(img#)
rotcrumpletrans_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#, "StartTransition")

form_show(frm#)

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

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

Example 3: Random Seed Variation

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

frm# = form#("Crumple Pattern Variation", 450, 400)

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

trans# = rotcrumpletrans#(img#)
rotcrumpletrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
rotcrumpletrans_progress#(trans#, 0.5)

lblSeed# = label#(frm#, "Random Seed: 0", 50, 200)
trkSeed# = trackbar#(frm#)
trackbar_bounds#(trkSeed#, 50, 230, 350, 30)
trackbar_max#(trkSeed#, 100)
trackbar_value#(trkSeed#, 0)
trackbar_onchange#(trkSeed#, "OnSeed")

form_show(frm#)

function OnSeed(sender#) local s
  let s = trackbar_value(trkSeed#)
  rotcrumpletrans_randomseed#(trans#, s)
  label_text#(lblSeed#, "Random Seed: " + str$(s))
endfunction

Best Practices

Practice	Why
Always load a target image before animating	Transitions need a target to reveal
Change RandomSeed for variety	Same seed always produces the same crumple pattern
Use slower progress (0.01–0.02 per tick)	The crumple+rotate is complex; slower animation shows detail
Compare with CrumpleTransition	CrumpleTransition crumples without rotation — choose based on desired drama level

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`rotcrumpletrans#(parent#)`	`rotcrumpletrans#@#`	Create effect
`rotcrumpletrans_free(effect#)`	`rotcrumpletrans_free@#`	Destroy effect
TARGET IMAGE
`rotcrumpletrans_target#(effect#, bitmap#)`	`rotcrumpletrans_target#@##`	Set target bitmap
`rotcrumpletrans_target#(effect#)`	`rotcrumpletrans_target#@#`	Get target bitmap
`rotcrumpletrans_loadtarget#(effect#, url$)`	`rotcrumpletrans_loadtarget#@#$`	Load target from URL/file
PROGRESS
`rotcrumpletrans_progress#(effect#, value)`	`rotcrumpletrans_progress#@#n`	Set progress (0–1)
`rotcrumpletrans_progress(effect#)`	`rotcrumpletrans_progress@#`	Get progress
RANDOM SEED
`rotcrumpletrans_randomseed#(effect#, value)`	`rotcrumpletrans_randomseed#@#n`	Set crumple pattern
`rotcrumpletrans_randomseed(effect#)`	`rotcrumpletrans_randomseed@#`	Get seed value
EFFECT CONTROL
`rotcrumpletrans_enabled#(effect#, value)`	`rotcrumpletrans_enabled#@#n`	Enable/disable
`rotcrumpletrans_enabled(effect#)`	`rotcrumpletrans_enabled@#`	Get enabled state
ERROR HANDLING
`rotcrumpletrans_error()`	`rotcrumpletrans_error@`	Last error code
`rotcrumpletrans_errormsg$()`	`rotcrumpletrans_errormsg$@`	Last error message
`rotcrumpletrans_strerror$(code)`	`rotcrumpletrans_strerror$@n`	Code to text
`rotcrumpletrans_clearerror()`	`rotcrumpletrans_clearerror@`	Clear error state

Library	Description
`CrumpleTransitionEffectLib`	Basic crumple transition (no rotation)
`BloodTransitionEffectLib`	Dramatic drip transition
`DissolveTransitionEffectLib`	Random dissolve transition