ez.sprite - ezOS Lua API

audio bus crypto display ez global gps keyboard mesh net radio sprite storage synth system wifi

Off-screen drawing surface for compositing and overlays

Sprites are off-screen RGB565 buffers allocated in PSRAM. Create with ez.display.create_sprite(w,h), draw to them using the same primitives as the display, then push() to composite onto the screen with optional alpha. Useful for UI overlays, menus, and cached graphics. Call destroy() when done.

Functions

clear() Clear sprite to a color

sprite:clear(color)

Fills the entire sprite buffer with the specified color. Call this before drawing new content to reset the sprite. Often used with the transparent color to create a clean slate for layered composition.

Parameter	Description
color	Fill color (optional, defaults to black)

sprite:clear(0x0000)  -- Clear to black
sprite:clear(0xF81F)  -- Clear to magenta(for transparency)

destroy() Free sprite memory

sprite:destroy()

Explicitly releases the sprite's pixel buffer from PSRAM. While sprites are automatically garbage collected, calling destroy() immediately frees memory when you know the sprite is no longer needed. After calling, the sprite is invalid.

local sprite = ez.display.create_sprite(100, 100)
-- ... use sprite ...
sprite:destroy()  -- Free memory immediately

draw_circle() Draw a circle outline in the sprite

sprite:draw_circle(x, y, r, color)

Draws a circle outline within the sprite buffer.

Parameter	Description
x	Center X
y	Center Y
r	Radius
color	Circle color

sprite:draw_circle(50, 50, 20, colors.CYAN)

draw_jpeg() Decode JPEG data into the sprite's pixel buffer

sprite:draw_jpeg(x, y, data [, scale_x, scale_y, off_x, off_y, max_w, max_h])

Identical parameters to ez.display.draw_jpeg but rasterises into the off-screen sprite. Decode happens once; subsequent push() calls reuse the cached pixels without re-decoding.

draw_line() Draw a line in the sprite

sprite:draw_line(x1, y1, x2, y2, color)

Draws a line between two points within the sprite buffer.

Parameter	Description
x1	Start X
y1	Start Y
x2	End X
y2	End Y
color	Line color

sprite:draw_line(0, 0, 50, 50, colors.YELLOW)

draw_png() Decode PNG data into the sprite's pixel buffer

sprite:draw_png(x, y, data [, scale_x, scale_y, off_x, off_y, max_w, max_h])

draw_rect() Draw a rectangle outline in the sprite

sprite:draw_rect(x, y, w, h, color)

Draws a 1-pixel wide rectangle outline within the sprite buffer.

Parameter	Description
x	X position relative to sprite
y	Y position relative to sprite
w	Width in pixels
h	Height in pixels
color	Outline color

sprite:draw_rect(5, 5, 90, 40, colors.WHITE)

draw_round_rect() Draw a rounded rectangle outline in the sprite

sprite:draw_round_rect(x, y, w, h, r, color)

Draws a rectangle outline with rounded corners within the sprite buffer.

Parameter	Description
x	X position
y	Y position
w	Width
h	Height
r	Corner radius
color	Outline color

sprite:draw_round_rect(10, 10, 80, 30, 5, colors.WHITE)

draw_text() Draw text in the sprite

sprite:draw_text(x, y, text, color)

Renders text at the specified position within the sprite buffer. Uses the current global font size setting.

Parameter	Description
x	X position
y	Y position
text	Text string to draw
color	Text color

sprite:draw_text(10, 10, "Overlay", colors.WHITE)

fill_circle() Draw a filled circle in the sprite

sprite:fill_circle(x, y, r, color)

Draws a solid filled circle within the sprite buffer.

Parameter	Description
x	Center X
y	Center Y
r	Radius
color	Fill color

sprite:fill_circle(50, 50, 15, colors.RED)

fill_rect() Fill a rectangle in the sprite

sprite:fill_rect(x, y, w, h, color)

Draws a solid filled rectangle within the sprite buffer.

Parameter	Description
x	X position relative to sprite
y	Y position relative to sprite
w	Width in pixels
h	Height in pixels
color	Fill color

sprite:fill_rect(0, 0, 100, 50, colors.BLUE)

fill_round_rect() Draw a filled rounded rectangle in the sprite

sprite:fill_round_rect(x, y, w, h, r, color)

Draws a solid rectangle with rounded corners within the sprite buffer.

Parameter	Description
x	X position
y	Y position
w	Width
h	Height
r	Corner radius
color	Fill color

sprite:fill_round_rect(10, 10, 80, 30, 5, colors.GREEN)

get_raw() → string Return the sprite's raw pixel buffer as a binary string

sprite:get_raw() -> string

The returned string contains width*height*2 bytes in LGFX buffer format (big-endian RGB565). This is the same layout that ez.display.draw_bitmap consumes, so the bytes can be cached to flash (via ez.storage.write_file) and blitted straight back next boot with no per-pixel conversion. Useful for decoding JPEG/PNG assets once and keeping them as fast-blit raw images.

height() → integer Get sprite height

sprite:height() -> integer

Returns the height of the sprite in pixels as specified when created.

Returns: Height in pixels

local h = sprite:height()  -- Get sprite dimensions

push() Composite sprite onto display buffer

sprite:push(x, y, alpha)

Copies the sprite content to the main display buffer with optional alpha blending. Pixels matching the transparent color (set via set_transparent_color) are skipped. The alpha parameter controls overall opacity for fade effects.

Parameter	Description
x	X position on screen
y	Y position on screen
alpha	Opacity 0-255 (optional, default 255 = opaque)

sprite:push(100, 50)          -- Fully opaque
sprite:push(100, 50, 128)     -- 50% transparent

set_transparent_color() Set the color treated as transparent when pushing

sprite:set_transparent_color(color)

Sets the color key used for transparency when calling push(). Pixels matching this color will not be drawn, allowing the background to show through. Common choices are magenta (0xF81F) or black (0x0000).

Parameter	Description
color	RGB565 color to treat as transparent

sprite:set_transparent_color(0xF81F)  -- Magenta = transparent

width() → integer Get sprite width

sprite:width() -> integer

Returns the width of the sprite in pixels as specified when created.

Returns: Width in pixels

local w = sprite:width()  -- Get sprite dimensions