GloomEffectLib — Plan9Basic Documentation

GloomEffectLib — Gloom / Darkening Effect

Creates a darkening/gloom effect on visual controls — the opposite of bloom. Reduces brightness and desaturates colours to produce a moody, subdued atmosphere. Wraps FireMonkey’s TGloomEffect. Works with four independent properties controlling gloom intensity/saturation and base intensity/saturation. 18 functions.

Category	Count	Description
Error Handling	4	gloom_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	gloom# (create), gloom_free (destroy)
Gloom Properties	4	gloomintensity, gloomsaturation (get/set)
Base Properties	4	baseintensity, basesaturation (get/set)
Effect Control	4	enabled, trigger (get/set)

Bloom vs Gloom

Feature	Bloom	Gloom
Effect	Brightens, adds luminous halo	Darkens, reduces brightness
Mood	Dreamy, ethereal, warm	Moody, dark, dramatic
Saturation	Can enhance colours	Can desaturate to grayscale
Best for	Highlights, heavenly glow	Dark themes, noir, horror

Properties

Property	Range	Default	Description
GloomIntensity	0.0–1.0	0.5	Strength of the darkening effect
BaseIntensity	0.0–1.0	1.0	Brightness of the original image
GloomSaturation	0.0–1.0	1.0	Colour saturation of the gloom areas
BaseSaturation	0.0–1.0	1.0	Colour saturation of the base image (0 = grayscale)

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
`gloom_error()`	`gloom_error@`	Returns last error code (0 = no error)
`gloom_errormsg$()`	`gloom_errormsg$@`	Returns last error message
`gloom_strerror$(code)`	`gloom_strerror$@n`	Converts error code to text
`gloom_clearerror()`	`gloom_clearerror@`	Clears the error state

Creation & Destruction

Function	Signature	Description
`gloom#(parent#)`	`gloom#@#`	Creates a gloom effect on the given control. Returns the effect pointer.
`gloom_free(effect#)`	`gloom_free@#`	Destroys the effect.

Gloom Properties

Function	Signature	Description
`gloom_gloomintensity#(effect#, value)`	`gloom_gloomintensity#@#n`	Sets darkening intensity (0.0–1.0)
`gloom_gloomintensity(effect#)`	`gloom_gloomintensity@#`	Gets gloom intensity
`gloom_gloomsaturation#(effect#, value)`	`gloom_gloomsaturation#@#n`	Sets gloom area saturation (0.0–1.0)
`gloom_gloomsaturation(effect#)`	`gloom_gloomsaturation@#`	Gets gloom saturation

Base Properties

Function	Signature	Description
`gloom_baseintensity#(effect#, value)`	`gloom_baseintensity#@#n`	Sets base image brightness (0.0–1.0)
`gloom_baseintensity(effect#)`	`gloom_baseintensity@#`	Gets base intensity
`gloom_basesaturation#(effect#, value)`	`gloom_basesaturation#@#n`	Sets base saturation (0 = grayscale)
`gloom_basesaturation(effect#)`	`gloom_basesaturation@#`	Gets base saturation

ⓘ Grayscale shortcut: Setting basesaturation to 0 converts the entire image to grayscale, regardless of other settings.

Effect Control

Function	Signature	Description
`gloom_enabled#(effect#, value)`	`gloom_enabled#@#n`	Enables (1) or disables (0)
`gloom_enabled(effect#)`	`gloom_enabled@#`	Gets enabled state
`gloom_trigger#(effect#, trigger$)`	`gloom_trigger#@#$`	Sets trigger string
`gloom_trigger$(effect#)`	`gloom_trigger$@#`	Gets trigger string

Complete Examples

Basic Gloom on Image

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

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

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

glm# = gloom#(img#)
gloom_gloomintensity#(glm#, 0.5)

form_show(frm#)

Intensity Presets

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

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

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

glm# = gloom#(img#)
gloom_gloomintensity#(glm#, 0)

lbl# = label#(frm#, "Gloom: Off", 175, 200)

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

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

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

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

form_show(frm#)

function SetOff(sender#)
  gloom_gloomintensity#(glm#, 0)
  label_text#(lbl#, "Gloom: Off")
endfunction

function SetLight(sender#)
  gloom_gloomintensity#(glm#, 0.3)
  label_text#(lbl#, "Gloom: 30%")
endfunction

function SetMedium(sender#)
  gloom_gloomintensity#(glm#, 0.5)
  label_text#(lbl#, "Gloom: 50%")
endfunction

function SetDark(sender#)
  gloom_gloomintensity#(glm#, 0.8)
  label_text#(lbl#, "Gloom: 80%")
endfunction

Saturation Control — Colour to Grayscale

╯ gloom-saturation.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let glm# = 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")

glm# = gloom#(img#)
gloom_gloomintensity#(glm#, 0.4)

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#)
  gloom_basesaturation#(glm#, 0)
  label_text#(lbl#, "Saturation: 0% (Grayscale)")
endfunction

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

function SetSat100(sender#)
  gloom_basesaturation#(glm#, 1.0)
  label_text#(lbl#, "Saturation: 100%")
endfunction

Best Practices

Practice	Why
Use on images, not solid shapes	Solid colours show little visible gloom effect
GloomIntensity 0.3–0.5 for mood	Subtle darkening for dark UI themes
BaseSaturation 0 for grayscale	Quick way to desaturate any image
Combine GloomIntensity + BaseSaturation 0	Dark desaturated noir look
Opposite of `BloomEffectLib`	Use bloom for highlights, gloom for shadows
Animate with `FloatAnimationLib`	Smoothly transition from bright to dark moods

Quick Reference

Function	Signature	Description
ERROR HANDLING
`gloom_error()`	`gloom_error@`	Last error code
`gloom_errormsg$()`	`gloom_errormsg$@`	Last error message
`gloom_strerror$(code)`	`gloom_strerror$@n`	Error code to text
`gloom_clearerror()`	`gloom_clearerror@`	Clear error state
CREATION & DESTRUCTION
`gloom#(parent#)`	`gloom#@#`	Create effect on control
`gloom_free(effect#)`	`gloom_free@#`	Destroy effect
GLOOM PROPERTIES
`gloom_gloomintensity#(e#, val)`	`gloom_gloomintensity#@#n`	Set darkening (0–1)
`gloom_gloomintensity(e#)`	`gloom_gloomintensity@#`	Get darkening
`gloom_gloomsaturation#(e#, val)`	`gloom_gloomsaturation#@#n`	Set gloom saturation
`gloom_gloomsaturation(e#)`	`gloom_gloomsaturation@#`	Get gloom saturation
BASE PROPERTIES
`gloom_baseintensity#(e#, val)`	`gloom_baseintensity#@#n`	Set base brightness
`gloom_baseintensity(e#)`	`gloom_baseintensity@#`	Get base brightness
`gloom_basesaturation#(e#, val)`	`gloom_basesaturation#@#n`	Set base saturation
`gloom_basesaturation(e#)`	`gloom_basesaturation@#`	Get base saturation
EFFECT CONTROL
`gloom_enabled#(e#, val)`	`gloom_enabled#@#n`	Enable (1) / disable (0)
`gloom_enabled(e#)`	`gloom_enabled@#`	Get enabled state
`gloom_trigger#(e#, str$)`	`gloom_trigger#@#$`	Set trigger string
`gloom_trigger$(e#)`	`gloom_trigger$@#`	Get trigger string

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