GaussianBlurEffectLib — Plan9Basic Documentation

GaussianBlurEffectLib — Gaussian Blur

Applies a high-quality Gaussian blur to visual controls. Pixels are weighted by a bell-curve distribution, producing the smoothest, most natural-looking blur available. Wraps FireMonkey’s TGaussianBlurEffect. 12 functions.

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

Gaussian vs Box Blur

Gaussian blur weights nearby pixels with a bell curve, giving more influence to close pixels and less to distant ones. Box blur averages all pixels equally within the radius. Gaussian produces smoother, more natural results but is slightly slower.

Feature	Gaussian Blur	Box Blur
Quality	Higher — smooth bell-curve weighting	Lower — uniform averaging
Speed	Slightly slower	Faster
Edges	Natural, soft falloff	Can show boxy artifacts
Best for	Photos, UI backgrounds, depth of field	Quick previews, simple softening

Blur Amount Ranges

Amount	Visual Effect	Use Case
0	No blur — original sharpness	Effect present but inactive
1–3	Subtle softening	Gentle focus, anti-alias, slight depth
4–6	Medium blur	Frosted glass, background blur, modal overlay
7–10	Heavy blur	Abstract backdrop, privacy/censoring, dream effect

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
`gaussblur_error()`	`gaussblur_error@`	Returns last error code (0 = no error)
`gaussblur_errormsg$()`	`gaussblur_errormsg$@`	Returns last error message as string
`gaussblur_strerror$(code)`	`gaussblur_strerror$@n`	Converts an error code to descriptive text
`gaussblur_clearerror()`	`gaussblur_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 TGaussianBlurEffect
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
`gaussblur#(parent#)`	`gaussblur#@#`	Creates a Gaussian blur effect on the given control. Returns the effect pointer.
`gaussblur_free(effect#)`	`gaussblur_free@#`	Destroys the effect and removes it from the parent.

Blur Amount

Controls the blur radius/intensity. Range 0–10, default 0.1. Higher values produce a stronger, wider blur.

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

Effect Control

Enabled

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

Trigger

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

Complete Examples

Basic Gaussian Blur

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

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

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

blur# = gaussblur#(img#)
gaussblur_bluramount#(blur#, 3)

form_show(frm#)

Adjustable Blur Slider

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

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

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

blur# = gaussblur#(img#)
gaussblur_bluramount#(blur#, 0)

lblBlur# = label#(frm#, "Blur: 0.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
  gaussblur_bluramount#(blur#, b)
  label_text#(lblBlur#, "Blur: " + stri$(b, 1))
endfunction

Toggle Blur On/Off

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

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

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

blur# = gaussblur#(img#)
gaussblur_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
    gaussblur_enabled#(blur#, 0)
    isOn = 0
    button_text#(btn#, "Enable Effect")
  else
    gaussblur_enabled#(blur#, 1)
    isOn = 1
    button_text#(btn#, "Disable Effect")
  endif
endfunction

Best Practices

Practice	Why
Use Gaussian over Box for photos	Smoother, more natural result on photographic content
Amount 1–3 for subtle softening	Gentle focus effect without losing detail
Amount 4–6 for frosted glass	Good for blurred backgrounds behind overlays/modals
Amount 7–10 for privacy/censoring	Heavy blur hides detail completely
Animate blur with `FloatAnimationLib`	Smooth focus/unfocus transitions
Use trigger for hover blur	`gaussblur_trigger#(b#, "IsMouseOver=true")`
Use Box blur if speed is critical	BoxBlurEffectLib is faster for real-time animation on mobile

Quick Reference

Function	Signature	Description
ERROR HANDLING
`gaussblur_error()`	`gaussblur_error@`	Last error code
`gaussblur_errormsg$()`	`gaussblur_errormsg$@`	Last error message
`gaussblur_strerror$(code)`	`gaussblur_strerror$@n`	Error code to text
`gaussblur_clearerror()`	`gaussblur_clearerror@`	Clear error state
CREATION & DESTRUCTION
`gaussblur#(parent#)`	`gaussblur#@#`	Create effect on control
`gaussblur_free(effect#)`	`gaussblur_free@#`	Destroy effect
PROPERTIES
`gaussblur_bluramount#(effect#, val)`	`gaussblur_bluramount#@#n`	Set blur amount (0–10)
`gaussblur_bluramount(effect#)`	`gaussblur_bluramount@#`	Get blur amount
EFFECT CONTROL
`gaussblur_enabled#(effect#, val)`	`gaussblur_enabled#@#n`	Enable (1) / disable (0)
`gaussblur_enabled(effect#)`	`gaussblur_enabled@#`	Get enabled state
`gaussblur_trigger#(effect#, str$)`	`gaussblur_trigger#@#$`	Set trigger string
`gaussblur_trigger$(effect#)`	`gaussblur_trigger$@#`	Get trigger string

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