clip( x, y, w, h, [clip_previous] )
clip "clipping rectangle" aka "crop"
x the X position of the top left corner of the clipping region
y the Y position of the top left corner of the clipping region
w the Width of the clipping region
h the Height of the clipping region
clip_previous (optional) set to true to combine new region with last region (explained more below)

The clip function is used to restrict the region on screen for anything being drawn after setting the clipping region. You can reset it back to full screen by calling clip() with no arguments.


clip(30,30,50,50)         --restrict drawing region
rectfill(0,0,127,127,12)  --draw full screen blue

clip region example

Reset Clipping Region

Calling clip with empty parentheses resets the drawing region to full screen.

Clip Previous Argument

The clip_previous optional argument is a boolean. If true is passed, then the new clipping region is also clipped by the old clipping region, so that the draw region is the overlap of both clipping regions.

For example:

clip(30,30,50,50)        --first clip
rectfill(30,30,79,79,1)  --dark blue

clip(x,y,50,50,true)     --second clip
rectfill(30,30,79,79,14) --pink 

clip region example

The pink filled rectangle is only visible where the two clipping regions overlap, even though it is being drawn the exact same size and position of the dark blue rectangle.


3 Oct 2023