Display & Rendering Handlers

Display & Rendering Handlers manage the visual output, UI components, and procedural animations for Muse Gadget devices. The system abstracts hardware-specific display drivers through a unified interface, allowing the SDK to support various panels including AMOLED, LCD, and E-paper.

These handlers coordinate the Light and Versatile Graphics Library (LVGL) with device-specific Board Support Packages (BSPs). They manage UI states such as the animated avatar, settings menus, and image rendering.

Architecture and Data Flow

The display system operates as a layered architecture. The muse_ui module acts as the central coordinator, interacting with board-specific implementations and the procedural pixel-art renderer.

Rendering Stack

Board Abstraction Layer

The muse_board_t structure defines the contract for display and input operations. Each supported board must implement these handlers to integrate with the rendering engine.

Key Display Operations

Boards implement the following functions to manage the display lifecycle:

• display_start: Initializes the display controller, allocates frame buffers, and starts the LVGL task.
• display_lock / display_unlock: Provides thread-safe access to the LVGL shared state.
• set_brightness: Controls the panel backlight or internal brightness registers (0-100%).
• panel_sleep: Puts the controller into a low-power state while preserving graphics RAM (GRAM).

Buffer Management

To minimize internal RAM usage, boards often use "band" rendering. For instance, the board_vn_s3_183.c uses two buffers of 16 rows (18 KB RAM) to avoid allocating large blocks that could starve other tasks like Wi-Fi or the Muse VM.
Sources: board_vn_s3_183.c:56-57, 137-160, board_waveshare_s3_175c.c:116-120

Procedural Pixel-Art Rendering

The avatar is rendered procedurally onto a coarse 64x64 grid (MUSE_PX_W x MUSE_PX_H). This approach allows for dynamic animations without storing large frame sequences in flash memory.

The renderer uses the muse_pose_t structure to determine the avatar's visual state based on mode, time, and audio levels.

Settings UI and Navigation

The settings interface is built using LVGL components. It uses a "lazy building" strategy to save RAM: only the active page is kept in memory, while sub-pages are built when opened and deleted when the user navigates back.

UI Style Constants

The settings UI uses a specific color palette defined in the rendering handlers:

• COLOR_TEXT: 0xf2efff
• COLOR_ACCENT: 0xa77dff
• COLOR_CARD: 0x1a1530
• COLOR_DANGER: 0xff5c5c

Navigation Logic

Users navigate through a tile-based system. The primary tile shows the avatar (the "face"), and a swipe gesture transitions to the settings menu.

Image Rendering Handlers

The system supports displaying external images sent by the Muse service. Images are provided as RGB565 pixels.

Handling Logic

1. Size Validation: muse_ui_image_size checks if PSRAM is available to hold the image data.
2. Drawing: muse_ui_image_draw places the pixel data at specific coordinates.
3. Hiding: An image remains visible until a user interaction (tap, talk, or menu) triggers muse_ui_image_hide.

Sources: muse_ui.h:43-48, AGENTS.md (Kind Table)

Conclusion

Display & Rendering Handlers provide the necessary abstraction to run the Muse UI across diverse ESP32 hardware. By combining procedural animation for the avatar with efficient LVGL memory management for settings, the system maintains a responsive interface even on RAM-constrained devices. The modular design ensures that adding new boards only requires implementing the muse_board_t interface while the core UI logic remains consistent.