DirectionalBlurEffectLib — Plan9Basic Documentation

DirectionalBlurEffectLib — Motion Blur

Applies a GPU-accelerated directional (motion) blur along a specified angle, creating a convincing sense of speed, movement, or camera panning. Wraps FireMonkey’s TDirectionalBlurEffect. Unlike standard blur which softens equally in all directions, directional blur smears pixels along a single axis. 14 functions.

Category	Count	Description
Error Handling	4	dirblur_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	dirblur# (create), dirblur_free (destroy)
Properties	4	bluramount, angle (get/set)
Effect Control	4	enabled, trigger (get/set)

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
`dirblur_error()`	`dirblur_error@`	Returns last error code (0 = no error)
`dirblur_errormsg$()`	`dirblur_errormsg$@`	Returns last error message as string
`dirblur_strerror$(code)`	`dirblur_strerror$@n`	Converts an error code to descriptive text
`dirblur_clearerror()`	`dirblur_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 TDirectionalBlurEffect
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
`dirblur#(parent#)`	`dirblur#@#`	Creates a directional blur effect on the given control. Returns the effect pointer.
`dirblur_free(effect#)`	`dirblur_free@#`	Destroys the effect and removes it from the parent.

Blur Amount

Controls the intensity/length of the motion blur streak. Range is 0–10. Default is 0.1 (barely visible).

Function	Signature	Description
`dirblur_bluramount#(effect#, value)`	`dirblur_bluramount#@#n`	Sets blur amount (0–10)
`dirblur_bluramount(effect#)`	`dirblur_bluramount@#`	Gets current blur amount

Amount	Visual Effect	Use Case
0	No blur — sharp	Effect present but invisible
1–3	Subtle motion streak	Gentle panning, slight movement
4–7	Strong motion blur	Speed effect, fast movement
8–10	Extreme motion streak	Warp speed, dramatic emphasis

Angle

Sets the direction of the motion blur in degrees (0–360). The blur streaks pixels along this direction.

Function	Signature	Description
`dirblur_angle#(effect#, value)`	`dirblur_angle#@#n`	Sets angle in degrees (0–360)
`dirblur_angle(effect#)`	`dirblur_angle@#`	Gets current angle

Angle Direction Reference

╯ angle-compass─◻✕
              270° (Up)
                |
                |
  180° (Left) --+-- 0°/360° (Right)
                |
                |
              90° (Down)

Angle	Direction	Visual Metaphor
0°	Right (→)	Horizontal speed, racing
45°	Down-Right (↘)	Diagonal fall, swoosh
90°	Down (↓)	Falling, rain, vertical scroll
135°	Down-Left (↙)	Diagonal slash
180°	Left (←)	Reverse motion, rewind
270°	Up (↑)	Rising, upward motion

╯ angle-presets.bas─◻✕
' Horizontal speed (racing game)
dirblur_angle#(blur#, 0)
dirblur_bluramount#(blur#, 5)

' Falling rain
dirblur_angle#(blur#, 90)
dirblur_bluramount#(blur#, 3)

' Diagonal swoosh
dirblur_angle#(blur#, 45)
dirblur_bluramount#(blur#, 6)

Effect Control

Enabled

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

Trigger

Function	Signature	Description
`dirblur_trigger#(effect#, trigger$)`	`dirblur_trigger#@#$`	Sets trigger string
`dirblur_trigger$(effect#)`	`dirblur_trigger$@#`	Gets current trigger string

Complete Examples

Basic Horizontal Motion Blur

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

frm# = form#("Directional Blur Demo", 400, 350)

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

blur# = dirblur#(img#)
dirblur_bluramount#(blur#, 3)
dirblur_angle#(blur#, 0)

form_show(frm#)

Dual Slider — Amount + Angle

╯ dirblur-control.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let blur# = Pointer#(0)
let trkBlur# = Pointer#(0)
let trkAngle# = Pointer#(0)
let lblBlur# = Pointer#(0)
let lblAngle# = Pointer#(0)

frm# = form#("Motion Blur Control", 500, 420)

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

blur# = dirblur#(img#)
dirblur_bluramount#(blur#, 2)
dirblur_angle#(blur#, 0)

lblBlur# = label#(frm#, "Blur: 2.0", 30, 190)
trkBlur# = trackbar#(frm#)
trackbar_bounds#(trkBlur#, 30, 215, 440, 25)
trackbar_max#(trkBlur#, 100)
trackbar_value#(trkBlur#, 20)
trackbar_onchange#(trkBlur#, "OnBlurChange")

lblAngle# = label#(frm#, "Angle: 0", 30, 260)
trkAngle# = trackbar#(frm#)
trackbar_bounds#(trkAngle#, 30, 285, 440, 25)
trackbar_max#(trkAngle#, 360)
trackbar_value#(trkAngle#, 0)
trackbar_onchange#(trkAngle#, "OnAngleChange")

form_show(frm#)

function OnBlurChange(sender#) local b
  let b = trackbar_value(trkBlur#) / 10
  dirblur_bluramount#(blur#, b)
  label_text#(lblBlur#, "Blur: " + stri$(b, 1))
endfunction

function OnAngleChange(sender#) local a
  let a = trackbar_value(trkAngle#)
  dirblur_angle#(blur#, a)
  label_text#(lblAngle#, "Angle: " + str$(a))
endfunction

Rotating Motion Blur Animation

The blur direction rotates continuously, creating a spinning motion effect.

╯ dirblur-rotate.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let blur# = Pointer#(0)
let tmr# = Pointer#(0)
let btn# = Pointer#(0)
let lblAngle# = Pointer#(0)
let angle = 0
let running = 0

frm# = form#("Rotating Blur", 400, 350)

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

blur# = dirblur#(img#)
dirblur_bluramount#(blur#, 4)
dirblur_angle#(blur#, 0)

lblAngle# = label#(frm#, "Angle: 0", 160, 195)

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

btn# = button#(frm#, "Start Rotation")
button_bounds#(btn#, 140, 230, 120, 30)
button_onclick#(btn#, "ToggleRotation")

form_show(frm#)

function ToggleRotation(sender#)
  if running = 0 then
    running = 1
    timer_enabled#(tmr#, 1)
    button_text#(btn#, "Stop Rotation")
  else
    running = 0
    timer_enabled#(tmr#, 0)
    button_text#(btn#, "Start Rotation")
  endif
endfunction

function Rotate(sender#)
  angle = angle + 3
  if angle >= 360 then
    angle = angle - 360
  endif
  dirblur_angle#(blur#, angle)
  label_text#(lblAngle#, "Angle: " + str$(angle))
endfunction

Best Practices

Practice	Why
Use 0° for horizontal speed, 90° for vertical motion	Most intuitive motion directions for common scenarios
Blur amount 1–3 for subtle, 4–7 for dramatic	Higher values quickly become abstract
Animate angle for spinning/rotating motion	Rotating directional blur creates hypnotic effects
Animate blur amount 0 → N for acceleration effect	Ramp up motion blur to simulate increasing speed
Use on images for best results	Blur needs pixel variation to be visible on vector shapes
Combine with `FloatAnimationLib` for smooth transitions	Animate both angle and amount simultaneously
Use trigger `IsMouseOver=true` for hover motion	Interactive speed effect on mouse hover
Pair with `RadialBlurEffectLib` for zoom effects	Directional for linear motion, radial for zoom/spin

Quick Reference

Function	Signature	Description
ERROR HANDLING
`dirblur_error()`	`dirblur_error@`	Last error code
`dirblur_errormsg$()`	`dirblur_errormsg$@`	Last error message
`dirblur_strerror$(code)`	`dirblur_strerror$@n`	Error code to text
`dirblur_clearerror()`	`dirblur_clearerror@`	Clear error state
CREATION & DESTRUCTION
`dirblur#(parent#)`	`dirblur#@#`	Create effect on control
`dirblur_free(effect#)`	`dirblur_free@#`	Destroy effect
PROPERTIES
`dirblur_bluramount#(effect#, val)`	`dirblur_bluramount#@#n`	Set blur amount (0–10)
`dirblur_bluramount(effect#)`	`dirblur_bluramount@#`	Get blur amount
`dirblur_angle#(effect#, deg)`	`dirblur_angle#@#n`	Set angle (0–360°)
`dirblur_angle(effect#)`	`dirblur_angle@#`	Get angle
EFFECT CONTROL
`dirblur_enabled#(effect#, val)`	`dirblur_enabled#@#n`	Enable (1) / disable (0)
`dirblur_enabled(effect#)`	`dirblur_enabled@#`	Get enabled state
`dirblur_trigger#(effect#, str$)`	`dirblur_trigger#@#$`	Set trigger string
`dirblur_trigger$(effect#)`	`dirblur_trigger$@#`	Get trigger string

14 functions. Part of the Plan9Basic visual effects library system.