Clip

From Pico-8 Wiki
Jump to navigation Jump to search
clip( x, y, w, h, [clip_previous] )
Sets the clipping region in the draw state.
x
The x coordinate of the upper left corner of the clipping rectangle.

y
The y coordinate of the upper left corner of the clipping rectangle.

w
The width of the clipping rectangle, in pixels.

h
The height of the clipping rectangle, in pixels.

clip_previous
If true, the new clipping rectangle is formed by clipping it to the area of the one currently specified within the draw state.

return-value
An x,y,w,h tuple representing the previous clipping rectangle.

When the draw state has a clipping rectangle set, all drawing operations will not affect any pixels in the graphics buffer outside of this rectangle. This is useful for reserving parts of the screen. An optional boolean argument allows multiple clipping rectangles to be easily combined in an AND fashion, handy for rendering stacks.

When called without arguments, the function resets the clipping region to be the entire screen and returns the previous state as 4 return values x, y, w, h (since PICO-8 0.2.0d).

Technical notes

The actual current GPU clipping rectangle is memory-mapped and may be read or written directly with peek() and poke():

  • 0x5f20 / 24352: x_begin (no pixels < x_begin will be drawn)
  • 0x5f21 / 24353: y_begin (no pixels < y_begin will be drawn)
  • 0x5f22 / 24354: x_end (no pixels >= x_end will be drawn)
  • 0x5f23 / 24355: y_end (no pixels >= y_end will be drawn)

Important: These values are not in the same format as the arguments to clip(). See the draw state documentation for details.

Examples

-- set the clipping region to exclude 8 pixels at the top and bottom
clip(0, 8, 128, 112)

-- these circles are clipped to (0-127,8-119)
circfill(10, 10, 8, 8)
circfill(10, 118, 8, 8)

-- reset the clipping region to full screen
clip()

-- these circles are not clipped
circfill(40, 10, 8, 7)
circfill(40, 118, 8, 7)

-- get the current clip rectangle from its memory-mapped addresses
clip_x=peek(0x5f20)
clip_y=peek(0x5f21)
clip_w=peek(0x5f22)-clip_x
clip_h=peek(0x5f23)-clip_y
clip example

See also