BloomEffectLib — Plan9Basic Documentation

BloomEffectLib — Bloom / Glow Halo Effect

Creates a GPU-accelerated bloom effect that makes bright areas of an image glow and bleed outward, simulating camera overexposure or cinematic light halos. The effect extracts luminous pixels from the source image, blurs them, and composites them back with adjustable intensity and saturation. Wraps FireMonkey’s TBloomEffect. Ideal for dreamy photo filters, sci-fi interfaces, neon glow effects, and cinematic post-processing. 18 functions.

Category	Count	Description
Error Handling	4	bloom_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	bloom# (create), bloom_free (destroy)
Bloom Properties	4	bloomintensity, bloomsaturation (get/set)
Base Image Properties	4	baseintensity, basesaturation (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 bloom_free only to remove the effect while keeping the parent alive.

How Bloom Works

The bloom effect operates on two layers that are composited together:

Layer	Controls	What It Does
Bloom layer	BloomIntensity, BloomSaturation	The glow extracted from bright pixels — blurred and overlaid
Base layer	BaseIntensity, BaseSaturation	The original image underneath the glow

The final output is: Base × BaseIntensity + Bloom × BloomIntensity, with each layer’s color saturation controlled independently.

⚠ Content Matters: Bloom works best on images with varying colors and bright areas (photos, gradients, colorful graphics). Solid-color shapes won’t produce a visible bloom effect since there are no bright highlights to extract.

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 bloom_error() after operations. Error code 0 means success.

Function	Signature	Description
`bloom_error()`	`bloom_error@`	Returns last error code (0 = no error)
`bloom_errormsg$()`	`bloom_errormsg$@`	Returns last error message as string
`bloom_strerror$(code)`	`bloom_strerror$@n`	Converts an error code to descriptive text
`bloom_clearerror()`	`bloom_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 TBloomEffect
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
`bloom#(parent#)`	`bloom#@#`	Creates a bloom effect attached to the given control. Returns the effect pointer.
`bloom_free(effect#)`	`bloom_free@#`	Destroys the effect and removes it from the parent control.

The parent# should ideally be an image or control with varied colors. The effect is created with default values (bloom intensity 0.5, base intensity 1.0, both saturations 1.0).

╯ create-bloom.bas─◻✕
' Create bloom effect on an image
let blm# = bloom#(img#)

' Later, remove the effect
bloom_free(blm#)

Bloom Properties

These control the glow layer — the luminous halo extracted from bright areas of the image.

Bloom Intensity

Controls how strong the glow overlay appears. 0.0 = no glow, 1.0 = maximum glow. Default is 0.5.

Function	Signature	Description
`bloom_bloomintensity#(effect#, value)`	`bloom_bloomintensity#@#n`	Sets bloom glow intensity (0.0–1.0)
`bloom_bloomintensity(effect#)`	`bloom_bloomintensity@#`	Gets current bloom intensity

Intensity	Visual Effect	Use Case
0.0	No glow visible	Bloom disabled without removing effect
0.1–0.3	Subtle halo on bright spots	Cinematic photography, soft focus
0.4–0.6	Visible glow (default range)	Dreamy filter, light bleeding
0.7–0.8	Strong overexposure look	Sci-fi interfaces, neon signs
0.9–1.0	Extreme bloom, washed-out highlights	Artistic effects, heavenly glow

Bloom Saturation

Controls the color saturation of the glow. At 0.0 the glow is pure white; at 1.0 it retains the original colors. Default is 1.0.

Function	Signature	Description
`bloom_bloomsaturation#(effect#, value)`	`bloom_bloomsaturation#@#n`	Sets bloom color saturation (0.0–1.0)
`bloom_bloomsaturation(effect#)`	`bloom_bloomsaturation@#`	Gets current bloom saturation

Saturation	Glow Color	Look
0.0	Pure white	Classic camera overexposure, clean light bleed
0.5	Desaturated tint	Pastel glow, soft and warm
1.0	Full original color	Neon glow, colored halos around bright areas

╯ bloom-properties.bas─◻✕
' Dreamy white glow
bloom_bloomintensity#(blm#, 0.6)
bloom_bloomsaturation#(blm#, 0.0)

' Neon colored bloom
bloom_bloomintensity#(blm#, 0.7)
bloom_bloomsaturation#(blm#, 1.0)

' Subtle cinematic
bloom_bloomintensity#(blm#, 0.2)
bloom_bloomsaturation#(blm#, 0.5)

Base Image Properties

These control the original image layer underneath the bloom overlay.

Base Intensity

Controls the brightness of the original image. 0.0 = black (only bloom visible), 1.0 = full original brightness. Default is 1.0.

Function	Signature	Description
`bloom_baseintensity#(effect#, value)`	`bloom_baseintensity#@#n`	Sets base image intensity (0.0–1.0)
`bloom_baseintensity(effect#)`	`bloom_baseintensity@#`	Gets current base intensity

Base Saturation

Controls the color saturation of the original image. 0.0 = grayscale base, 1.0 = full color. Default is 1.0.

Function	Signature	Description
`bloom_basesaturation#(effect#, value)`	`bloom_basesaturation#@#n`	Sets base color saturation (0.0–1.0)
`bloom_basesaturation(effect#)`	`bloom_basesaturation@#`	Gets current base saturation

╯ base-properties.bas─◻✕
' Dim base, prominent bloom (ethereal look)
bloom_baseintensity#(blm#, 0.5)
bloom_bloomintensity#(blm#, 0.8)

' Grayscale base + colored bloom (dramatic)
bloom_basesaturation#(blm#, 0.0)
bloom_bloomsaturation#(blm#, 1.0)

' Full brightness, full color (default)
bloom_baseintensity#(blm#, 1.0)
bloom_basesaturation#(blm#, 1.0)

Effect Control

Enabled

Toggles the effect on or off without destroying it.

Function	Signature	Description
`bloom_enabled#(effect#, value)`	`bloom_enabled#@#n`	Enables (1) or disables (0) the effect
`bloom_enabled(effect#)`	`bloom_enabled@#`	Gets enabled state (1 = on, 0 = off)

Trigger

The trigger property is a string used by FireMonkey’s animation system.

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

Complete Examples

Basic Bloom on Image

Applies a moderate bloom glow to a photo.

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

frm# = form#("Bloom Demo", 400, 320)

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

blm# = bloom#(img#)
bloom_bloomintensity#(blm#, 0.6)

form_show(frm#)

Bloom Intensity Presets

Four buttons to switch between off, low, medium, and high bloom levels.

╯ bloom-presets.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let blm# = Pointer#(0)
let lbl# = Pointer#(0)

frm# = form#("Bloom Control", 450, 380)

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

blm# = bloom#(img#)
bloom_bloomintensity#(blm#, 0)

lbl# = label#(frm#, "Bloom: Off", 180, 200)

let btn1# = button#(frm#, "Off")
button_bounds#(btn1#, 50, 240, 80, 30)
button_onclick#(btn1#, "SetOff")

let btn2# = button#(frm#, "Low")
button_bounds#(btn2#, 140, 240, 80, 30)
button_onclick#(btn2#, "SetLow")

let btn3# = button#(frm#, "Medium")
button_bounds#(btn3#, 230, 240, 80, 30)
button_onclick#(btn3#, "SetMedium")

let btn4# = button#(frm#, "High")
button_bounds#(btn4#, 320, 240, 80, 30)
button_onclick#(btn4#, "SetHigh")

form_show(frm#)

function SetOff(sender#)
  bloom_bloomintensity#(blm#, 0)
  label_text#(lbl#, "Bloom: Off")
endfunction

function SetLow(sender#)
  bloom_bloomintensity#(blm#, 0.3)
  label_text#(lbl#, "Bloom: 30%")
endfunction

function SetMedium(sender#)
  bloom_bloomintensity#(blm#, 0.5)
  label_text#(lbl#, "Bloom: 50%")
endfunction

function SetHigh(sender#)
  bloom_bloomintensity#(blm#, 0.8)
  label_text#(lbl#, "Bloom: 80%")
endfunction

Saturation Control — White vs Colored Glow

Demonstrates the difference between desaturated (white) and fully saturated (colored) bloom.

╯ bloom-saturation.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let blm# = Pointer#(0)
let lbl# = Pointer#(0)

frm# = form#("Saturation Control", 450, 380)

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

blm# = bloom#(img#)
bloom_bloomintensity#(blm#, 0.6)
bloom_bloomsaturation#(blm#, 1.0)

lbl# = label#(frm#, "Saturation: 100%", 155, 200)

let btn1# = button#(frm#, "0%")
button_bounds#(btn1#, 80, 240, 80, 30)
button_onclick#(btn1#, "SetSat0")

let btn2# = button#(frm#, "50%")
button_bounds#(btn2#, 180, 240, 80, 30)
button_onclick#(btn2#, "SetSat50")

let btn3# = button#(frm#, "100%")
button_bounds#(btn3#, 280, 240, 80, 30)
button_onclick#(btn3#, "SetSat100")

form_show(frm#)

function SetSat0(sender#)
  bloom_bloomsaturation#(blm#, 0)
  label_text#(lbl#, "Saturation: 0% (White glow)")
endfunction

function SetSat50(sender#)
  bloom_bloomsaturation#(blm#, 0.5)
  label_text#(lbl#, "Saturation: 50%")
endfunction

function SetSat100(sender#)
  bloom_bloomsaturation#(blm#, 1.0)
  label_text#(lbl#, "Saturation: 100% (Full color)")
endfunction

Best Practices

Practice	Why
Use on images with bright highlights and varied colors	Bloom needs bright pixels to extract — solid colors produce no visible effect
Start with bloom intensity 0.3–0.5	Subtle bloom is usually more pleasing; high values wash out quickly
Set bloom saturation 0.0 for classic overexposure	White glow mimics real camera light bleed — the most natural look
Set bloom saturation 1.0 for neon/sci-fi glow	Colored halos look electric — great for game UIs and futuristic interfaces
Reduce base intensity to emphasize bloom	Dimming the original image makes the glow more prominent and ethereal
Combine base saturation 0.0 + bloom saturation 1.0	Grayscale photo with colored glow = dramatic artistic effect
Pair with `GloomEffectLib` for contrast	Gloom darkens; bloom brightens — use both for HDR-like processing
Animate bloom intensity with `FloatAnimationLib`	Pulsating bloom creates breathing/heartbeat glow effects

Quick Reference

Function	Signature	Description
ERROR HANDLING
`bloom_error()`	`bloom_error@`	Last error code
`bloom_errormsg$()`	`bloom_errormsg$@`	Last error message
`bloom_strerror$(code)`	`bloom_strerror$@n`	Error code to text
`bloom_clearerror()`	`bloom_clearerror@`	Clear error state
CREATION & DESTRUCTION
`bloom#(parent#)`	`bloom#@#`	Create effect on control
`bloom_free(effect#)`	`bloom_free@#`	Destroy effect
BLOOM PROPERTIES
`bloom_bloomintensity#(effect#, val)`	`bloom_bloomintensity#@#n`	Set glow intensity (0.0–1.0)
`bloom_bloomintensity(effect#)`	`bloom_bloomintensity@#`	Get glow intensity
`bloom_bloomsaturation#(effect#, val)`	`bloom_bloomsaturation#@#n`	Set glow saturation (0.0–1.0)
`bloom_bloomsaturation(effect#)`	`bloom_bloomsaturation@#`	Get glow saturation
BASE IMAGE PROPERTIES
`bloom_baseintensity#(effect#, val)`	`bloom_baseintensity#@#n`	Set base brightness (0.0–1.0)
`bloom_baseintensity(effect#)`	`bloom_baseintensity@#`	Get base brightness
`bloom_basesaturation#(effect#, val)`	`bloom_basesaturation#@#n`	Set base saturation (0.0–1.0)
`bloom_basesaturation(effect#)`	`bloom_basesaturation@#`	Get base saturation
EFFECT CONTROL
`bloom_enabled#(effect#, val)`	`bloom_enabled#@#n`	Enable (1) / disable (0)
`bloom_enabled(effect#)`	`bloom_enabled@#`	Get enabled state
`bloom_trigger#(effect#, str$)`	`bloom_trigger#@#$`	Set trigger string
`bloom_trigger$(effect#)`	`bloom_trigger$@#`	Get trigger string

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