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. In v0.3, buffers can form parent/child trees through parent_uid, and compositing walks traversal chains with z-index ordering.

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"

Hierarchy and Parenting

Use buffers.set_buffer_parent(scene_name, uid, parent_uid) to attach a child buffer to a parent buffer. v0.3 validates parent relations: self-parent and cyclic relationships are rejected.

When a parent buffer is deleted, children are safely reparented so scene integrity is preserved.

Compositing Order

In v0.3, root buffers are ordered by z-index and each parent/child subtree is composited as a traversal chain. This preserves tree-local layering while still allowing scene-wide root ordering.

Scene Activity Metrics

v0.3 tracks scene activity counters including frame counter fields such as last_active_frame and last_compacted_frame. Use scenes.get_scene_stats() for data-first maintenance and compaction decisions.

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.