ez.display - ezOS Lua API

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

2D drawing primitives and text rendering for the 320x240 LCD

All drawing operations write to a double-buffered framebuffer in PSRAM. Call flush() once per frame to transfer the buffer to the physical display via DMA. Drawing functions use pixel coordinates (0,0 at top-left) and RGB565 color format. Use rgb(r,g,b) to convert from 8-bit RGB values.

Functions

clear() Clear display buffer to black

ez.display.clear()

Fills the entire display buffer with black (0x0000). This does not immediately update the physical screen - call flush() to push changes to the display. Typically called at the start of each render cycle before drawing new content.

ez.display.clear()
ez.display.draw_text(10, 10, "Hello", colors.WHITE)
ez.display.flush()

clear_clip_rect() Remove the clipping rectangle, restoring full-screen drawing

ez.display.clear_clip_rect()

create_sprite() → Sprite Create an off-screen sprite for alpha compositing

ez.display.create_sprite(width, height) -> Sprite

Allocates an off-screen RGB565 pixel buffer in PSRAM for compositing operations. Sprites support transparency and alpha blending when pushed to the display. Useful for overlays, menus, and animated elements. Remember to call destroy() or let garbage collection free the memory when done.

Parameter	Description
width	Sprite width in pixels
height	Sprite height in pixels

Returns: Sprite object, or nil if allocation failed

local overlay = ez.display.create_sprite(200, 100)
overlay:set_transparent_color(0xF81F)
overlay:clear(0xF81F)
overlay:fill_round_rect(0, 0, 200, 100, 10, colors.DARK_GRAY)
overlay:draw_text(20, 40, "Popup Menu", colors.WHITE)
overlay:push(60, 70, 200)  -- Draw at 78% opacity

draw_battery() Draw battery indicator icon

ez.display.draw_battery(x, y, percent)

Draws a battery icon with fill level corresponding to the percentage. The icon is color-coded: green for high charge, yellow for medium, red for low. Typically used in status bars.

Parameter	Description
x	X position in pixels
y	Y position in pixels
percent	Battery percentage (0-100)

local battery = ez.system.get_battery()
ez.display.draw_battery(290, 2, battery.percent)

draw_bitmap() Draw a bitmap image from raw RGB565 data

ez.display.draw_bitmap(x, y, width, height, data)

Draws an uncompressed bitmap from raw RGB565 pixel data. Each pixel is 2 bytes in big-endian format. The data length must be exactly width*height*2 bytes. This is the fastest bitmap draw method but uses the most memory.

Parameter	Description
x	X position
y	Y position
width	Bitmap width in pixels
height	Bitmap height in pixels
data	Raw RGB565 pixel data (2 bytes per pixel, big-endian)

local data = ez.storage.read_bytes("/icons/logo.raw")
ez.display.draw_bitmap(100, 50, 64, 64, data)

draw_bitmap_1bit() Draw a 1-bit bitmap with scaling and colorization

ez.display.draw_bitmap_1bit(x, y, width, height, data, scale, color)

Parameter	Description
x	X position
y	Y position
width	Bitmap width in pixels (original size)
height	Bitmap height in pixels (original size)
data	Packed 1-bit data (MSB first, row by row)
scale	Scale factor (1, 2, 3, etc.) - optional, default 1
color	RGB565 color for "on" pixels - optional, default WHITE

-- 8x8 icon(8 bytes), scaled 3x, cyan color
display.draw_bitmap_1bit(10, 10, 8, 8, icon_data, 3, colors.CYAN)

draw_bitmap_transparent() Draw a bitmap with transparency

ez.display.draw_bitmap_transparent(x, y, width, height, data, transparent_color)

Draws a bitmap where pixels matching the transparent color are skipped, allowing the background to show through. This is a simple color-key transparency (not alpha blending). Commonly used for sprites and icons.

Parameter	Description
x	X position
y	Y position
width	Bitmap width in pixels
height	Bitmap height in pixels
data	Raw RGB565 pixel data
transparent_color	RGB565 color to treat as transparent

local data = ez.storage.read_bytes("/sprites/player.raw")
-- Treat magenta(0xF81F) as transparent
ez.display.draw_bitmap_transparent(100, 100, 32, 32, data, 0xF81F)

draw_box() Draw bordered box with optional title

ez.display.draw_box(x, y, w, h, title, border_color, title_color)

Draws a box using box-drawing characters (single-line borders) with an optional title in the top border. Coordinates are in character cells, not pixels. Used for creating dialog boxes, menus, and panels in text-mode UIs.

Parameter	Description
x	X position in character cells
y	Y position in character cells
w	Width in character cells
h	Height in character cells
title	Optional title string
border_color	Border color (optional)
title_color	Title color (optional)

-- Dialog box with title
ez.display.draw_box(5, 3, 30, 10, "Confirm", colors.BORDER, colors.HIGHLIGHT)

draw_char() Draw a single character

ez.display.draw_char(x, y, char, color)

Draws a single character at the specified position. Only the first character of the provided string is rendered. More efficient than draw_text() when you only need one character, such as for custom cursors or icon fonts.

Parameter	Description
x	X position in pixels
y	Y position in pixels
char	Character to draw (first char of string)
color	Character color (optional)

ez.display.draw_char(100, 100, ">", colors.GREEN)  -- Cursor
ez.display.draw_char(50, 50, "X", colors.RED)      -- Close icon

draw_circle() Draw circle outline

ez.display.draw_circle(x, y, r, color)

Draws a 1-pixel wide circle outline using the midpoint circle algorithm. The center point and radius define the circle. Partially off-screen circles are clipped correctly.

Parameter	Description
x	Center X position
y	Center Y position
r	Radius
color	Circle color (optional)

-- Ring around a point
ez.display.draw_circle(160, 120, 50, colors.CYAN)

draw_gps() Draw a GPS fix indicator (3 ascending orange bars + satellite dot).

ez.display.draw_gps(x, y, bars)

Parameter	Description
x	X position in pixels
y	Y position in pixels
bars	Fix quality (0-3 bars filled)

draw_hline() Draw a 1-pixel horizontal line in pixel coordinates

ez.display.draw_hline(x, y, w, color)

Parameter	Description
x	X start position in pixels
y	Y position in pixels
w	Width in pixels
color	Line color (RGB565)

draw_indexed_bitmap() Draw a 3-bit indexed bitmap using a color palette

ez.display.draw_indexed_bitmap(x, y, width, height, data, palette)

Parameter	Description
x	X position
y	Y position
width	Bitmap width in pixels
height	Bitmap height in pixels
data	Packed 3-bit pixel indices (8 pixels packed into 3 bytes)
palette	Table of 8 RGB565 color values

local palette = {0x0000, 0x2104, 0x4208, 0x630C, 0x8410, 0xC618, 0xE71C, 0xFFFF}
display.draw_indexed_bitmap(0, 0, 256, 256, tile_data, palette)

draw_indexed_bitmap_scaled() Draw a scaled portion of a 3-bit indexed bitmap

ez.display.draw_indexed_bitmap_scaled(x, y, dest_w, dest_h, data, palette, src_x, src_y, src_w, src_h)

Parameter	Description
x	Destination X position
y	Destination Y position
dest_w	Destination width
dest_h	Destination height
data	Packed 3-bit pixel indices (256x256 source assumed)
palette	Table of 8 RGB565 color values
src_x	Source X offset in pixels
src_y	Source Y offset in pixels
src_w	Source width to sample
src_h	Source height to sample

draw_jpeg() Decode and draw a JPEG image from memory

ez.display.draw_jpeg(x, y, data [, scale_x, scale_y, off_x, off_y, max_w, max_h])

Decodes JPEG data and draws it to the display at the given position. Supports optional pan (off_x/off_y crop the source image) and zoom (scale_x/y). Decode happens in C++ using the LovyanGFX built-in TJpgDec decoder.

Parameter	Description
x	X position on screen
y	Y position on screen
data	JPEG file data as a string (from async_read or file load)
scale_x	Horizontal scale factor (default 1.0)
scale_y	Vertical scale factor (default = scale_x)
off_x	Source image X offset (pan, default 0)
off_y	Source image Y offset (pan, default 0)
max_w	Maximum output width (default 0 = unlimited)
max_h	Maximum output height (default 0 = unlimited)

Returns: true on success, false on decode error

draw_line() Draw a line between two points

ez.display.draw_line(x1, y1, x2, y2, color)

Draws a 1-pixel wide line using Bresenham's algorithm. Supports any angle including diagonal lines. Coordinates can extend off-screen and will be clipped appropriately.

Parameter	Description
x1	Start X position
y1	Start Y position
x2	End X position
y2	End Y position
color	Line color (optional)

-- Diagonal line
ez.display.draw_line(0, 0, 319, 239, colors.WHITE)
-- Horizontal separator
ez.display.draw_line(10, 100, 310, 100, colors.GRAY)

draw_pixel() Draw a single pixel

ez.display.draw_pixel(x, y, color)

Sets a single pixel in the frame buffer. While simple, this is the slowest way to draw - prefer fill_rect or other primitives when possible. Useful for plotting graphs, custom patterns, or debugging.

Parameter	Description
x	X position in pixels
y	Y position in pixels
color	Pixel color (optional)

-- Plot a point
ez.display.draw_pixel(160, 120, colors.RED)

draw_png() Decode and draw a PNG image from memory

ez.display.draw_png(x, y, data [, scale_x, scale_y, off_x, off_y, max_w, max_h])

Same pan/zoom parameters as draw_jpeg.

Returns: true on success

draw_progress() Draw a progress bar

ez.display.draw_progress(x, y, w, h, progress, fg_color, bg_color)

Draws a horizontal progress bar with a background track and filled portion. The progress value is clamped to 0.0-1.0 range. Useful for loading indicators, file transfers, or any percentage-based visualization.

Parameter	Description
x	X position in pixels
y	Y position in pixels
w	Width in pixels
h	Height in pixels
progress	Progress value (0.0 to 1.0)
fg_color	Foreground color (optional)
bg_color	Background color (optional)

-- Download progress at 75%
ez.display.draw_progress(20, 150, 280, 12, 0.75, colors.GREEN, colors.DARK_GRAY)

draw_rect() Draw rectangle outline

ez.display.draw_rect(x, y, w, h, color)

Draws a 1-pixel wide rectangle outline (not filled). Useful for borders, focus indicators, and bounding boxes. The outline is drawn inside the specified dimensions.

Parameter	Description
x	X position in pixels
y	Y position in pixels
w	Width in pixels
h	Height in pixels
color	Outline color (optional)

-- Focus border around selected item
ez.display.draw_rect(10, 50, 300, 25, colors.HIGHLIGHT)

draw_round_rect() Draw rounded rectangle outline

ez.display.draw_round_rect(x, y, w, h, r, color)

Draws a rectangle outline with rounded corners. The corner radius should be less than half the smaller dimension. Commonly used for modern UI elements.

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

-- Rounded button outline
ez.display.draw_round_rect(100, 180, 120, 40, 8, colors.WHITE)

draw_signal() Draw signal strength indicator

ez.display.draw_signal(x, y, bars)

Draws a signal strength icon with 0-4 ascending bars, similar to mobile phone signal indicators. Used to show radio or mesh network signal quality.

Parameter	Description
x	X position in pixels
y	Y position in pixels
bars	Signal strength (0-4 bars)

-- Strong signal
ez.display.draw_signal(270, 2, 4)
-- Weak signal
ez.display.draw_signal(270, 2, 1)

draw_text() Draw text at pixel coordinates

ez.display.draw_text(x, y, text, color)

Renders a text string at the specified pixel position using the current font size. The position specifies the top-left corner of the first character. Supports UTF-8 encoded strings including special characters.

Parameter	Description
x	X position in pixels
y	Y position in pixels
text	Text string to draw
color	Text color (optional, defaults to TEXT)

ez.display.draw_text(10, 20, "Hello World", colors.WHITE)
ez.display.draw_text(10, 40, "Status: OK", colors.GREEN)

draw_text_bg() Draw text with a background rectangle

ez.display.draw_text_bg(x, y, text, fg_color, bg_color, padding)

Draws text with a solid background rectangle for better readability over complex backgrounds like images or maps. The background rectangle is sized automatically based on text dimensions plus the specified padding.

Parameter	Description
x	X position in pixels
y	Y position in pixels
text	Text string to draw
fg_color	Text color
bg_color	Background color
padding	Padding around text (optional, defaults to 1)

-- Label with dark background for contrast
ez.display.draw_text_bg(50, 100, "GPS: Locked", colors.GREEN, colors.BLACK, 2)

draw_text_centered() Draw horizontally centered text

ez.display.draw_text_centered(y, text, color)

Draws text centered horizontally on the display. The text width is calculated automatically and the X position is computed to center the string. Useful for titles, headings, and status messages.

Parameter	Description
y	Y position in pixels
text	Text string to draw
color	Text color (optional, defaults to TEXT)

ez.display.draw_text_centered(10, "Settings", colors.WHITE)
ez.display.draw_text_centered(120, "No messages", colors.GRAY)

draw_text_shadow() Draw text with a shadow offset

ez.display.draw_text_shadow(x, y, text, fg_color, shadow_color, offset)

Draws text with a drop shadow effect by rendering the text twice: first at an offset position in the shadow color, then at the original position in the foreground color. Creates a pseudo-3D effect that improves readability.

Parameter	Description
x	X position in pixels
y	Y position in pixels
text	Text string to draw
fg_color	Text color
shadow_color	Shadow color (optional, defaults to black)
offset	Shadow offset in pixels (optional, defaults to 1)

-- Title with drop shadow
ez.display.draw_text_shadow(20, 10, "ezOS", colors.WHITE, colors.DARK_GRAY, 2)

draw_triangle() Draw triangle outline

ez.display.draw_triangle(x1, y1, x2, y2, x3, y3, color)

Draws a triangle outline by connecting three vertices with lines. Vertices can be specified in any order. Useful for arrows, pointers, and icons.

Parameter	Description
x1	First vertex X
y1	First vertex Y
x2	Second vertex X
y2	Second vertex Y
x3	Third vertex X
y3	Third vertex Y
color	Outline color (optional)

-- Arrow pointing right
ez.display.draw_triangle(100, 110, 100, 130, 120, 120, colors.WHITE)

draw_wifi() Draw a WiFi signal strength icon (3 ascending cyan bars).

ez.display.draw_wifi(x, y, bars)

Parameter	Description
x	X position in pixels
y	Y position in pixels
bars	Signal strength (0-3 bars filled)

fill_circle() Draw filled circle

ez.display.fill_circle(x, y, r, color)

Draws a solid filled circle. Useful for indicators, buttons, or markers.

Parameter	Description
x	Center X position
y	Center Y position
r	Radius
color	Fill color (optional)

-- Status indicator dot
ez.display.fill_circle(300, 10, 5, colors.GREEN)

fill_rect() Fill a rectangle with color

ez.display.fill_rect(x, y, w, h, color)

Draws a solid filled rectangle. One of the most commonly used drawing primitives for backgrounds, buttons, selection highlights, and clearing specific screen regions. Coordinates can extend off-screen (clipped automatically).

Parameter	Description
x	X position in pixels
y	Y position in pixels
w	Width in pixels
h	Height in pixels
color	Fill color (optional)

-- Selection highlight
ez.display.fill_rect(0, 50, 320, 20, colors.SELECTION)
-- Button background
ez.display.fill_rect(100, 200, 120, 30, colors.BLUE)

fill_rect_dithered() Fill a rectangle with dithered pattern (simulates transparency)

ez.display.fill_rect_dithered(x, y, w, h, color, density)

Fills a rectangle with a dithered pattern to simulate semi-transparency on hardware that doesn't support alpha blending. At 50% density, creates a checkerboard pattern. Lower density = fewer pixels filled. Useful for overlays and shadows.

Parameter	Description
x	X position in pixels
y	Y position in pixels
w	Width in pixels
h	Height in pixels
color	Fill color
density	Percentage of pixels filled (0-100, default 50 for checkerboard)

-- Semi-transparent overlay
ez.display.fill_rect_dithered(0, 0, 320, 240, colors.BLACK, 50)
-- Light shadow effect
ez.display.fill_rect_dithered(5, 5, 100, 50, colors.BLACK, 25)

fill_rect_hlines() Fill a rectangle with horizontal line pattern

ez.display.fill_rect_hlines(x, y, w, h, color, spacing)

Fills a rectangle with horizontal scan lines at regular intervals. Creates a striped pattern that can simulate CRT effects, partial fills, or decorative backgrounds. Spacing of 2 fills every other row (50% fill).

Parameter	Description
x	X position in pixels
y	Y position in pixels
w	Width in pixels
h	Height in pixels
color	Fill color
spacing	Line spacing (2 = 50%, 3 = 33%, etc., default 2)

-- Retro scanline effect
ez.display.fill_rect_hlines(0, 0, 320, 240, colors.BLACK, 2)

fill_rect_vlines() Fill a rectangle with vertical line pattern

ez.display.fill_rect_vlines(x, y, w, h, color, spacing)

Fills a rectangle with vertical lines at regular intervals. Creates a vertical striped pattern. Spacing of 2 fills every other column (50% fill).

Parameter	Description
x	X position in pixels
y	Y position in pixels
w	Width in pixels
h	Height in pixels
color	Fill color
spacing	Line spacing (2 = 50%, 3 = 33%, etc., default 2)

-- Vertical stripe pattern
ez.display.fill_rect_vlines(10, 10, 100, 100, colors.BLUE, 3)

fill_round_rect() Draw filled rounded rectangle

ez.display.fill_round_rect(x, y, w, h, r, color)

Draws a solid filled rectangle with rounded corners. Commonly used for buttons, cards, and modern UI panels.

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

-- Button background
ez.display.fill_round_rect(100, 180, 120, 40, 8, colors.BLUE)
ez.display.draw_text(130, 190, "OK", colors.WHITE)

fill_triangle() Draw filled triangle

ez.display.fill_triangle(x1, y1, x2, y2, x3, y3, color)

Draws a solid filled triangle. The fill uses scan-line rasterization. Useful for filled arrows, play buttons, and decorative elements.

Parameter	Description
x1	First vertex X
y1	First vertex Y
x2	Second vertex X
y2	Second vertex Y
x3	Third vertex X
y3	Third vertex Y
color	Fill color (optional)

-- Play button triangle
ez.display.fill_triangle(130, 100, 130, 140, 170, 120, colors.GREEN)

flush() Flush buffer to physical display

ez.display.flush()

Transfers the internal frame buffer to the physical LCD via DMA. Call this after all drawing operations are complete for the current frame. The T-Deck uses a 320x240 RGB565 display with hardware-accelerated transfers.

ez.display.clear()
ez.display.draw_text(10, 10, "Frame complete", colors.GREEN)
ez.display.flush()  -- Push to screen

get_cols() → integer Get display columns

ez.display.get_cols() -> integer

Returns the number of character columns based on current font size. Used for text-mode layouts where positioning is in character cells rather than pixels.

Returns: Number of character columns

local cols = ez.display.get_cols()  -- e.g., 40 with 8px font

get_font_height() → integer Get font character height

ez.display.get_font_height() -> integer

Returns the height in pixels of a character cell in the current font. This is the line height including spacing. Useful for calculating vertical layout.

Returns: Character height in pixels

local fh = ez.display.get_font_height()  -- e.g., 16 for medium font
for i, line in ipairs(lines) do
ez.display.draw_text(10, 10 + (i-1) * fh, line, colors.WHITE)
end

get_font_width() → integer Get font character width

ez.display.get_font_width() -> integer

Returns the width in pixels of a single character in the current font. Monospace fonts have uniform character width. Useful for calculating text positioning.

Returns: Character width in pixels

local fw = ez.display.get_font_width()  -- e.g., 8 for medium font
local x = 10 + 5 * fw  -- Position after 5 characters

get_height() → integer Get display height

ez.display.get_height() -> integer

Returns the display height in pixels. The T-Deck has a 320x240 IPS LCD.

Returns: Height in pixels

local h = ez.display.get_height()  -- Returns 240

get_image_size() → width, height Parse JPEG or PNG header to get dimensions without rendering

ez.display.get_image_size(data) -> width, height

Scans the file header of a JPEG (SOF marker) or PNG (IHDR chunk) and returns image dimensions. Both formats are auto-detected by file signature. Returns nil, nil if the format is unrecognized or the header is incomplete.

Returns: width, height (integers) or nil, nil on error

get_rows() → integer Get display rows

ez.display.get_rows() -> integer

Returns the number of character rows based on current font size. Used for text-mode layouts where positioning is in character cells.

Returns: Number of character rows

local rows = ez.display.get_rows()  -- e.g., 15 with 16px font

get_width() → integer Get display width

ez.display.get_width() -> integer

Returns the display width in pixels. The T-Deck has a 320x240 IPS LCD. Use this for portable layouts that adapt to different display sizes.

Returns: Width in pixels

local w = ez.display.get_width()  -- Returns 320

rgb() → integer Convert RGB to RGB565 color value

ez.display.rgb(r, g, b) -> integer

Converts 8-bit RGB components to the 16-bit RGB565 format used by the display. RGB565 packs red (5 bits), green (6 bits), and blue (5 bits) into a single 16-bit value. Some color precision is lost in this conversion.

Parameter	Description
r	Red component (0-255)
g	Green component (0-255)
b	Blue component (0-255)

Returns: RGB565 color value

local purple = ez.display.rgb(128, 0, 255)
local orange = ez.display.rgb(255, 165, 0)
ez.display.fill_rect(10, 10, 50, 50, purple)

save_screenshot() → boolean Save current display contents as BMP screenshot to SD card

ez.display.save_screenshot(path) -> boolean

Parameter	Description
path	File path on SD card (e.g., "/screenshots/screen_001.bmp")

Returns: true if saved successfully, false on error

local ok = display.save_screenshot("/screenshots/capture.bmp")

scene_add_aabb() Append an axis-aligned box (5 visible faces, bottom omitted).

ez.display.scene_add_aabb(scene, x0,y0,z0, x1,y1,z1, side_color, top_color)

The bottom face is skipped because every use so far has the box resting on a floor surface that already covers it — drawing it wastes triangle budget for no visible difference. `side_color` is used for the four vertical faces; `top_color` for the top cap. Pass the same colour for both if you want a monochrome box. Corners are given as two opposite points: (x0,y0,z0) and (x1,y1,z1). The call normalises them so the caller doesn't have to care which is min and which is max.

scene_add_billboard() Append a camera-facing quad (2 triangles) at world position

ez.display.scene_add_billboard(scene, wx, wy, wz, half_w, full_h, color)

scene_add_quad() Append a planar quad as two triangles in one call.

ez.display.scene_add_quad(scene, x1,y1,z1, x2,y2,z2, x3,y3,z3, x4,y4,z4, color)

Convenience wrapper for the extremely common "submit a flat surface" pattern (ground tiles, walls, roof panels, road segments). Winding order is the same as the tris it expands to: CCW as seen from the visible side. Saves 1 Lua→C crossing + 10 stack reads per surface compared to two scene_add_tri calls; for a world built from hundreds of quads this cuts build-time perceptibly.

scene_add_road_strip() Append a ribbon of quads along a centerline, width held

ez.display.scene_add_road_strip(scene, points_table, half_width, y, color)

`points_table` is an array of {x, z} pairs — typically a closed track ring, but works for open roads too. Consecutive points define a segment; for each segment, this helper computes a perpendicular direction (rotated 90° in the XZ plane) and emits a flat quad of length=segment and width=2*half_width centred on the segment, all at vertical `y`. No allocation per segment — the quads append directly into the scene buffer. Use for: race tracks, footpaths, rivers, belt ribbons — anything whose centerline is known and whose cross-section is a constant horizontal width.

scene_add_tri() Append a world-space triangle. CCW winding when viewed from the

ez.display.scene_add_tri(scene, x1,y1,z1, x2,y2,z2, x3,y3,z3, color)

scene_clear()

ez.display.scene_clear(scene)

scene_count() → int Update the billboard camera context.

ez.display.scene_count(scene) -> int

The billboard helpers (scene_add_billboard, scene_add_billboard_split) need to know where the camera is and which way it faces to orient their quads. Call this once per frame before submitting billboards — saves passing the parameters on every primitive call and lets the C side do the right/forward math in native code instead of Lua.

Parameter	Description
fwd_nudge	optional world-space distance to shift billboards

scene_mark_static() → int Return the current triangle count so callers can later restore

ez.display.scene_mark_static(scene) -> int

scene_new() → Scene3D Allocate a new 3D scene buffer

ez.display.scene_new() -> Scene3D

scene_reset_to() Truncate the scene's triangle buffer back to `count` triangles.

ez.display.scene_reset_to(scene, count)

set_brightness() Set backlight brightness

ez.display.set_brightness(level)

Controls the LCD backlight PWM level. Lower values save battery but reduce visibility. The setting persists until changed. Use 0 to turn off the backlight completely (screen will appear black but is still rendering).

Parameter	Description
level	Brightness level (0-255)

ez.display.set_brightness(200)  -- Bright, good for indoor use
ez.display.set_brightness(50)   -- Dim, saves battery
ez.display.set_brightness(0)    -- Backlight off

set_clip_rect() Set a clipping rectangle for all subsequent draw operations

ez.display.set_clip_rect(x, y, w, h)

Restricts drawing to the specified rectangle. Any pixels drawn outside this region are discarded. Use clear_clip_rect() to remove. Essential for scrollable containers that must not draw outside their bounds.

Parameter	Description
x	Left edge of clip region
y	Top edge of clip region
w	Width of clip region
h	Height of clip region

set_font_size() Set font size

ez.display.set_font_size(size)

Changes the current font size used by all text drawing functions. The font size affects text_width(), get_font_width(), and get_font_height() return values. Available sizes: tiny (6px), small (8px), medium (12px), large (16px).

Parameter	Description
size	Font size string: "tiny", "small", "medium", or "large"

ez.display.set_font_size("large")
ez.display.draw_text(10, 10, "Big Title", colors.WHITE)
ez.display.set_font_size("small")
ez.display.draw_text(10, 30, "Small details", colors.GRAY)

set_font_style() Set font style (weight/slope)

ez.display.set_font_style(style)

Selects a style variant of the current AA font — bold, italic, or both. Bitmap mono fonts (tiny/small/medium/large) ignore this; they only ship in a regular weight. The generated AA pack covers all four combinations per size (see tools/gen_aa_font.py).

Parameter	Description
style	One of "regular", "bold", "italic", or "bold_italic"

ez.display.set_font_size("small_aa")
ez.display.set_font_style("bold")
ez.display.draw_text(10, 10, "Heading", colors.WHITE)
ez.display.set_font_style("regular")

text_width() → integer Get pixel width of text string

ez.display.text_width(text) -> integer

Calculates the width in pixels that the given text would occupy when rendered with the current font size. Essential for text alignment, centering, truncation, and layout calculations.

Parameter	Description
text	Text string to measure

Returns: Width in pixels

local text = "Hello World"
local width = ez.display.text_width(text)
local x = (320 - width) / 2  -- Center on 320px display
ez.display.draw_text(x, 100, text, colors.WHITE)

Bus Messages

theme/colors payload: string Color scheme name Posted when the color scheme is changed

Fired when ThemeManager.set_colors() is called. UI components should refresh their color values.

Payload: string Color scheme name

ez.bus.subscribe("theme/colors", function(scheme)
self.bg_color = ThemeManager.colors.background
end)

theme/icons payload: string Icon pack name Posted when the icon pack is changed

Fired when ThemeManager.set_icon_pack() is called. Components displaying icons should refresh their cached icon references.

Payload: string Icon pack name

ez.bus.subscribe("theme/icons", function(pack)
self:reload_icons()
end)

theme/wallpaper payload: string Wallpaper name (e.g., "clouds", "mountains"... Posted when the wallpaper is changed

Fired when ThemeManager.set_wallpaper() is called. Screens can subscribe to update their rendering if they display the wallpaper.

Payload: string Wallpaper name (e.g., "clouds", "mountains", "none")

ez.bus.subscribe("theme/wallpaper", function(name)
print("Wallpaper changed to: " .. name)
end)