ContrastEffectLib — Plan9Basic Documentation

ContrastEffectLib — Contrast & Brightness

Adjusts the contrast and brightness of any visual control in real time. Use it to make images and UI elements appear more vivid, washed out, darkened, or brightened. Wraps FireMonkey’s TContrastEffect. A fundamental image processing effect for photo editors, accessibility features, day/night themes, and visual feedback. 14 functions.

Category	Count	Description
Error Handling	4	contrast_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	contrast# (create), contrast_free (destroy)
Properties	4	contrast, brightness (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 contrast_free only to remove the effect while keeping the parent alive.

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

Function	Signature	Description
`contrast_error()`	`contrast_error@`	Returns last error code (0 = no error)
`contrast_errormsg$()`	`contrast_errormsg$@`	Returns last error message as string
`contrast_strerror$(code)`	`contrast_strerror$@n`	Converts an error code to descriptive text
`contrast_clearerror()`	`contrast_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 TContrastEffect
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
`contrast#(parent#)`	`contrast#@#`	Creates a contrast effect attached to the given control. Returns the effect pointer.
`contrast_free(effect#)`	`contrast_free@#`	Destroys the effect and removes it from the parent control.

The effect is created with defaults: contrast 1.0 (normal) and brightness 0.0 (normal).

Contrast

Controls the tonal range between dark and light areas. At 0.0 everything becomes flat gray. At 1.0 the image is unmodified. At 2.0 the difference between darks and lights is maximized.

Function	Signature	Description
`contrast_contrast#(effect#, value)`	`contrast_contrast#@#n`	Sets contrast level (0.0–2.0)
`contrast_contrast(effect#)`	`contrast_contrast@#`	Gets current contrast

Value	Visual Effect	Use Case
0.0	Flat gray — no tonal range	Extreme desaturation effect
0.5	Washed out, low contrast	Fog/mist overlay, faded vintage look
1.0	Normal (default)	No change to the original
1.5	Vivid, punchy	Photo enhancement, emphasis
2.0	Maximum contrast — near black & white	Dramatic art, high-contrast UI

Brightness

Shifts the overall luminance of the image. Negative values darken; positive values brighten. Default is 0.0 (no change).

Function	Signature	Description
`contrast_brightness#(effect#, value)`	`contrast_brightness#@#n`	Sets brightness (−1.0 to 1.0)
`contrast_brightness(effect#)`	`contrast_brightness@#`	Gets current brightness

Value	Visual Effect	Use Case
−1.0	Completely black	Fade-to-black transition
−0.5	Very dark	Night mode, dramatic shadows
0.0	Normal (default)	No change
0.3	Noticeably brighter	Lighten dark photos, highlight
0.5	Very bright	Overexposure look, dreamy
1.0	Completely white	Fade-to-white transition

╯ contrast-brightness.bas─◻✕
' High contrast, slightly bright (vivid photos)
contrast_contrast#(fx#, 1.5)
contrast_brightness#(fx#, 0.1)

' Faded vintage look
contrast_contrast#(fx#, 0.7)
contrast_brightness#(fx#, 0.15)

' Night/dark mode
contrast_contrast#(fx#, 1.2)
contrast_brightness#(fx#, -0.3)

' Reset to normal
contrast_contrast#(fx#, 1.0)
contrast_brightness#(fx#, 0.0)

Effect Control

Enabled

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

Trigger

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

Complete Examples

Contrast & Brightness on Image with Toggle

╯ contrast-demo.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let fx# = Pointer#(0)
let statusLbl# = Pointer#(0)

frm# = form#("Contrast Demo", 400, 350)

img# = image#(frm#)
image_bounds#(img#, 50, 30, 300, 180)
image_load#(img#, "https://picsum.photos/300/180")

' Apply contrast effect
fx# = contrast#(img#)
contrast_contrast#(fx#, 2.0)
contrast_brightness#(fx#, 0.2)

let btn# = button#(frm#, "Toggle Effect")
button_bounds#(btn#, 50, 230, 120, 30)
button_onclick#(btn#, "ToggleFx")

statusLbl# = label#(frm#, "Effect: ON", 200, 235)

form_show(frm#)

function ToggleFx(sender#) local e
  e = contrast_enabled(fx#)
  if e = 1 then
    contrast_enabled#(fx#, 0)
    label_text#(statusLbl#, "Effect: OFF")
  else
    contrast_enabled#(fx#, 1)
    label_text#(statusLbl#, "Effect: ON")
  endif
endfunction

Animated Contrast Pulse

Uses FloatAnimationLib to animate contrast in a looping auto-reverse pulse.

╯ contrast-animated.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let fx# = Pointer#(0)

frm# = form#("Contrast Pulse", 400, 300)

img# = image#(frm#)
image_bounds#(img#, 50, 30, 300, 180)
image_load#(img#, "https://picsum.photos/300/180")

fx# = contrast#(img#)

let ani# = floatani#(fx#)
floatani_propertyname#(ani#, "Contrast")
floatani_startvalue#(ani#, 1.0)
floatani_stopvalue#(ani#, 2.0)
floatani_duration#(ani#, 1.0)
floatani_autoreverse#(ani#, 1)
floatani_start(ani#)

form_show(frm#)

Best Practices

Practice	Why
Use contrast 1.0 + brightness 0.0 as “identity”	These defaults produce no visible change — good starting point
Adjust contrast 1.2–1.5 for photo enhancement	Subtle boost makes images look more vivid without clipping
Combine with `BloomEffectLib` for HDR look	High contrast + bloom gives a cinematic HDR appearance
Animate brightness −1.0 ↔ 0.0 for fade transitions	Smooth fade-to-black / fade-from-black with `FloatAnimationLib`
Use on hover trigger for interactive UI	`IsMouseOver=true` to brighten controls on hover
Pair with `SepiaEffectLib` for vintage photos	Low contrast + sepia toning = classic old photograph look
Use `contrast_enabled#` for before/after toggle	Instant comparison without recreating the effect
Works on any control, not just images	Buttons, panels, rectangles — darken/brighten any UI element

Quick Reference

Function	Signature	Description
ERROR HANDLING
`contrast_error()`	`contrast_error@`	Last error code
`contrast_errormsg$()`	`contrast_errormsg$@`	Last error message
`contrast_strerror$(code)`	`contrast_strerror$@n`	Error code to text
`contrast_clearerror()`	`contrast_clearerror@`	Clear error state
CREATION & DESTRUCTION
`contrast#(parent#)`	`contrast#@#`	Create effect on control
`contrast_free(effect#)`	`contrast_free@#`	Destroy effect
PROPERTIES
`contrast_contrast#(effect#, val)`	`contrast_contrast#@#n`	Set contrast (0.0–2.0)
`contrast_contrast(effect#)`	`contrast_contrast@#`	Get contrast
`contrast_brightness#(effect#, val)`	`contrast_brightness#@#n`	Set brightness (−1.0 to 1.0)
`contrast_brightness(effect#)`	`contrast_brightness@#`	Get brightness
EFFECT CONTROL
`contrast_enabled#(effect#, val)`	`contrast_enabled#@#n`	Enable (1) / disable (0)
`contrast_enabled(effect#)`	`contrast_enabled@#`	Get enabled state
`contrast_trigger#(effect#, str$)`	`contrast_trigger#@#$`	Set trigger string
`contrast_trigger$(effect#)`	`contrast_trigger$@#`	Get trigger string

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