BoxBlurEffectLib — Plan9Basic Documentation

BoxBlurEffectLib — Box Blur Effect

Applies a GPU-accelerated box blur to any visual control. Box blur averages all pixels within a square kernel, producing a fast but slightly “blocky” blur compared to Gaussian. Wraps FireMonkey’s TBoxBlurEffect. Ideal when speed matters more than smoothness — real-time previews, performance-sensitive mobile apps, and quick background defocus. 12 functions.

Category	Count	Description
Error Handling	4	boxblur_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	boxblur# (create), boxblur_free (destroy)
Blur Amount	2	bluramount (get/set)
Effect Control	4	enabled, trigger (get/set)

ⓘ Box vs Gaussian: Box blur uses a simple square kernel (every pixel weighted equally), making it the fastest blur algorithm. Gaussian blur uses a bell-curve kernel for smoother results but at higher computational cost. Choose box blur for speed, Gaussian for quality.

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 boxblur_error() after operations.

Function	Signature	Description
`boxblur_error()`	`boxblur_error@`	Returns last error code (0 = no error)
`boxblur_errormsg$()`	`boxblur_errormsg$@`	Returns last error message as string
`boxblur_strerror$(code)`	`boxblur_strerror$@n`	Converts an error code to descriptive text
`boxblur_clearerror()`	`boxblur_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 TBoxBlurEffect
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
`boxblur#(parent#)`	`boxblur#@#`	Creates a box blur effect attached to the given control. Returns the effect pointer.
`boxblur_free(effect#)`	`boxblur_free@#`	Destroys the effect and removes it from the parent control.

The effect is created with default blur amount of 0.1 (barely visible).

Blur Amount

Controls the size of the averaging kernel. Higher values produce a stronger, more diffused blur. Default is 0.1. Range is 0–10.

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

Amount	Visual Effect	Use Case
0	No blur — sharp original	Effect disabled without removing
1–3	Subtle softening	Light defocus, anti-aliasing, soft edges
4–6	Medium blur, details fading	Background blur, frosted overlay
7–10	Heavy blur, abstract shapes only	Privacy masking, color extraction

⚠ Note: The blur amount range for BoxBlurEffectLib is 0–10, not 0–1. This differs from BlurEffectLib which uses 0–3 softness. At equivalent visual blur levels, box blur is faster but less smooth.

╯ blur-amount.bas─◻✕
' Subtle softening
boxblur_bluramount#(blur#, 2)

' Medium defocus
boxblur_bluramount#(blur#, 5)

' Heavy privacy blur
boxblur_bluramount#(blur#, 9)

let b = boxblur_bluramount(blur#)
print "Blur amount: " + str$(b)

Effect Control

Enabled

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

Trigger

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

Complete Examples

Basic Box Blur

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

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

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

' Create box blur effect with visible amount
blur# = boxblur#(img#)
boxblur_bluramount#(blur#, 3)

form_show(frm#)

Adjustable Blur Slider

A trackbar controls blur from 0.0 to 10.0 in real time.

╯ boxblur-slider.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let blur# = Pointer#(0)
let trkBlur# = Pointer#(0)
let lblBlur# = Pointer#(0)

frm# = form#("Blur Control", 450, 400)

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

blur# = boxblur#(img#)
boxblur_bluramount#(blur#, 0)

' Blur amount slider (0-10 range)
lblBlur# = label#(frm#, "Blur: 0", 180, 200)
trkBlur# = trackbar#(frm#)
trackbar_bounds#(trkBlur#, 50, 230, 350, 30)
trackbar_max#(trkBlur#, 100)
trackbar_value#(trkBlur#, 0)
trackbar_onchange#(trkBlur#, "OnBlurChange")

form_show(frm#)

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

Toggle Box Blur

╯ boxblur-toggle.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let blur# = Pointer#(0)
let btn# = Pointer#(0)
let isOn = 1

frm# = form#("Toggle Box Blur", 400, 300)

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

blur# = boxblur#(img#)
boxblur_bluramount#(blur#, 4)

btn# = button#(frm#, "Disable Effect")
button_bounds#(btn#, 140, 210, 120, 30)
button_onclick#(btn#, "Toggle")

form_show(frm#)

function Toggle(sender#)
  if isOn = 1 then
    boxblur_enabled#(blur#, 0)
    isOn = 0
    button_text#(btn#, "Enable Effect")
  else
    boxblur_enabled#(blur#, 1)
    isOn = 1
    button_text#(btn#, "Disable Effect")
  endif
endfunction

Best Practices

Practice	Why
Use box blur when speed matters more than smoothness	Fastest blur algorithm — ideal for real-time previews and mobile
Use `GaussianBlurEffectLib` for final output quality	Gaussian is smoother but slower — use for polished exports
Remember: range is 0–10, not 0–1	Wider range than BlurEffectLib — adjust slider scales accordingly
Values 1–3 for subtle, 4–6 for medium, 7–10 for heavy	Quick reference for dial-in without trial and error
Use `boxblur_enabled#` to toggle	Faster than destroy/recreate for on/off scenarios
Animate blur amount with `FloatAnimationLib`	Smooth focus/unfocus transitions using the BlurAmount property
Combine with opacity for frosted glass	Semi-transparent panel + box blur = fast frosted overlay
Use box blur for backgrounds, Gaussian for foreground	Background blur doesn’t need to be as smooth — save GPU for what matters

Quick Reference

Function	Signature	Description
ERROR HANDLING
`boxblur_error()`	`boxblur_error@`	Last error code
`boxblur_errormsg$()`	`boxblur_errormsg$@`	Last error message
`boxblur_strerror$(code)`	`boxblur_strerror$@n`	Error code to text
`boxblur_clearerror()`	`boxblur_clearerror@`	Clear error state
CREATION & DESTRUCTION
`boxblur#(parent#)`	`boxblur#@#`	Create effect on control
`boxblur_free(effect#)`	`boxblur_free@#`	Destroy effect
BLUR AMOUNT
`boxblur_bluramount#(effect#, val)`	`boxblur_bluramount#@#n`	Set blur amount (0–10)
`boxblur_bluramount(effect#)`	`boxblur_bluramount@#`	Get blur amount
EFFECT CONTROL
`boxblur_enabled#(effect#, val)`	`boxblur_enabled#@#n`	Enable (1) / disable (0)
`boxblur_enabled(effect#)`	`boxblur_enabled@#`	Get enabled state
`boxblur_trigger#(effect#, str$)`	`boxblur_trigger#@#$`	Set trigger string
`boxblur_trigger$(effect#)`	`boxblur_trigger$@#`	Get trigger string

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