MaskToAlphaEffectLib — Plan9Basic Documentation

Overview

MaskToAlphaEffectLib converts the luminosity (brightness) of an image into alpha (transparency), wrapping the FireMonkey TMaskToAlphaEffect component. Darker pixels become more transparent while lighter pixels remain opaque. This is useful for creating transparency masks from grayscale images.

Property	Details
Library	`MaskToAlphaEffectLib`
Prefix	`mask2a_`
Wraps	`TMaskToAlphaEffect`
Functions	10
Type	Visual effect (non-transition)

Category	Count	Description
Creation / Destruction	2	Create and free effect
Effect Control	4	Enabled and trigger get/set
Error Handling	4	Error codes and messages

🎨 No Properties: This effect has no adjustable parameters beyond Enabled and Trigger. The brightness-to-alpha conversion is fully automatic — just apply it and it works. This makes it the simplest effect to use in Plan9Basic.

How It Works

The effect maps each pixel's brightness (luminosity) directly to its alpha (transparency) channel:

Pixel Brightness	RGB Value	Resulting Alpha	Visibility
White	`255, 255, 255`	Fully opaque	Completely visible
Light gray	`192, 192, 192`	~75% opaque	Mostly visible
Medium gray	`128, 128, 128`	~50% opaque	Semi-transparent
Dark gray	`64, 64, 64`	~25% opaque	Mostly transparent
Black	`0, 0, 0`	Fully transparent	Invisible

💡 See the Effect: To see the transparency, use a colored form background. Without a visible background, transparent areas will appear black or invisible and the effect may seem like it isn't working.

⚠ Colored Images: For color images, the effect uses overall luminosity (not individual channels). Bright colors stay visible while dark colors become transparent, regardless of their hue.

Cross-Platform Support

Platform	Support
Windows	✅ Full support
Linux	✅ Full support
Android	✅ Full support

Creation & Destruction

mask2a#(parent#)

Creates a new mask-to-alpha effect attached to the specified visual control.

Parameter	Type	Description
`parent#`	Pointer	Target visual control (e.g., image)
Returns	Pointer	Effect handle, or 0 on failure

mask2a_free(effect#)

Destroys the effect and releases associated resources.

Parameter	Type	Description
`effect#`	Pointer	Effect handle to destroy

╯ create-mask2a.bas─◻✕
' Create mask-to-alpha effect — instant transparency!
let mask# = mask2a#(img#)

' Clean up when done
mask2a_free(mask#)

Error Handling

All four standard error functions are available for detecting and diagnosing issues.

Function	Signature	Description
`mask2a_error()`	`mask2a_error@`	Returns last error code (0 = none)
`mask2a_errormsg$()`	`mask2a_errormsg$@`	Returns last error message
`mask2a_strerror$(code)`	`mask2a_strerror$@n`	Converts error code to text
`mask2a_clearerror()`	`mask2a_clearerror@`	Clears the error state

Code	Meaning
`0`	No error
`1`	Invalid effect handle
`2`	Invalid parameter value

Effect Control

Enable, disable, or trigger the mask-to-alpha effect at runtime.

Function	Signature	Description
`mask2a_enabled#(effect#, value)`	`mask2a_enabled#@#n`	Enable (1) or disable (0)
`mask2a_enabled(effect#)`	`mask2a_enabled@#`	Gets enabled state
`mask2a_trigger#(effect#, trigger$)`	`mask2a_trigger#@#$`	Sets trigger string
`mask2a_trigger$(effect#)`	`mask2a_trigger$@#`	Gets trigger string

╯ toggle-mask.bas─◻✕
' Toggle the effect on and off
if mask2a_enabled(mask#) = 1 then
  mask2a_enabled#(mask#, 0)   ' Disable — show original
else
  mask2a_enabled#(mask#, 1)   ' Enable — apply transparency
endif

Complete Examples

Example 1: Basic Mask to Alpha

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

frm# = form#("Mask to Alpha Demo", 400, 350)
form_fill#(frm#, "LightBlue")

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

' Apply mask-to-alpha effect
mask# = mask2a#(img#)

form_show(frm#)

Example 2: Toggle Effect

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

frm# = form#("Toggle Mask Effect", 400, 350)
form_fill#(frm#, "Coral")

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

mask# = mask2a#(img#)

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
    mask2a_enabled#(mask#, 0)
    isOn = 0
    button_text#(btn#, "Enable Effect")
  else
    mask2a_enabled#(mask#, 1)
    isOn = 1
    button_text#(btn#, "Disable Effect")
  endif
endfunction

Example 3: Compare With/Without Effect

╯ mask-comparison.bas─◻✕
let frm# = Pointer#(0)
let img1# = Pointer#(0)
let img2# = Pointer#(0)
let mask# = Pointer#(0)
let lbl1# = Pointer#(0)
let lbl2# = Pointer#(0)

frm# = form#("Mask Comparison", 500, 350)
form_fill#(frm#, "Orange")

' Original image
img1# = image#(frm#)
image_bounds#(img1#, 50, 30, 180, 135)
image_load#(img1#, "https://picsum.photos/180/135")
lbl1# = label#(frm#, "Original", 110, 175)

' With mask-to-alpha
img2# = image#(frm#)
image_bounds#(img2#, 270, 30, 180, 135)
image_load#(img2#, "https://picsum.photos/180/135")
mask# = mask2a#(img2#)
lbl2# = label#(frm#, "Mask to Alpha", 310, 175)

form_show(frm#)

Best Practices

Practice	Why
Use a colored form background	Makes the transparency effect visible — otherwise transparent areas appear black
Works best with grayscale or high-contrast images	Produces the clearest and most predictable transparency results
Combine with other effects for layering	Use mask-to-alpha on overlapping images to create composite scenes
Toggle for before/after comparison	Let users see the original and masked versions side by side
No parameters to tune	Simply create the effect — it works automatically with no configuration

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`mask2a#(parent#)`	`mask2a#@#`	Create effect
`mask2a_free(effect#)`	`mask2a_free@#`	Destroy effect
EFFECT CONTROL
`mask2a_enabled#(effect#, value)`	`mask2a_enabled#@#n`	Enable/disable
`mask2a_enabled(effect#)`	`mask2a_enabled@#`	Get enabled state
`mask2a_trigger#(effect#, trigger$)`	`mask2a_trigger#@#$`	Set trigger
`mask2a_trigger$(effect#)`	`mask2a_trigger$@#`	Get trigger
ERROR HANDLING
`mask2a_error()`	`mask2a_error@`	Last error code
`mask2a_errormsg$()`	`mask2a_errormsg$@`	Last error message
`mask2a_strerror$(code)`	`mask2a_strerror$@n`	Code to text
`mask2a_clearerror()`	`mask2a_clearerror@`	Clear error state

Library	Description
`ColorKeyAlphaEffectLib`	Make specific colors transparent
`InvertEffectLib`	Invert image colors
`MonochromeEffectLib`	Convert to grayscale
`FillEffectLib`	Fill with solid color