NormalBlendEffectLib — Plan9Basic Documentation

Overview

NormalBlendEffectLib composites a target image on top of a source image using standard alpha blending, wrapping the FireMonkey TNormalBlendEffect component. The target image is drawn over the source based on the target's alpha (transparency) values. This is ideal for overlaying watermarks, logos, or PNG images with transparent regions.

Property	Details
Library	`NormalBlendEffectLib`
Prefix	`blend_`
Wraps	`TNormalBlendEffect`
Functions	11
Type	Visual effect (compositing)

Category	Count	Description
Creation / Destruction	2	Create and free effect
Target Image	1	Set overlay image
Effect Control	4	Enabled and trigger get/set
Error Handling	4	Error codes and messages

⚠ Not a Crossfade: This effect performs alpha compositing, not a smooth crossfade. If the target image is fully opaque (no transparency), it will completely cover the source. For crossfade transitions between two opaque images, use FadeTransitionEffectLib instead.

How It Works

The blend effect overlays the target image onto the source using the target's alpha channel:

Target Pixel	Result
Fully opaque	Completely replaces source pixel
Fully transparent	Source pixel shows through unchanged
Semi-transparent	Proportional blend of target and source

📷 Best with Transparency: This effect is designed for overlaying images that have transparent regions (like PNG watermarks, logos, or graphics with alpha channels). The target image can be hidden (image_visible#(img#, 0)) — only its bitmap data is used.

Cross-Platform Support

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

Creation & Destruction

blend#(parent#)

Creates a new normal blend effect attached to the specified visual control (the source image).

Parameter	Type	Description
`parent#`	Pointer	Source visual control to blend onto
Returns	Pointer	Effect handle, or 0 on failure

blend_free(effect#)

Destroys the effect and releases associated resources.

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

╯ create-blend.bas─◻✕
' Create a blend effect with overlay
let blnd# = blend#(sourceImg#)
blend_target#(blnd#, overlayImg#)

' Clean up when done
blend_free(blnd#)

Error Handling

Function	Signature	Description
`blend_error()`	`blend_error@`	Returns last error code (0 = none)
`blend_errormsg$()`	`blend_errormsg$@`	Returns last error message
`blend_strerror$(code)`	`blend_strerror$@n`	Converts error code to text
`blend_clearerror()`	`blend_clearerror@`	Clears the error state

Target Image

The target is the overlay image composited on top of the source. It should have transparency (alpha channel) for blending to be visible.

Function	Signature	Description
`blend_target#(effect#, image#)`	`blend_target#@##`	Sets the overlay image

💡 Hidden Targets: The target image control can be hidden with image_visible#(img#, 0) — the blend effect only uses the bitmap data, not the visible control. This lets you keep the overlay image off-screen.

Effect Control

Enable, disable, or trigger the blend effect at runtime.

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

Complete Examples

Example 1: Toggle Overlay Effect

╯ toggle-overlay.bas─◻✕
let frm# = Pointer#(0)
let img1# = Pointer#(0)
let img2# = Pointer#(0)
let blnd# = Pointer#(0)
let btn# = Pointer#(0)
let isOn = 1

frm# = form#("Blend Overlay Demo", 400, 350)

' Source image (base layer)
img1# = image#(frm#)
image_bounds#(img1#, 100, 30, 200, 150)
image_load#(img1#, "https://picsum.photos/200/150?random=1")

' Target image (overlay — hidden control)
img2# = image#(frm#)
image_bounds#(img2#, 0, 0, 200, 150)
image_visible#(img2#, 0)
image_load#(img2#, "https://picsum.photos/200/150?random=2")

' Create blend effect
blnd# = blend#(img1#)
blend_target#(blnd#, img2#)

btn# = button#(frm#, "Disable Overlay")
button_bounds#(btn#, 130, 210, 140, 30)
button_onclick#(btn#, "Toggle")

form_show(frm#)

function Toggle(sender#)
  if isOn = 1 then
    blend_enabled#(blnd#, 0)
    isOn = 0
    button_text#(btn#, "Enable Overlay")
  else
    blend_enabled#(blnd#, 1)
    isOn = 1
    button_text#(btn#, "Disable Overlay")
  endif
endfunction

Example 2: Compare With and Without Overlay

╯ overlay-comparison.bas─◻✕
let frm# = Pointer#(0)
let img1# = Pointer#(0)
let img2# = Pointer#(0)
let img3# = Pointer#(0)
let blnd# = Pointer#(0)

frm# = form#("Overlay Comparison", 500, 350)

' Source only
img1# = image#(frm#)
image_bounds#(img1#, 50, 30, 180, 135)
image_load#(img1#, "https://picsum.photos/180/135?random=1")
let lbl1# = label#(frm#, "Source Only", 100, 175)

' With overlay
img2# = image#(frm#)
image_bounds#(img2#, 270, 30, 180, 135)
image_load#(img2#, "https://picsum.photos/180/135?random=1")

' Hidden target image for overlay
img3# = image#(frm#)
image_bounds#(img3#, 0, 0, 180, 135)
image_visible#(img3#, 0)
image_load#(img3#, "https://picsum.photos/180/135?random=2")

blnd# = blend#(img2#)
blend_target#(blnd#, img3#)
let lbl2# = label#(frm#, "With Overlay", 315, 175)

form_show(frm#)

Example 3: Hover-Activated Overlay

╯ hover-blend.bas─◻✕
let frm# = Pointer#(0)
let img1# = Pointer#(0)
let img2# = Pointer#(0)
let blnd# = Pointer#(0)

frm# = form#("Hover Overlay", 400, 300)

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

img2# = image#(frm#)
image_bounds#(img2#, 0, 0, 200, 150)
image_visible#(img2#, 0)
image_load#(img2#, "https://picsum.photos/200/150?random=2")

' Overlay appears only on hover
blnd# = blend#(img1#)
blend_target#(blnd#, img2#)
blend_trigger#(blnd#, "IsMouseOver=true")

let lbl# = label#(frm#, "Hover over image to see overlay", 80, 210)

form_show(frm#)

Best Practices

Practice	Why
Use PNG overlays with alpha channels	Transparency is what makes normal blending visible
Hide the target image control	Only the bitmap data is used — no need to display it
Match source and target dimensions	Prevents misalignment or unexpected cropping
Use FadeTransition for crossfades	Normal blend is not a crossfade — opaque targets replace the source
Combine with MaskToAlpha for creative blends	Convert brightness to transparency, then blend on top of another image

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`blend#(parent#)`	`blend#@#`	Create effect
`blend_free(effect#)`	`blend_free@#`	Destroy effect
TARGET IMAGE
`blend_target#(effect#, image#)`	`blend_target#@##`	Set overlay image
EFFECT CONTROL
`blend_enabled#(effect#, value)`	`blend_enabled#@#n`	Enable/disable
`blend_enabled(effect#)`	`blend_enabled@#`	Get enabled state
`blend_trigger#(effect#, trigger$)`	`blend_trigger#@#$`	Set trigger
`blend_trigger$(effect#)`	`blend_trigger$@#`	Get trigger
ERROR HANDLING
`blend_error()`	`blend_error@`	Last error code
`blend_errormsg$()`	`blend_errormsg$@`	Last error message
`blend_strerror$(code)`	`blend_strerror$@n`	Code to text
`blend_clearerror()`	`blend_clearerror@`	Clear error state

Library	Description
`FadeTransitionEffectLib`	Smooth crossfade between two opaque images
`MaskToAlphaEffectLib`	Convert brightness to transparency
`ColorKeyAlphaEffectLib`	Make specific colors transparent