SmoothMagnifyEffectLib — Plan9Basic Documentation

Overview

SmoothMagnifyEffectLib creates a refined magnifying glass effect with smooth transitions between magnified and normal areas, wrapping the FireMonkey TSmoothMagnifyEffect component. Unlike basic magnification, this effect uses separate inner and outer radii to create a gradual, professional-looking transition zone.

Property	Details
Library	`SmoothMagnifyEffectLib`
Prefix	`smag_`
Wraps	`TSmoothMagnifyEffect`
Functions	22
Type	Visual effect (distortion)

Category	Count	Description
Creation / Destruction	2	Create and free effect
Center Position	4	Get/set X and Y center
Magnification	2	Get/set zoom level
Inner / Outer Radius	4	Get/set inner and outer radii
Aspect Ratio	2	Get/set shape aspect
Effect Control	4	Enabled and trigger get/set
Error Handling	4	Error codes and messages

🔎 Smooth Lens: The key advantage over basic MagnifyEffectLib is the dual-radius system. The InnerRadius defines the area of full magnification, and the OuterRadius defines where the effect fades to normal — creating a smooth, natural-looking lens transition with no harsh edges.

Cross-Platform Support

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

Creation & Destruction

smag#(parent#)

Creates a new smooth magnify effect attached to the specified visual control.

Parameter	Type	Description
`parent#`	Pointer	Target visual control
Returns	Pointer	Effect handle, or 0 on failure

smag_free(effect#)

Destroys the effect and releases associated resources.

Error Handling

Function	Signature	Description
`smag_error()`	`smag_error@`	Returns last error code (0 = none)
`smag_errormsg$()`	`smag_errormsg$@`	Returns last error message
`smag_strerror$(code)`	`smag_strerror$@n`	Converts error code to text
`smag_clearerror()`	`smag_clearerror@`	Clears the error state

Center Position

Sets the center point of the magnifying lens using normalized coordinates (0–1 relative to image size).

Function	Signature	Description
`smag_centerx#(effect#, value)`	`smag_centerx#@#n`	Set X center (0–1)
`smag_centerx(effect#)`	`smag_centerx@#`	Get X center
`smag_centery#(effect#, value)`	`smag_centery#@#n`	Set Y center (0–1)
`smag_centery(effect#)`	`smag_centery@#`	Get Y center

Position	CenterX	CenterY
Top-left corner	`0.0`	`0.0`
Image center	`0.5`	`0.5`
Bottom-right corner	`1.0`	`1.0`

Magnification

Controls the zoom level inside the magnifying lens. A value of 1 means no zoom.

Function	Signature	Description
`smag_mag#(effect#, value)`	`smag_mag#@#n`	Set magnification (1.0+)
`smag_mag(effect#)`	`smag_mag@#`	Get magnification

Value	Effect
`1.0`	No zoom (original size)
`2.0`	2× zoom (default)
`3.0–5.0`	Strong magnification
`5.0+`	Very high zoom (extreme close-up)

Inner / Outer Radius

The dual-radius system is what makes this effect "smooth." The InnerRadius defines the zone of full magnification. The OuterRadius defines where the effect fades back to normal. The area between them has a smooth gradient transition.

Function	Signature	Description
`smag_inner#(effect#, value)`	`smag_inner#@#n`	Set inner radius (0–1)
`smag_inner(effect#)`	`smag_inner@#`	Get inner radius
`smag_outer#(effect#, value)`	`smag_outer#@#n`	Set outer radius (0–1)
`smag_outer(effect#)`	`smag_outer@#`	Get outer radius

⚠ OuterRadius must be > InnerRadius: If outer is smaller than or equal to inner, the smooth transition zone disappears and the effect may look broken. Always keep OuterRadius > InnerRadius.

Zone	Description
Inside InnerRadius	Full magnification (constant zoom)
Between Inner and Outer	Smooth gradient from full zoom to normal
Outside OuterRadius	Normal (no magnification)

Aspect Ratio

Controls the shape of the magnifying lens.

Function	Signature	Description
`smag_aspect#(effect#, value)`	`smag_aspect#@#n`	Set aspect ratio
`smag_aspect(effect#)`	`smag_aspect@#`	Get aspect ratio

A value of 1.0 creates a circular lens. Values greater than 1 stretch horizontally (oval), values less than 1 stretch vertically.

Effect Control

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

Complete Examples

Example 1: Basic Smooth Magnify

╯ smooth-magnify.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let eff# = Pointer#(0)

frm# = form#("Smooth Magnify Demo", 400, 350)

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

' Apply smooth magnification
eff# = smag#(img#)
smag_mag#(eff#, 3)
smag_inner#(eff#, 0.2)
smag_outer#(eff#, 0.5)

form_show(frm#)

Example 2: Adjustable Controls

╯ smag-controls.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let eff# = Pointer#(0)
let trkMag# = Pointer#(0)
let trkInner# = Pointer#(0)
let trkOuter# = Pointer#(0)
let lblMag# = Pointer#(0)
let lblInner# = Pointer#(0)
let lblOuter# = Pointer#(0)

frm# = form#("Smooth Magnify Control", 500, 520)

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

eff# = smag#(img#)
smag_mag#(eff#, 3)
smag_inner#(eff#, 0.2)
smag_outer#(eff#, 0.5)

' Magnification slider (1 to 10)
lblMag# = label#(frm#, "Magnification: 3.0", 30, 190)
trkMag# = trackbar#(frm#)
trackbar_bounds#(trkMag#, 30, 215, 440, 25)
trackbar_max#(trkMag#, 100)
trackbar_value#(trkMag#, 20)
trackbar_onchange#(trkMag#, "OnMagnification")

' Inner radius slider
lblInner# = label#(frm#, "Inner Radius: 0.20", 30, 260)
trkInner# = trackbar#(frm#)
trackbar_bounds#(trkInner#, 30, 285, 440, 25)
trackbar_max#(trkInner#, 100)
trackbar_value#(trkInner#, 20)
trackbar_onchange#(trkInner#, "OnInner")

' Outer radius slider
lblOuter# = label#(frm#, "Outer Radius: 0.50", 30, 330)
trkOuter# = trackbar#(frm#)
trackbar_bounds#(trkOuter#, 30, 355, 440, 25)
trackbar_max#(trkOuter#, 100)
trackbar_value#(trkOuter#, 50)
trackbar_onchange#(trkOuter#, "OnOuter")

form_show(frm#)

function OnMagnification(sender#) local m
  let m = 1 + trackbar_value(trkMag#) / 10
  smag_mag#(eff#, m)
  label_text#(lblMag#, "Magnification: " + stri$(m, 1))
endfunction

function OnInner(sender#) local i
  let i = trackbar_value(trkInner#) / 100
  smag_inner#(eff#, i)
  label_text#(lblInner#, "Inner Radius: " + stri$(i, 2))
endfunction

function OnOuter(sender#) local o
  let o = trackbar_value(trkOuter#) / 100
  smag_outer#(eff#, o)
  label_text#(lblOuter#, "Outer Radius: " + stri$(o, 2))
endfunction

Best Practices

Practice	Why
Always keep OuterRadius > InnerRadius	Required for the smooth transition zone to work
Use InnerRadius 0.05–0.2 for natural look	Small inner zone with larger outer gives realistic lens effect
Difference of 0.1–0.3 between radii	Narrow gap = sharper edge; wide gap = smoother falloff
Magnification 2–4 for practical use	Higher values can cause pixelation
Prefer this over MagnifyEffectLib	Smoother edges look more professional

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`smag#(parent#)`	`smag#@#`	Create effect
`smag_free(effect#)`	`smag_free@#`	Destroy effect
CENTER POSITION
`smag_centerx#(effect#, value)`	`smag_centerx#@#n`	Set X center (0–1)
`smag_centerx(effect#)`	`smag_centerx@#`	Get X center
`smag_centery#(effect#, value)`	`smag_centery#@#n`	Set Y center (0–1)
`smag_centery(effect#)`	`smag_centery@#`	Get Y center
MAGNIFICATION
`smag_mag#(effect#, value)`	`smag_mag#@#n`	Set zoom level
`smag_mag(effect#)`	`smag_mag@#`	Get zoom level
INNER / OUTER RADIUS
`smag_inner#(effect#, value)`	`smag_inner#@#n`	Set inner radius
`smag_inner(effect#)`	`smag_inner@#`	Get inner radius
`smag_outer#(effect#, value)`	`smag_outer#@#n`	Set outer radius
`smag_outer(effect#)`	`smag_outer@#`	Get outer radius
ASPECT RATIO
`smag_aspect#(effect#, value)`	`smag_aspect#@#n`	Set aspect ratio
`smag_aspect(effect#)`	`smag_aspect@#`	Get aspect ratio
EFFECT CONTROL
`smag_enabled#(effect#, value)`	`smag_enabled#@#n`	Enable/disable
`smag_enabled(effect#)`	`smag_enabled@#`	Get enabled state
`smag_trigger#(effect#, trigger$)`	`smag_trigger#@#$`	Set trigger
`smag_trigger$(effect#)`	`smag_trigger$@#`	Get trigger
ERROR HANDLING
`smag_error()`	`smag_error@`	Last error code
`smag_errormsg$()`	`smag_errormsg$@`	Last error message
`smag_strerror$(code)`	`smag_strerror$@n`	Code to text
`smag_clearerror()`	`smag_clearerror@`	Clear error state

Library	Description
`MagnifyEffectLib`	Basic magnification (single radius)
`PinchEffectLib`	Pinch/bulge distortion
`RippleEffectLib`	Water ripple distortion