yaze/docs/internal/architecture/graphics_system_architecture.md

Graphics System Architecture

Status: Complete Last Updated: 2025-11-21 Related Code: src/app/gfx/, src/app/editor/graphics/

This document outlines the architecture of the Graphics System in YAZE, including resource management, compression pipelines, and rendering workflows.

Overview

The graphics system is designed to handle SNES-specific image formats (indexed color, 2BPP/3BPP) while efficiently rendering them using modern hardware acceleration via SDL2. It uses a centralized resource manager (Arena) to pool resources and manage lifecycle.

Core Components

1. The Arena (src/app/gfx/resource/arena.h)

The Arena is a singleton class that acts as the central resource manager for all graphics.

Responsibilities:

• Resource Management: Manages the lifecycle of SDL_Texture and SDL_Surface objects using RAII wrappers with custom deleters
• Graphics Sheets: Holds a fixed array of 223 Bitmap objects representing the game's complete graphics space (indexed 0-222)
• Background Buffers: Manages BackgroundBuffers for SNES BG1 and BG2 layer rendering
• Deferred Rendering: Implements a command queue (QueueTextureCommand) to batch texture creation/updates, preventing UI freezes during heavy loads
• Memory Pooling: Reuses textures and surfaces to minimize allocation overhead

Key Methods:

• QueueTextureCommand(type, bitmap): Queue a texture operation for batch processing
• ProcessTextureQueue(renderer): Process all queued texture commands
• NotifySheetModified(sheet_index): Notify when a graphics sheet changes to synchronize editors
• gfx_sheets(): Get all 223 graphics sheets
• mutable_gfx_sheet(index): Get mutable reference to a specific sheet

2. Bitmap (src/app/gfx/core/bitmap.h)

Represents a single graphics sheet or image optimized for SNES ROM editing.

Key Features:

• Data Storage: Stores raw pixel data as std::vector<uint8_t> (indices into a palette)
• Palette: Each bitmap owns a SnesPalette (256 colors maximum)
• Texture Management: Manages an SDL_Texture handle and syncs CPU pixel data to GPU
• Dirty Tracking: Tracks modified regions to minimize texture upload bandwidth
• Tile Extraction: Provides methods like Get8x8Tile(), Get16x16Tile() for SNES tile operations

Important Synchronization Rules:

• Never modify SDL_Texture directly - always modify the Bitmap data
• Use set_data() for bulk updates to keep CPU and GPU in sync
• Use WriteToPixel() for single-pixel modifications
• Call UpdateTexture() to sync changes to GPU

3. Graphics Editor (src/app/editor/graphics/graphics_editor.cc)

The primary UI for viewing and modifying graphics.

• Sheet Editor: Pixel-level editing of all 223 sheets
• Palette Integration: Fetches palette groups from the ROM (Overworld, Dungeon, Sprites) to render sheets correctly
• Tools: Pencil, Fill, Select, Zoom
• Real-time Display: Uses Canvas class for drawing interface

4. IRenderer Interface (src/app/gfx/backend/irenderer.h)

Abstract interface for the rendering backend (currently implemented by SdlRenderer). This decouples graphics logic from SDL-specific calls, enabling:

• Testing with mock renderers
• Future backend swaps (e.g., Vulkan, Metal)

Rendering Pipeline

1. Loading Phase

Source: ROM compressed data Process:

1. Iterates through all 223 sheet indices
2. Determines format based on index range (2BPP, 3BPP compressed, 3BPP uncompressed)
3. Calls decompression functions
4. Converts to internal 8-bit indexed format
5. Stores result in Arena.gfx_sheets_

Performance: Uses deferred loading via texture queue to avoid blocking

2. Composition Phase (Rooms/Overworld)

Process:

1. Room/Overworld logic draws tiles from gfx_sheets into a BackgroundBuffer (wraps a Bitmap)
2. This drawing happens on CPU, manipulating indexed pixel data
3. Each room/map maintains its own Bitmap of rendered data

Key Classes:

• BackgroundBuffer: Manages BG1 and BG2 layer rendering for a single room/area
• Methods like Room::RenderRoomGraphics() handle composition

3. Texture Update Phase

Process:

1. Editor checks if bitmaps are marked "dirty" (modified since last render)
2. Modified bitmaps queue a TextureCommand::UPDATE to Arena
3. Arena processes queue, uploading pixel data to SDL textures
4. This batching avoids per-frame texture uploads

4. Display Phase

Process:

1. Canvas or UI elements request the SDL_Texture from a Bitmap
2. Texture is rendered to screen using ImGui or direct SDL calls
3. Grid, overlays, and selection highlights are drawn on top

Compression Pipeline

YAZE uses the LC-LZ2 algorithm (often called "Hyrule Magic" compression) for ROM I/O.

Supported Formats

Format	Sheets	Bits Per Pixel	Usage	Location
3BPP (Compressed)	0-112, 127-217	3	Most graphics	Standard ROM
2BPP (Compressed)	113-114, 218-222	2	HUD, Fonts, Effects	Standard ROM
3BPP (Uncompressed)	115-126	3	Link Player Sprites	0x080000

Loading Process

Entry Point: src/app/rom.cc:Rom::LoadFromFile()

1. Iterates through all 223 sheet indices
2. Determines format based on index range
3. Calls gfx::lc_lz2::DecompressV2() (or DecompressV1() for compatibility)
4. For uncompressed sheets (115-126), copies raw data directly
5. Converts result to internal 8-bit indexed format
6. Stores in Arena.gfx_sheets_[index]

Saving Process

Process:

1. Get mutable reference: auto& sheet = Arena::Get().mutable_gfx_sheet(index)
2. Make modifications to sheet.mutable_data()
3. Notify Arena: Arena::Get().NotifySheetModified(index)
4. When saving ROM:
   • Convert 8-bit indexed data back to 2BPP/3BPP format
   • Compress using gfx::lc_lz2::CompressV3()
   • Write to ROM, handling pointer table updates if sizes change

Link Graphics (Player Sprites)

Location: ROM offset 0x080000 Format: Uncompressed 3BPP Sheet Indices: 115-126 Editor: GraphicsEditor provides a "Player Animations" view Structure: Sheets are assembled into poses using OAM (Object Attribute Memory) tables

Canvas Interactions

The Canvas class (src/app/gui/canvas/canvas.h) is the primary rendering engine.

Drawing Operations:

• DrawBitmap(): Renders a sheet texture to the canvas
• DrawSolidTilePainter(): Preview of brush before commit
• DrawTileOnBitmap(): Commits pixel changes to Bitmap data

Selection and Tools:

• DrawSelectRect(): Rectangular region selection
• Context Menu: Right-click for Zoom, Grid, view resets

Coordinate Systems:

• Canvas Pixels: Unscaled (128-512 range depending on sheet)
• Screen Pixels: Scaled by zoom level
• Tile Coordinates: 8x8 or 16x16 tiles for SNES editing

Best Practices

• Never modify SDL_Texture directly: Always modify the Bitmap data and call UpdateTexture() or queue it
• Use QueueTextureCommand: For bulk updates, queue commands to avoid stalling the main thread
• Respect Palettes: Remember that Bitmap data is just indices. Visual result depends on the associated SnesPalette
• Sheet Modification: When modifying a global graphics sheet, notify Arena via NotifySheetModified() to propagate changes to all editors
• Deferred Loading: Always use the texture queue system for heavy operations to prevent UI freezes

Future Improvements

• Vulkan/Metal Backend: The IRenderer interface allows for potentially swapping SDL2 for a more modern API
• Compute Shaders: Palette swapping could potentially be moved to GPU using shaders instead of CPU-side pixel manipulation
• Streaming Graphics: Load/unload sheets on demand for very large ROM patches