LineTransitionEffectLib — Plan9Basic Documentation

Overview

LineTransitionEffectLib provides a line sweep transition effect for Plan9Basic applets, wrapping the FireMonkey TLineTransitionEffect component. A line sweeps across the source image, progressively revealing the target image beneath. The direction and angle of the sweep are controlled by adjustable origin coordinates.

Property	Details
Library	`LineTransitionEffectLib`
Prefix	`linetrans_`
Wraps	`TLineTransitionEffect`
Functions	19
Type	Transition effect

Category	Count	Description
Creation / Destruction	2	Create and free effect
Progress	2	Get/set transition progress
Target Image	3	Set/get target bitmap, load from URL
Fuzzy Amount	2	Get/set edge softness
Origin Point	4	Get/set X and Y origin coordinates
Effect Control	2	Enable/disable effect
Error Handling	4	Error codes and messages

⚙ Classic Wipe Effect: The line transition is the most fundamental transition type in video editing — a straight line sweeps across the frame, revealing the next scene. By adjusting the origin point, you can achieve horizontal, vertical, and diagonal wipes.

Cross-Platform Support

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

Creation & Destruction

linetrans#(parent#)

Creates a new line 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

linetrans_free(effect#)

Destroys the effect and releases associated resources.

Parameter	Type	Description
`effect#`	Pointer	Effect handle to destroy

╯ create-line-transition.bas─◻✕
' Create a line transition effect
let trans# = linetrans#(img#)

' ... use the effect ...

' Clean up when done
linetrans_free(trans#)

Error Handling

All four standard error functions are available for detecting and diagnosing issues.

Function	Signature	Description
`linetrans_error()`	`linetrans_error@`	Returns last error code (0 = none)
`linetrans_errormsg$()`	`linetrans_errormsg$@`	Returns last error message
`linetrans_strerror$(code)`	`linetrans_strerror$@n`	Converts error code to text
`linetrans_clearerror()`	`linetrans_clearerror@`	Clears the error state

Code	Meaning
`0`	No error
`1`	Invalid effect handle
`2`	Invalid parameter value
`3`	Resource load failure

╯ error-handling.bas─◻✕
linetrans_loadtarget#(trans#, "target.png")
if linetrans_error() <> 0 then
  print "Error: " + linetrans_errormsg$()
  linetrans_clearerror()
endif

Progress

Controls how far the transition has advanced. At 0.0 the source image is fully visible; at 1.0 the target image is fully revealed.

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

Value	Description
`0.0`	Source image fully visible (no transition)
`0.5`	Half transitioned — line at midpoint
`1.0`	Target image fully revealed

Target Image

The target image is what gets revealed as the line sweeps across. You can assign a bitmap directly or load from a URL or file path.

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

📷 Quick Load: Use linetrans_loadtarget# to load images directly from a URL or file path without creating a separate bitmap object.

Fuzzy Amount

Controls the softness of the transition edge. A value of 0.0 produces a hard, crisp line while higher values create a smooth, feathered edge.

Function	Signature	Description
`linetrans_fuzzyamount#(effect#, value)`	`linetrans_fuzzyamount#@#n`	Sets edge softness (0.0–1.0)
`linetrans_fuzzyamount(effect#)`	`linetrans_fuzzyamount@#`	Gets fuzzy amount

Value	Description	Use Case
`0.0`	Hard edge — crisp line	Clean geometric wipe
`0.05`	Subtle softness	Professional transitions
`0.1–0.3`	Visible feathering	Smooth, elegant wipes
`0.5–1.0`	Very soft blend zone	Dreamy, gradual reveals

Origin Point

The origin point determines the direction from which the line sweeps. By combining different X and Y values, you can create wipes from any corner, edge, or angle.

Function	Signature	Description
`linetrans_originx#(effect#, value)`	`linetrans_originx#@#n`	Sets X origin (0.0–1.0)
`linetrans_originx(effect#)`	`linetrans_originx@#`	Gets X origin
`linetrans_originy#(effect#, value)`	`linetrans_originy#@#n`	Sets Y origin (0.0–1.0)
`linetrans_originy(effect#)`	`linetrans_originy@#`	Gets Y origin

OriginX	OriginY	Wipe Direction
`0.0`	`0.0`	From top-left corner (diagonal)
`1.0`	`0.0`	From top-right corner (diagonal)
`0.0`	`1.0`	From bottom-left corner (diagonal)
`1.0`	`1.0`	From bottom-right corner (diagonal)
`0.5`	`0.0`	From top center (horizontal wipe down)
`0.0`	`0.5`	From left center (vertical wipe right)
`1.0`	`0.5`	From right center (vertical wipe left)
`0.5`	`1.0`	From bottom center (horizontal wipe up)

🎨 Direction Tips: Setting both origins to 0.5 creates a center-outward wipe. Corner values (0 or 1) produce diagonal wipes. Edge-center values (0.5 on one axis) produce clean horizontal or vertical wipes.

Effect Control

Enable or disable the transition effect at runtime without destroying it.

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

Complete Examples

Example 1: Basic Line Transition

╯ basic-line-transition.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let trkProg# = Pointer#(0)
let lblProg# = Pointer#(0)

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

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

' Create line transition effect
trans# = linetrans#(img#)
linetrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")

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

Example 2: Animated Line Wipe

╯ animated-line-wipe.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 Line Wipe", 400, 350)

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

trans# = linetrans#(img#)
linetrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
linetrans_fuzzyamount#(trans#, 0.1)

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

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

form_show(frm#)

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

function Animate(sender#)
  progress = progress + 0.02
  linetrans_progress#(trans#, progress)

  if progress >= 1 then
    timer_enabled#(tmr#, 0)
    button_enabled#(btn#, 1)
  endif
endfunction

Example 3: Different Wipe Directions

╯ wipe-directions.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let trans# = Pointer#(0)
let trkProg# = Pointer#(0)
let lblProg# = Pointer#(0)
let lblDir# = Pointer#(0)

frm# = form#("Wipe Directions", 500, 450)

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

trans# = linetrans#(img#)
linetrans_loadtarget#(trans#, "https://picsum.photos/200/150?random=2")
linetrans_fuzzyamount#(trans#, 0.05)

' Progress control
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")

lblDir# = label#(frm#, "Direction: Top-Left", 30, 260)

' Direction buttons
let btn1# = button#(frm#, "Top-Left")
button_bounds#(btn1#, 30, 290, 100, 30)
button_onclick#(btn1#, "DirTopLeft")

let btn2# = button#(frm#, "Top-Right")
button_bounds#(btn2#, 140, 290, 100, 30)
button_onclick#(btn2#, "DirTopRight")

let btn3# = button#(frm#, "Bottom-Left")
button_bounds#(btn3#, 250, 290, 100, 30)
button_onclick#(btn3#, "DirBottomLeft")

let btn4# = button#(frm#, "Bottom-Right")
button_bounds#(btn4#, 360, 290, 100, 30)
button_onclick#(btn4#, "DirBottomRight")

' Set initial progress
linetrans_progress#(trans#, 0.5)

form_show(frm#)

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

function DirTopLeft(sender#)
  linetrans_originx#(trans#, 0)
  linetrans_originy#(trans#, 0)
  label_text#(lblDir#, "Direction: Top-Left")
endfunction

function DirTopRight(sender#)
  linetrans_originx#(trans#, 1)
  linetrans_originy#(trans#, 0)
  label_text#(lblDir#, "Direction: Top-Right")
endfunction

function DirBottomLeft(sender#)
  linetrans_originx#(trans#, 0)
  linetrans_originy#(trans#, 1)
  label_text#(lblDir#, "Direction: Bottom-Left")
endfunction

function DirBottomRight(sender#)
  linetrans_originx#(trans#, 1)
  linetrans_originy#(trans#, 1)
  label_text#(lblDir#, "Direction: Bottom-Right")
endfunction

Best Practices

Practice	Why
Match source and target image dimensions	Prevents visual artifacts at the transition boundary
Use small FuzzyAmount values (0.05–0.1)	Creates professional-looking transitions without excessive blur
Animate with 0.02 step increments	Produces smooth ~1.5 second transitions at 30ms intervals
Load target image before animating	Avoids blank frames during transition
Check errors after `loadtarget`	Catch missing files or network failures early
Disable buttons during animation	Prevents users from restarting mid-transition

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`linetrans#(parent#)`	`linetrans#@#`	Create effect
`linetrans_free(effect#)`	`linetrans_free@#`	Destroy effect
PROGRESS
`linetrans_progress#(effect#, value)`	`linetrans_progress#@#n`	Set progress
`linetrans_progress(effect#)`	`linetrans_progress@#`	Get progress
TARGET IMAGE
`linetrans_target#(effect#, bitmap#)`	`linetrans_target#@##`	Set target bitmap
`linetrans_target#(effect#)`	`linetrans_target#@#`	Get target bitmap
`linetrans_loadtarget#(effect#, url$)`	`linetrans_loadtarget#@#$`	Load target from URL/file
FUZZY AMOUNT
`linetrans_fuzzyamount#(effect#, value)`	`linetrans_fuzzyamount#@#n`	Set edge softness
`linetrans_fuzzyamount(effect#)`	`linetrans_fuzzyamount@#`	Get fuzzy amount
ORIGIN POINT
`linetrans_originx#(effect#, value)`	`linetrans_originx#@#n`	Set X origin
`linetrans_originx(effect#)`	`linetrans_originx@#`	Get X origin
`linetrans_originy#(effect#, value)`	`linetrans_originy#@#n`	Set Y origin
`linetrans_originy(effect#)`	`linetrans_originy@#`	Get Y origin
EFFECT CONTROL
`linetrans_enabled#(effect#, value)`	`linetrans_enabled#@#n`	Enable/disable
`linetrans_enabled(effect#)`	`linetrans_enabled@#`	Get enabled state
ERROR HANDLING
`linetrans_error()`	`linetrans_error@`	Last error code
`linetrans_errormsg$()`	`linetrans_errormsg$@`	Last error message
`linetrans_strerror$(code)`	`linetrans_strerror$@n`	Code to text
`linetrans_clearerror()`	`linetrans_clearerror@`	Clear error state

Library	Description
`BlindTransitionEffectLib`	Venetian blinds transition effect
`SlideTransitionEffectLib`	Sliding transition effect
`CircleTransitionEffectLib`	Circular wipe transition
`SwipeTransitionEffectLib`	Swipe transition effect