CropEffectLib — Plan9Basic Documentation

CropEffectLib — Image Crop Effect

Crops a rectangular region from the texture of a visual control using pixel coordinates. The cropped area is then scaled to fill the control’s display bounds. Wraps FireMonkey’s TCropEffect. Useful for image viewports, zoom previews, sprite sheet extraction, and interactive region selection. 18 functions.

Category	Count	Description
Error Handling	4	crop_error, errormsg$, strerror$, clearerror
Creation & Destruction	2	crop# (create), crop_free (destroy)
Crop Region	8	lefttopx, lefttopy, rightbottomx, rightbottomy (get/set)
Effect Control	4	enabled, trigger (get/set)

⚠ Images Only: This effect works on bitmap/texture data only. It does not work on vector shapes like rectangles or circles. Use with TImage controls loaded via image_load#.

Coordinate System

The crop region is defined by four pixel coordinates relative to the original image dimensions, not the control’s display size. The top-left corner of the image is (0, 0).

╯ coordinate-diagram─◻✕
  (0,0)                        (200,0)
    +------------------------------+
    |                              |
    |    (LeftTopX, LeftTopY)      |
    |       +------------+         |
    |       |  CROP AREA |         |
    |       |  (visible) |         |
    |       +------------+         |
    |       (RightBottomX, RightBottomY)
    |                              |
    +------------------------------+
  (0,150)                      (200,150)

Property	Default	Description
`LeftTopX`	0	Left edge of crop region (pixels from left)
`LeftTopY`	0	Top edge of crop region (pixels from top)
`RightBottomX`	10000	Right edge of crop region (pixels from left)
`RightBottomY`	10000	Bottom edge of crop region (pixels from top)

ⓘ Default = Full Image: With defaults of 0, 0, 10000, 10000 the crop region extends far beyond any practical image size, so the entire image is shown. Set specific coordinates to define the actual crop area.

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
`crop_error()`	`crop_error@`	Returns last error code (0 = no error)
`crop_errormsg$()`	`crop_errormsg$@`	Returns last error message as string
`crop_strerror$(code)`	`crop_strerror$@n`	Converts an error code to descriptive text
`crop_clearerror()`	`crop_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 TCropEffect
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
`crop#(parent#)`	`crop#@#`	Creates a crop effect attached to the given control. Returns the effect pointer.
`crop_free(effect#)`	`crop_free@#`	Destroys the effect and removes it from the parent control.

Crop Region

Four coordinate functions define the rectangular crop area in pixel units relative to the original image.

Function	Signature	Description
`crop_lefttopx#(effect#, value)`	`crop_lefttopx#@#n`	Sets left edge X (pixels)
`crop_lefttopx(effect#)`	`crop_lefttopx@#`	Gets left edge X
`crop_lefttopy#(effect#, value)`	`crop_lefttopy#@#n`	Sets top edge Y (pixels)
`crop_lefttopy(effect#)`	`crop_lefttopy@#`	Gets top edge Y
`crop_rightbottomx#(effect#, value)`	`crop_rightbottomx#@#n`	Sets right edge X (pixels)
`crop_rightbottomx(effect#)`	`crop_rightbottomx@#`	Gets right edge X
`crop_rightbottomy#(effect#, value)`	`crop_rightbottomy#@#n`	Sets bottom edge Y (pixels)
`crop_rightbottomy(effect#)`	`crop_rightbottomy@#`	Gets bottom edge Y

Common Crop Patterns (200×150 image)

Crop	LeftTopX	LeftTopY	RightBottomX	RightBottomY
Full image	0	0	200	150
Left half	0	0	100	150
Right half	100	0	200	150
Top half	0	0	200	75
Center 50%	50	37	150	112
Top-left quadrant	0	0	100	75
Bottom-right quadrant	100	75	200	150

╯ crop-region.bas─◻✕
' Crop to center 50% of a 200x150 image
crop_lefttopx#(crp#, 50)
crop_lefttopy#(crp#, 37)
crop_rightbottomx#(crp#, 150)
crop_rightbottomy#(crp#, 112)
crop_enabled#(crp#, 1)

Effect Control

Enabled

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

Trigger

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

Complete Examples

Basic Crop with Presets

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

frm# = form#("Crop Demo", 400, 350)

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

crp# = crop#(img#)
crop_enabled#(crp#, 0)  ' Start disabled until image loads

let btn1# = button#(frm#, "Crop Left Half")
button_bounds#(btn1#, 50, 210, 120, 30)
button_onclick#(btn1#, "CropLeft")

let btn2# = button#(frm#, "Crop Center")
button_bounds#(btn2#, 180, 210, 120, 30)
button_onclick#(btn2#, "CropCenter")

let btn3# = button#(frm#, "Reset")
button_bounds#(btn3#, 115, 250, 120, 30)
button_onclick#(btn3#, "CropReset")

form_show(frm#)

function CropLeft(sender#)
  crop_lefttopx#(crp#, 0)
  crop_lefttopy#(crp#, 0)
  crop_rightbottomx#(crp#, 100)
  crop_rightbottomy#(crp#, 150)
  crop_enabled#(crp#, 1)
endfunction

function CropCenter(sender#)
  crop_lefttopx#(crp#, 50)
  crop_lefttopy#(crp#, 37)
  crop_rightbottomx#(crp#, 150)
  crop_rightbottomy#(crp#, 112)
  crop_enabled#(crp#, 1)
endfunction

function CropReset(sender#)
  crop_enabled#(crp#, 0)
endfunction

Quadrant Selector

Five buttons to view the full image or any of its four quadrants.

╯ crop-quadrants.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let crp# = Pointer#(0)
let lbl# = Pointer#(0)

frm# = form#("Quadrant Crop", 450, 380)

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

crp# = crop#(img#)
crop_enabled#(crp#, 0)

lbl# = label#(frm#, "Click button after image loads", 115, 185)

let btn1# = button#(frm#, "Full")
button_bounds#(btn1#, 40, 220, 80, 30)
button_onclick#(btn1#, "SetFull")

let btn2# = button#(frm#, "Top-Left")
button_bounds#(btn2#, 130, 220, 80, 30)
button_onclick#(btn2#, "SetTL")

let btn3# = button#(frm#, "Top-Right")
button_bounds#(btn3#, 220, 220, 80, 30)
button_onclick#(btn3#, "SetTR")

let btn4# = button#(frm#, "Bottom-L")
button_bounds#(btn4#, 130, 260, 80, 30)
button_onclick#(btn4#, "SetBL")

let btn5# = button#(frm#, "Bottom-R")
button_bounds#(btn5#, 220, 260, 80, 30)
button_onclick#(btn5#, "SetBR")

form_show(frm#)

function SetFull(sender#)
  crop_enabled#(crp#, 0)
  label_text#(lbl#, "Showing: Full Image")
endfunction

function SetTL(sender#)
  crop_lefttopx#(crp#, 0)
  crop_lefttopy#(crp#, 0)
  crop_rightbottomx#(crp#, 100)
  crop_rightbottomy#(crp#, 75)
  crop_enabled#(crp#, 1)
  label_text#(lbl#, "Showing: Top-Left Quadrant")
endfunction

function SetTR(sender#)
  crop_lefttopx#(crp#, 100)
  crop_lefttopy#(crp#, 0)
  crop_rightbottomx#(crp#, 200)
  crop_rightbottomy#(crp#, 75)
  crop_enabled#(crp#, 1)
  label_text#(lbl#, "Showing: Top-Right Quadrant")
endfunction

function SetBL(sender#)
  crop_lefttopx#(crp#, 0)
  crop_lefttopy#(crp#, 75)
  crop_rightbottomx#(crp#, 100)
  crop_rightbottomy#(crp#, 150)
  crop_enabled#(crp#, 1)
  label_text#(lbl#, "Showing: Bottom-Left Quadrant")
endfunction

function SetBR(sender#)
  crop_lefttopx#(crp#, 100)
  crop_lefttopy#(crp#, 75)
  crop_rightbottomx#(crp#, 200)
  crop_rightbottomy#(crp#, 150)
  crop_enabled#(crp#, 1)
  label_text#(lbl#, "Showing: Bottom-Right Quadrant")
endfunction

Best Practices

Practice	Why
Coordinates are in pixels, not percentages	You must know the original image dimensions to set correct crop values
Keep effect disabled until image loads	Cropping before the texture exists may produce no result
Disable to show full image (instead of resetting coords)	`crop_enabled#(crp#, 0)` instantly shows the full image
Cropped area scales to fill the control	A small crop region will be upscaled — expect lower apparent resolution
Animate crop coordinates for pan/zoom effects	Use `FloatAnimationLib` to smoothly pan across an image
Use for sprite sheet extraction	Set crop region to a single sprite frame and swap coordinates per frame
Combine with `MagnifyEffectLib` for magnifying glass	Crop to region + magnify = interactive zoom viewer
Ensure RightBottomX > LeftTopX and RightBottomY > LeftTopY	Inverted coordinates produce undefined behavior

Quick Reference

Function	Signature	Description
ERROR HANDLING
`crop_error()`	`crop_error@`	Last error code
`crop_errormsg$()`	`crop_errormsg$@`	Last error message
`crop_strerror$(code)`	`crop_strerror$@n`	Error code to text
`crop_clearerror()`	`crop_clearerror@`	Clear error state
CREATION & DESTRUCTION
`crop#(parent#)`	`crop#@#`	Create effect on control
`crop_free(effect#)`	`crop_free@#`	Destroy effect
CROP REGION
`crop_lefttopx#(effect#, px)`	`crop_lefttopx#@#n`	Set left edge
`crop_lefttopx(effect#)`	`crop_lefttopx@#`	Get left edge
`crop_lefttopy#(effect#, px)`	`crop_lefttopy#@#n`	Set top edge
`crop_lefttopy(effect#)`	`crop_lefttopy@#`	Get top edge
`crop_rightbottomx#(effect#, px)`	`crop_rightbottomx#@#n`	Set right edge
`crop_rightbottomx(effect#)`	`crop_rightbottomx@#`	Get right edge
`crop_rightbottomy#(effect#, px)`	`crop_rightbottomy#@#n`	Set bottom edge
`crop_rightbottomy(effect#)`	`crop_rightbottomy@#`	Get bottom edge
EFFECT CONTROL
`crop_enabled#(effect#, val)`	`crop_enabled#@#n`	Enable (1) / disable (0)
`crop_enabled(effect#)`	`crop_enabled@#`	Get enabled state
`crop_trigger#(effect#, str$)`	`crop_trigger#@#$`	Set trigger string
`crop_trigger$(effect#)`	`crop_trigger$@#`	Get trigger string

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