EmbossEffectLib — Plan9Basic Documentation

EmbossEffectLib — Emboss Effect

Creates a 3D raised-surface emboss effect on visual controls, simulating a pressed or stamped appearance using highlight and shadow edge detection. Wraps FireMonkey’s TEmbossEffect. Useful for giving flat controls a tactile, physical look — like letters stamped into metal or raised lettering on a coin. 14 functions.

Category	Count	Description
Error Handling	4	emboss_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	emboss# (create), emboss_free (destroy)
Properties	4	amount, width (get/set)
Effect Control	4	enabled, trigger (get/set)

How Emboss Works

The emboss effect detects edges in the source image and applies directional lighting simulation: one side of each edge gets a highlight (light), the other gets a shadow (dark). This creates the illusion that the surface is raised or pressed.

╯ emboss-principle─◻✕
Original:         Embossed:
+----------+      +----------+
| PLAN9    |      | ░PLAN9▓  |   ░ = highlight (light side)
| BASIC    |      | ░BASIC▓  |   ▓ = shadow   (dark side)
+----------+      +----------+
                  Light source: top-left

Two properties control the result:

Property	Range	Default	Controls
Amount	0.0 – 1.0	0.5	How much of the emboss effect blends with the original — intensity/strength
Width	0.0 – 10.0	1.0	How wide the highlight/shadow edges are — edge thickness in pixels

Amount Ranges

Amount	Visual Effect	Use Case
0.0	No emboss — original appearance	Effect present but invisible
0.1–0.3	Subtle raised surface	Elegant, understated 3D
0.4–0.6	Clear emboss with good detail	Default look, balanced
0.7–0.9	Strong emboss, dominates appearance	Dramatic, artistic
1.0	Full emboss — pure edge rendering	Edge-map visualization

Width Ranges

Width	Visual Effect	Use Case
0.5–1.0	Thin, crisp edges	Fine detail, text, sharp shapes
1.0–3.0	Medium edges	General-purpose emboss
3.0–6.0	Wide, soft edges	Bold 3D look, large controls
6.0–10.0	Very wide, exaggerated	Artistic/stylized effects

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
`emboss_error()`	`emboss_error@`	Returns last error code (0 = no error)
`emboss_errormsg$()`	`emboss_errormsg$@`	Returns last error message as string
`emboss_strerror$(code)`	`emboss_strerror$@n`	Converts an error code to descriptive text
`emboss_clearerror()`	`emboss_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 TEmbossEffect
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
`emboss#(parent#)`	`emboss#@#`	Creates an emboss effect on the given control. Returns the effect pointer.
`emboss_free(effect#)`	`emboss_free@#`	Destroys the effect and removes it from the parent.

Amount

Controls the intensity of the emboss effect — how much the 3D raised appearance blends with the original image. Range 0.0–1.0, default 0.5.

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

╯ amount-presets.bas─◻✕
' Subtle 3D hint
emboss_amount#(emb#, 0.2)

' Balanced default
emboss_amount#(emb#, 0.5)

' Bold dramatic emboss
emboss_amount#(emb#, 0.9)

Width

Controls the edge thickness of the highlight and shadow bands. Range 0.0–10.0, default 1.0. Wider edges create a bolder, more dramatic 3D look.

Function	Signature	Description
`emboss_width#(effect#, value)`	`emboss_width#@#n`	Sets width (0.0–10.0)
`emboss_width(effect#)`	`emboss_width@#`	Gets current width

Effect Control

Enabled

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

Trigger

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

Complete Examples

Basic Emboss on Rectangle

╯ emboss-basic.bas─◻✕
let frm# = Pointer#(0)
let rect# = Pointer#(0)
let emb# = Pointer#(0)

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

rect# = rectangle#(frm#)
rectangle_bounds#(rect#, 100, 80, 200, 120)
rectangle_fill#(rect#, "Silver")

emb# = emboss#(rect#)
emboss_amount#(emb#, 0.5)
emboss_width#(emb#, 2)

form_show(frm#)

Intensity Presets with Buttons

╯ emboss-presets.bas─◻✕
let frm# = Pointer#(0)
let rect# = Pointer#(0)
let emb# = Pointer#(0)
let lbl# = Pointer#(0)

frm# = form#("Emboss Control", 450, 320)

rect# = rectangle#(frm#)
rectangle_bounds#(rect#, 125, 40, 200, 100)
rectangle_fill#(rect#, "Gray")

emb# = emboss#(rect#)
emboss_amount#(emb#, 0.5)
emboss_width#(emb#, 2)

lbl# = label#(frm#, "Amount: 0.5", 170, 160)

let btn1# = button#(frm#, "Light")
button_bounds#(btn1#, 60, 200, 100, 30)
button_onclick#(btn1#, "SetLight")

let btn2# = button#(frm#, "Medium")
button_bounds#(btn2#, 170, 200, 100, 30)
button_onclick#(btn2#, "SetMedium")

let btn3# = button#(frm#, "Strong")
button_bounds#(btn3#, 280, 200, 100, 30)
button_onclick#(btn3#, "SetStrong")

form_show(frm#)

function SetLight(sender#)
  emboss_amount#(emb#, 0.2)
  label_text#(lbl#, "Amount: 0.2")
endfunction

function SetMedium(sender#)
  emboss_amount#(emb#, 0.5)
  label_text#(lbl#, "Amount: 0.5")
endfunction

function SetStrong(sender#)
  emboss_amount#(emb#, 0.9)
  label_text#(lbl#, "Amount: 0.9")
endfunction

Width Comparison — Side by Side

╯ emboss-widths.bas─◻✕
let frm# = Pointer#(0)
let rect1# = Pointer#(0)
let rect2# = Pointer#(0)
let rect3# = Pointer#(0)
let emb1# = Pointer#(0)
let emb2# = Pointer#(0)
let emb3# = Pointer#(0)

frm# = form#("Emboss Width", 500, 280)

' Thin width
rect1# = rectangle#(frm#)
rectangle_bounds#(rect1#, 40, 60, 120, 100)
rectangle_fill#(rect1#, "Silver")
emb1# = emboss#(rect1#)
emboss_amount#(emb1#, 0.5)
emboss_width#(emb1#, 1)
let lbl1# = label#(frm#, "Width: 1", 70, 170)

' Medium width
rect2# = rectangle#(frm#)
rectangle_bounds#(rect2#, 190, 60, 120, 100)
rectangle_fill#(rect2#, "Silver")
emb2# = emboss#(rect2#)
emboss_amount#(emb2#, 0.5)
emboss_width#(emb2#, 3)
let lbl2# = label#(frm#, "Width: 3", 220, 170)

' Wide width
rect3# = rectangle#(frm#)
rectangle_bounds#(rect3#, 340, 60, 120, 100)
rectangle_fill#(rect3#, "Silver")
emb3# = emboss#(rect3#)
emboss_amount#(emb3#, 0.5)
emboss_width#(emb3#, 6)
let lbl3# = label#(frm#, "Width: 6", 370, 170)

form_show(frm#)

Best Practices

Practice	Why
Use gray or neutral-colored controls	Emboss relies on highlight/shadow contrast — works best on mid-tone surfaces
Start with amount 0.5, width 2	Good default that shows the 3D effect clearly without overloading
Lower amount (0.2–0.3) for subtle elegance	Professional UI look with a hint of depth
Combine with `BevelEffectLib`	Both create 3D looks but with different edge styles
Use on images for rich texture	Photos show emboss well due to natural edge detail
Match width to control size	Small controls need thin width (1–2); large controls can handle 3–6
Use trigger `IsMouseOver=true`	Emboss on hover gives buttons a “pressed” feeling
Animate amount with `FloatAnimationLib`	Smoothly transition between flat and embossed states

Quick Reference

Function	Signature	Description
ERROR HANDLING
`emboss_error()`	`emboss_error@`	Last error code
`emboss_errormsg$()`	`emboss_errormsg$@`	Last error message
`emboss_strerror$(code)`	`emboss_strerror$@n`	Error code to text
`emboss_clearerror()`	`emboss_clearerror@`	Clear error state
CREATION & DESTRUCTION
`emboss#(parent#)`	`emboss#@#`	Create effect on control
`emboss_free(effect#)`	`emboss_free@#`	Destroy effect
PROPERTIES
`emboss_amount#(effect#, val)`	`emboss_amount#@#n`	Set amount (0.0–1.0)
`emboss_amount(effect#)`	`emboss_amount@#`	Get amount
`emboss_width#(effect#, val)`	`emboss_width#@#n`	Set width (0.0–10.0)
`emboss_width(effect#)`	`emboss_width@#`	Get width
EFFECT CONTROL
`emboss_enabled#(effect#, val)`	`emboss_enabled#@#n`	Enable (1) / disable (0)
`emboss_enabled(effect#)`	`emboss_enabled@#`	Get enabled state
`emboss_trigger#(effect#, str$)`	`emboss_trigger#@#$`	Set trigger string
`emboss_trigger$(effect#)`	`emboss_trigger$@#`	Get trigger string

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