BlurEffectLib — Plan9Basic Documentation

BlurEffectLib — Standard Blur Effect

Applies a GPU-accelerated blur effect to any visual control, softening the image by averaging neighboring pixels. The effect wraps FireMonkey’s TBlurEffect with a single softness property that controls blur intensity from sharp to heavily diffused. Useful for depth-of-field simulation, frosted glass overlays, focus/unfocus transitions, and privacy masking. 12 functions.

Category	Count	Description
Error Handling	4	blur_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	blur# (create), blur_free (destroy)
Softness	2	softness (get/set)
Effect Control	4	enabled, trigger (get/set)

ⓘ Effect Ownership: The effect is owned by its parent control, not managed by garbage collection. Destroying the parent also destroys the effect. Use blur_free only to remove the effect while keeping the parent alive.

Blur Type Comparison

Plan9Basic offers several blur libraries. Choose based on your needs:

Library	Algorithm	Speed	Quality	Best For
BlurEffectLib	Standard	Fast	Good	General-purpose blur, UI overlays
BoxBlurEffectLib	Box average	Fastest	Fair	Performance-critical, quick previews
GaussianBlurEffectLib	Gaussian	Moderate	Best	Photography, smooth gradients
DirectionalBlurEffectLib	Motion	Fast	Good	Speed/motion effects
RadialBlurEffectLib	Radial	Moderate	Good	Zoom/spin motion effects

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

All functions set an error code on failure. Check with blur_error() after operations.

Function	Signature	Description
`blur_error()`	`blur_error@`	Returns last error code (0 = no error)
`blur_errormsg$()`	`blur_errormsg$@`	Returns last error message as string
`blur_strerror$(code)`	`blur_strerror$@n`	Converts an error code to descriptive text
`blur_clearerror()`	`blur_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 TBlurEffect
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
`blur#(parent#)`	`blur#@#`	Creates a blur effect attached to the given control. Returns the effect pointer.
`blur_free(effect#)`	`blur_free@#`	Destroys the effect and removes it from the parent control.

The effect is created with default softness of 0.4 (slight blur).

Softness

Controls the intensity of the blur. Higher values produce a more diffused, out-of-focus appearance. Default is 0.4. Range is 0.0–3.0.

Function	Signature	Description
`blur_softness#(effect#, value)`	`blur_softness#@#n`	Sets blur softness (0.0–3.0)
`blur_softness(effect#)`	`blur_softness@#`	Gets current softness

Softness	Visual Effect	Use Case
0.0	No blur — perfectly sharp	Blur disabled without removing effect
0.1–0.4	Slight softening (default range)	Subtle soft-focus, anti-aliasing
0.5–1.0	Moderate blur, clearly visible	Depth of field, background defocus
1.0–2.0	Heavy blur, details lost	Frosted glass, privacy masking
2.0–3.0	Maximum diffusion	Abstract backgrounds, dramatic effect

╯ softness.bas─◻✕
' Subtle soft focus
blur_softness#(blur#, 0.4)

' Frosted glass
blur_softness#(blur#, 1.5)

' Maximum diffusion
blur_softness#(blur#, 3.0)

let s = blur_softness(blur#)
print "Softness: " + stri$(s, 1)

Effect Control

Enabled

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

Trigger

The trigger property integrates with FireMonkey’s animation system. Common triggers include IsMouseOver=true for hover blur effects.

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

╯ trigger.bas─◻✕
' Blur activates on mouse hover
blur_trigger#(blur#, "IsMouseOver=true")

Complete Examples

Simple Blur on Rectangle

╯ blur-basic.bas─◻✕
let frm# = form#("Simple Blur", 400, 300)

let rect# = rectangle#(frm#)
rectangle_bounds#(rect#, 100, 75, 200, 150)
rectangle_fill#(rect#, "DodgerBlue")
rectangle_cornerradius#(rect#, 10, 10)

let lbl# = label#(rect#, "Blurred Box", 50, 60)

let blur# = blur#(rect#)
blur_softness#(blur#, 1.5)

form_show(frm#)

Toggle Blur with Button

╯ blur-toggle.bas─◻✕
let frm# = form#("Toggle Blur", 400, 350)

let rect# = rectangle#(frm#)
rectangle_bounds#(rect#, 100, 50, 200, 150)
rectangle_fill#(rect#, "Green")

let blur# = blur#(rect#)
blur_softness#(blur#, 2.0)
blur_enabled#(blur#, 0)  ' Start disabled

let btn# = button#(frm#, "Enable Blur")
button_bounds#(btn#, 150, 230, 100, 30)
button_onclick#(btn#, "OnToggle")

form_show(frm#)

function OnToggle(sender#) local isOn
  isOn = blur_enabled(blur#)
  if isOn = 1 then
    blur_enabled#(blur#, 0)
    button_text#(btn#, "Enable Blur")
  else
    blur_enabled#(blur#, 1)
    button_text#(btn#, "Disable Blur")
  endif
endfunction

Animated Blur In/Out

Uses FloatAnimationLib to smoothly animate blur softness for a focus/unfocus transition.

╯ blur-animated.bas─◻✕
let frm# = form#("Animated Blur", 400, 300)

let rect# = rectangle#(frm#)
rectangle_bounds#(rect#, 50, 50, 300, 150)
rectangle_fill#(rect#, "Purple")

let blur# = blur#(rect#)
blur_softness#(blur#, 0.0)

let btnBlur# = button#(frm#, "Blur In")
button_bounds#(btnBlur#, 50, 220, 80, 30)
button_onclick#(btnBlur#, "OnBlurIn")

let btnClear# = button#(frm#, "Blur Out")
button_bounds#(btnClear#, 140, 220, 80, 30)
button_onclick#(btnClear#, "OnBlurOut")

form_show(frm#)

function OnBlurIn(sender#) local ani#
  ani# = floatani#(blur#)
  floatani_propertyname#(ani#, "Softness")
  floatani_startvalue#(ani#, 0.0)
  floatani_stopvalue#(ani#, 3.0)
  floatani_duration#(ani#, 1.0)
  floatani_start(ani#)
endfunction

function OnBlurOut(sender#) local ani#
  ani# = floatani#(blur#)
  floatani_propertyname#(ani#, "Softness")
  floatani_startfromcurrent#(ani#, 1)
  floatani_stopvalue#(ani#, 0.0)
  floatani_duration#(ani#, 1.0)
  floatani_start(ani#)
endfunction

Hover Blur Using Trigger

The blur activates only when the mouse hovers over the control.

╯ blur-hover.bas─◻✕
let frm# = form#("Hover Blur", 500, 300)

let rect1# = rectangle#(frm#)
rectangle_bounds#(rect1#, 50, 80, 180, 120)
rectangle_fill#(rect1#, "Red")
let lbl1# = label#(rect1#, "Hover = Blur", 40, 45)

let blur1# = blur#(rect1#)
blur_softness#(blur1#, 2.5)
blur_trigger#(blur1#, "IsMouseOver=true")

let rect2# = rectangle#(frm#)
rectangle_bounds#(rect2#, 270, 80, 180, 120)
rectangle_fill#(rect2#, "Blue")
let lbl2# = label#(rect2#, "No Trigger", 45, 45)

form_show(frm#)

Best Practices

Practice	Why
Keep softness ≤ 2.0 on mobile devices	Heavy blur (>2.0) may reduce frame rate on older mobile GPUs
Use `blur_enabled#` to toggle, not `blur_free`	Faster than destroy/recreate for on/off scenarios
Animate softness with `FloatAnimationLib`	Smooth focus/unfocus transitions feel polished and cinematic
Use triggers for hover blur	`IsMouseOver=true` creates interactive blur without code
Combine with opacity for frosted glass	Semi-transparent control + blur = modern frosted glass overlay
Use `BoxBlurEffectLib` for faster blur	Box blur is computationally cheaper if quality is less important
Use `GaussianBlurEffectLib` for smoother blur	Gaussian produces the smoothest result for photography
Multiple effects stack sequentially	Blur + Bloom + Shadow all process on the same control in order

Quick Reference

Function	Signature	Description
ERROR HANDLING
`blur_error()`	`blur_error@`	Last error code
`blur_errormsg$()`	`blur_errormsg$@`	Last error message
`blur_strerror$(code)`	`blur_strerror$@n`	Error code to text
`blur_clearerror()`	`blur_clearerror@`	Clear error state
CREATION & DESTRUCTION
`blur#(parent#)`	`blur#@#`	Create effect on control
`blur_free(effect#)`	`blur_free@#`	Destroy effect
SOFTNESS
`blur_softness#(effect#, val)`	`blur_softness#@#n`	Set blur intensity (0.0–3.0)
`blur_softness(effect#)`	`blur_softness@#`	Get blur intensity
EFFECT CONTROL
`blur_enabled#(effect#, val)`	`blur_enabled#@#n`	Enable (1) / disable (0)
`blur_enabled(effect#)`	`blur_enabled@#`	Get enabled state
`blur_trigger#(effect#, str$)`	`blur_trigger#@#$`	Set trigger string
`blur_trigger$(effect#)`	`blur_trigger$@#`	Get trigger string

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