ColorKeyAlphaEffectLib — Plan9Basic Documentation

ColorKeyAlphaEffectLib — Chroma Key Transparency

Makes pixels of a specific color transparent, enabling chroma key (green screen) removal and selective color knockout effects on image controls. Wraps FireMonkey’s TColorKeyAlphaEffect. Ideal for green screen removal, background knockout, sprite transparency, and color-based masking. 14 functions.

Category	Count	Description
Error Handling	4	colorkey_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	colorkey# (create), colorkey_free (destroy)
Key Color & Tolerance	4	color, tolerance (get/set)
Effect Control	4	enabled, trigger (get/set)

⚠ Critical: The default tolerance is 0.0, which means no colors become transparent. You must set tolerance > 0 for the effect to work. A typical starting value is 0.1–0.2.

How Chroma Key Works

The effect compares every pixel in the image to the key color. If a pixel’s color is within the tolerance distance of the key color, it becomes transparent. The wider the tolerance, the more shades around the key color are knocked out.

Step	What Happens
1. Set key color	Choose the color to remove (e.g., `"Lime"` for green screen)
2. Set tolerance	How far from the key color to match (0.0 = exact only, 1.0 = everything)
3. Pixels within tolerance → transparent	Matching pixels become fully transparent, revealing whatever is behind

⚠ Textures Only: This effect works on bitmap/texture data (images loaded via image_load#). It does not work on vector shapes like rectangles or circles.

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

Function	Signature	Description
`colorkey_error()`	`colorkey_error@`	Returns last error code (0 = no error)
`colorkey_errormsg$()`	`colorkey_errormsg$@`	Returns last error message as string
`colorkey_strerror$(code)`	`colorkey_strerror$@n`	Converts an error code to descriptive text
`colorkey_clearerror()`	`colorkey_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 TColorKeyAlphaEffect
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
`colorkey#(parent#)`	`colorkey#@#`	Creates a color key alpha effect attached to the given control. Returns the effect pointer.
`colorkey_free(effect#)`	`colorkey_free@#`	Destroys the effect and removes it from the parent control.

Key Color

Sets the target color to make transparent. Colors can be specified as named colors, hex RGB, or hex ARGB.

Function	Signature	Description
`colorkey_color#(effect#, color$)`	`colorkey_color#@#$`	Sets the color to knock out
`colorkey_color$(effect#)`	`colorkey_color$@#`	Gets the current key color

Color Format Reference

Format	Example	Description
Named color	`"Lime"`, `"Blue"`, `"Red"`	Standard color names
Hex RGB	`"#00FF00"`	6-digit hex (red, green, blue)
Hex ARGB	`"#FF00FF00"`	8-digit hex (alpha, red, green, blue)

Common Key Colors for Chroma Key

Color	Value	Use Case
`"Lime"`	#00FF00	Standard green screen (most common)
`"Green"`	#008000	Darker green backgrounds
`"Blue"`	#0000FF	Blue screen (film industry)
`"White"`	#FFFFFF	White background knockout
`"Black"`	#000000	Black background knockout
`"Magenta"`	#FF00FF	Magenta (game sprites, rarely in photos)

╯ key-color.bas─◻✕
' Green screen removal
colorkey_color#(ck#, "Lime")
colorkey_tolerance#(ck#, 0.15)

' Blue screen removal
colorkey_color#(ck#, "#0000FF")
colorkey_tolerance#(ck#, 0.2)

' White background knockout
colorkey_color#(ck#, "White")
colorkey_tolerance#(ck#, 0.1)

Tolerance

Controls how closely a pixel must match the key color to become transparent. At 0.0 only an exact match is affected (and the default 0.0 effectively disables the effect). At 1.0 nearly all colors become transparent.

Function	Signature	Description
`colorkey_tolerance#(effect#, value)`	`colorkey_tolerance#@#n`	Sets tolerance (0.0–1.0)
`colorkey_tolerance(effect#)`	`colorkey_tolerance@#`	Gets current tolerance

Tolerance	Match Range	Use Case
0.0	Nothing (default — effect disabled)	Must be > 0 to work
0.01–0.05	Exact color only	Uniform solid backgrounds, sprites
0.05–0.15	Close shades included	Clean green screens, product photos
0.15–0.30	Wider range, catches shadows	Uneven lighting, amateur green screens
0.30–0.50	Aggressive knockout	Noisy backgrounds, artistic effect
0.50–1.0	Most/all colors removed	Extreme effect, near-full transparency

╯ tolerance.bas─◻✕
' Tight match for clean green screen
colorkey_tolerance#(ck#, 0.1)

' Wider match for uneven lighting
colorkey_tolerance#(ck#, 0.25)

let t = colorkey_tolerance(ck#)
print "Tolerance: " + stri$(t, 2)

Effect Control

Enabled

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

Trigger

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

Complete Examples

Adjustable Tolerance with Slider

╯ colorkey-slider.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let ck# = Pointer#(0)
let trkTol# = Pointer#(0)
let lblTol# = Pointer#(0)

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

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

ck# = colorkey#(img#)
colorkey_color#(ck#, "Green")
colorkey_tolerance#(ck#, 0.2)

' Tolerance control
lblTol# = label#(frm#, "Tolerance: 0.20", 50, 190)
trkTol# = trackbar#(frm#)
trackbar_bounds#(trkTol#, 50, 220, 350, 30)
trackbar_max#(trkTol#, 100)
trackbar_value#(trkTol#, 20)
trackbar_onchange#(trkTol#, "OnTolChange")

form_show(frm#)

function OnTolChange(sender#) local v
  let v = trackbar_value(trkTol#) / 100
  colorkey_tolerance#(ck#, v)
  label_text#(lblTol#, "Tolerance: " + stri$(v, 2))
endfunction

Toggle Chroma Key Effect

╯ colorkey-toggle.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let ck# = Pointer#(0)
let btn# = Pointer#(0)
let isOn = 0

frm# = form#("ChromaKey Demo", 400, 300)

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

ck# = colorkey#(img#)
colorkey_enabled#(ck#, 0)
colorkey_color#(ck#, "Lime")
colorkey_tolerance#(ck#, 0.1)

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

form_show(frm#)

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

Best Practices

Practice	Why
Always set tolerance > 0	Default 0.0 makes nothing transparent — the most common mistake
Use `"Lime"` (#00FF00) for green screen	Standard chroma key green — widest compatibility
Start tolerance at 0.1, increase gradually	Too high removes foreground colors; fine-tune visually
Only use on image controls, not vector shapes	Effect operates on bitmap textures, not vector rendering
Use `"Magenta"` for game sprites	Magenta (#FF00FF) rarely appears in natural images
Combine with other effects for compositing	Layer transparent images over backgrounds for photo composites
Animate tolerance with `FloatAnimationLib`	Gradual reveal/disappear effects by animating tolerance 0 → 0.3
Use `colorkey_enabled#` to toggle	Faster than destroy/recreate for before/after comparison

Quick Reference

Function	Signature	Description
ERROR HANDLING
`colorkey_error()`	`colorkey_error@`	Last error code
`colorkey_errormsg$()`	`colorkey_errormsg$@`	Last error message
`colorkey_strerror$(code)`	`colorkey_strerror$@n`	Error code to text
`colorkey_clearerror()`	`colorkey_clearerror@`	Clear error state
CREATION & DESTRUCTION
`colorkey#(parent#)`	`colorkey#@#`	Create effect on control
`colorkey_free(effect#)`	`colorkey_free@#`	Destroy effect
KEY COLOR & TOLERANCE
`colorkey_color#(effect#, color$)`	`colorkey_color#@#$`	Set key color
`colorkey_color$(effect#)`	`colorkey_color$@#`	Get key color
`colorkey_tolerance#(effect#, val)`	`colorkey_tolerance#@#n`	Set tolerance (0.0–1.0)
`colorkey_tolerance(effect#)`	`colorkey_tolerance@#`	Get tolerance
EFFECT CONTROL
`colorkey_enabled#(effect#, val)`	`colorkey_enabled#@#n`	Enable (1) / disable (0)
`colorkey_enabled(effect#)`	`colorkey_enabled@#`	Get enabled state
`colorkey_trigger#(effect#, str$)`	`colorkey_trigger#@#$`	Set trigger string
`colorkey_trigger$(effect#)`	`colorkey_trigger$@#`	Get trigger string

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