PinchEffectLib — Plan9Basic Documentation

Overview

PinchEffectLib creates a pinch or bulge distortion at a specified location on a visual control, wrapping the FireMonkey TPinchEffect component. Positive strength values pull pixels inward (pinch), while negative values push pixels outward (bulge) — great for fun-house mirror effects, interactive distortions, or dynamic visual feedback.

Property	Details
Library	`PinchEffectLib`
Prefix	`pinch_`
Wraps	`TPinchEffect`
Functions	20
Type	Visual effect (distortion)

Category	Count	Description
Creation / Destruction	2	Create and free effect
Center Position	4	Get/set X,Y center (0–1)
Radius & Strength	4	Get/set radius and strength
Aspect Ratio	2	Get/set distortion shape
Effect Control	4	Enabled and trigger get/set
Error Handling	4	Error codes and messages

🔍 Pinch vs Bulge: Positive strength pulls pixels inward (pinch), negative pushes outward (bulge). A strength of 0 produces no distortion. This dual behavior makes the effect very versatile.

Cross-Platform Support

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

Creation & Destruction

pinch#(parent#)

Creates a new pinch/bulge effect attached to the specified visual control.

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

pinch_free(effect#)

Destroys the effect and releases associated resources.

Error Handling

Function	Signature	Description
`pinch_error()`	`pinch_error@`	Returns last error code (0 = none)
`pinch_errormsg$()`	`pinch_errormsg$@`	Returns last error message
`pinch_strerror$(code)`	`pinch_strerror$@n`	Converts error code to text
`pinch_clearerror()`	`pinch_clearerror@`	Clears the error state

Center Position

Normalized coordinates (0–1) specifying where the distortion is centered.

Function	Signature	Description
`pinch_centerx#(effect#, value)`	`pinch_centerx#@#n`	Set X center (0=left, 1=right)
`pinch_centerx(effect#)`	`pinch_centerx@#`	Get X center
`pinch_centery#(effect#, value)`	`pinch_centery#@#n`	Set Y center (0=top, 1=bottom)
`pinch_centery(effect#)`	`pinch_centery@#`	Get Y center

CenterX/Y	Position
`0.0, 0.0`	Top-left corner
`0.5, 0.5`	Center (default)
`1.0, 1.0`	Bottom-right corner

Radius

Controls the size of the affected area in pixels.

Function	Signature	Description
`pinch_radius#(effect#, value)`	`pinch_radius#@#n`	Set radius (pixels)
`pinch_radius(effect#)`	`pinch_radius@#`	Get radius

Value	Effect
`10–20`	Small, localized distortion
`30–50`	Medium distortion area (default range)
`60–100`	Large area affected

Strength

Controls the direction and intensity of the distortion.

Function	Signature	Description
`pinch_strength#(effect#, value)`	`pinch_strength#@#n`	Set strength (−1 to +1)
`pinch_strength(effect#)`	`pinch_strength@#`	Get strength

Value	Direction	Effect
`−1.0`	← Outward	Maximum bulge (fisheye)
`−0.5`	← Outward	Moderate bulge
`0.0`	— None	No distortion
`+0.5`	→ Inward	Moderate pinch (default)
`+1.0`	→ Inward	Maximum pinch

Aspect Ratio

Controls the width-to-height ratio of the distortion area. Values greater than 1.0 stretch the effect horizontally; values less than 1.0 stretch vertically.

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

Effect Control

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

Complete Examples

Example 1: Pinch vs Bulge Comparison

╯ pinch-vs-bulge.bas─◻✕
let frm# = Pointer#(0)

frm# = form#("Pinch vs Bulge", 550, 300)

' Original (no effect)
let img1# = image#(frm#)
image_bounds#(img1#, 30, 50, 150, 112)
image_load#(img1#, "https://picsum.photos/150/112")
let lbl1# = label#(frm#, "Original", 75, 170)

' Pinch (positive strength)
let img2# = image#(frm#)
image_bounds#(img2#, 200, 50, 150, 112)
image_load#(img2#, "https://picsum.photos/150/112")
let p1# = pinch#(img2#)
pinch_strength#(p1#, 0.6)
pinch_radius#(p1#, 40)
let lbl2# = label#(frm#, "Pinch (+0.6)", 235, 170)

' Bulge (negative strength)
let img3# = image#(frm#)
image_bounds#(img3#, 370, 50, 150, 112)
image_load#(img3#, "https://picsum.photos/150/112")
let p2# = pinch#(img3#)
pinch_strength#(p2#, -0.6)
pinch_radius#(p2#, 40)
let lbl3# = label#(frm#, "Bulge (-0.6)", 405, 170)

form_show(frm#)

Example 2: Interactive Pinch Control

╯ interactive-pinch.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let pinch# = Pointer#(0)
let trkStr# = Pointer#(0)
let trkRad# = Pointer#(0)
let lblStr# = Pointer#(0)
let lblRad# = Pointer#(0)

frm# = form#("Pinch Control", 500, 450)

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

pinch# = pinch#(img#)
pinch_strength#(pinch#, 0)
pinch_radius#(pinch#, 50)

' Strength slider (-1 to +1)
lblStr# = label#(frm#, "Strength: 0.00", 30, 190)
trkStr# = trackbar#(frm#)
trackbar_bounds#(trkStr#, 30, 215, 440, 25)
trackbar_max#(trkStr#, 200)
trackbar_value#(trkStr#, 100)
trackbar_onchange#(trkStr#, "OnStrength")

' Radius slider
lblRad# = label#(frm#, "Radius: 50", 30, 260)
trkRad# = trackbar#(frm#)
trackbar_bounds#(trkRad#, 30, 285, 440, 25)
trackbar_max#(trkRad#, 100)
trackbar_value#(trkRad#, 50)
trackbar_onchange#(trkRad#, "OnRadius")

form_show(frm#)

function OnStrength(sender#) local s
  let s = (trackbar_value(trkStr#) - 100) / 100
  pinch_strength#(pinch#, s)
  label_text#(lblStr#, "Strength: " + stri$(s, 2))
endfunction

function OnRadius(sender#) local r
  let r = trackbar_value(trkRad#)
  pinch_radius#(pinch#, r)
  label_text#(lblRad#, "Radius: " + str$(r))
endfunction

Example 3: Basic Pinch Effect

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

frm# = form#("Pinch Effect Demo", 400, 350)

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

' Apply pinch effect (inward distortion)
pinch# = pinch#(img#)
pinch_strength#(pinch#, 0.5)
pinch_radius#(pinch#, 50)

form_show(frm#)

Best Practices

Practice	Why
Use strength 0 as a neutral starting point	Lets users slide between pinch and bulge intuitively
Match radius to image size	A radius of ~25–50% of image width works well
Center values are normalized (0–1)	Unlike PerspectiveTransform, this uses normalized coordinates
Combine with Swirl for complex distortions	Layer multiple effects for creative results
Map slider range −100 to +100 for strength	Then divide by 100 for the −1 to +1 range

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`pinch#(parent#)`	`pinch#@#`	Create effect
`pinch_free(effect#)`	`pinch_free@#`	Destroy effect
CENTER POSITION
`pinch_centerx#(effect#, value)`	`pinch_centerx#@#n`	Set X center (0–1)
`pinch_centerx(effect#)`	`pinch_centerx@#`	Get X center
`pinch_centery#(effect#, value)`	`pinch_centery#@#n`	Set Y center (0–1)
`pinch_centery(effect#)`	`pinch_centery@#`	Get Y center
RADIUS & STRENGTH
`pinch_radius#(effect#, value)`	`pinch_radius#@#n`	Set radius (pixels)
`pinch_radius(effect#)`	`pinch_radius@#`	Get radius
`pinch_strength#(effect#, value)`	`pinch_strength#@#n`	Set strength (−1 to +1)
`pinch_strength(effect#)`	`pinch_strength@#`	Get strength
ASPECT RATIO
`pinch_aspect#(effect#, value)`	`pinch_aspect#@#n`	Set aspect ratio
`pinch_aspect(effect#)`	`pinch_aspect@#`	Get aspect ratio
EFFECT CONTROL
`pinch_enabled#(effect#, value)`	`pinch_enabled#@#n`	Enable/disable
`pinch_enabled(effect#)`	`pinch_enabled@#`	Get enabled state
`pinch_trigger#(effect#, trigger$)`	`pinch_trigger#@#$`	Set trigger
`pinch_trigger$(effect#)`	`pinch_trigger$@#`	Get trigger
ERROR HANDLING
`pinch_error()`	`pinch_error@`	Last error code
`pinch_errormsg$()`	`pinch_errormsg$@`	Last error message
`pinch_strerror$(code)`	`pinch_strerror$@n`	Code to text
`pinch_clearerror()`	`pinch_clearerror@`	Clear error state

Library	Description
`SwirlEffectLib`	Swirl/twist distortion
`WrapEffectLib`	Wrap distortion
`MagnifyEffectLib`	Magnification effect
`RippleEffectLib`	Ripple/wave distortion