Scenes

Scenes are the top-level containers in TUIX. Every widget lives inside a scene, and only the active scene is rendered each frame.

What Is a Scene

A scene is a named collection of widget buffers. Internally, each scene (TuixScene) holds an ordered array of TuixBuffer pointers. When the engine renders a frame, it composites only the buffers belonging to the currently active scene.

Scene names are byte strings (e.g. b"main", b"settings"). Names are stored once in the global registry and compared by pointer rather than by value, making scene lookups O(1) after the initial creation.

Scene Lifecycle

1. Create a scene: scenes.init_scene(b"name")
2. Set it as active: registry.registry.current_scene_name = b"name"
3. Create widgets in the scene: objects.create_object(builder, b"name", ...)
4. Clear widget contents (optional): scenes.clear_scene(b"name")
5. Destroy the scene: scenes.free_scene(b"name")

Active Scene

Only one scene can be active at a time. The active scene is set via registry.registry.current_scene_name. During main_loop(), only the active scene's widgets are rendered. Switching scenes is instant — set the property and the next frame renders the new scene.

# Switch between scenes
scenes.init_scene(b"menu")
scenes.init_scene(b"game")

# Show the menu scene
registry.registry.current_scene_name = b"menu"

# Later, switch to game scene
registry.registry.current_scene_name = b"game"

Compositing Order

Buffers within a scene are composited in creation order (painter's algorithm). The first widget created is drawn first (background), and later widgets are drawn on top. If two widgets overlap, the later one's pixels overwrite the earlier one's.

Memory Management

Scenes and their buffers are manually managed. Call scenes.free_scene() to release all buffers and the scene structure. Call scenes.clear_scene() to free all buffers but keep the scene allocated for reuse. Scenes use exponential growth (4 → 8 → 16 → ...) for their internal buffer arrays to minimize reallocations.