Scenes

A scene is a named collection of buffers and objects. Only the selected scene is rendered, but inactive scenes can stay resident for quick switching, stats collection, or later compaction.

Scene Lifecycle

from tuix.core import scenes

scenes.init_scene('Main')
scenes.select_scene('Main')

# later
scenes.clear_scene('Main')   # keep the scene, remove buffers
scenes.free_scene('Main')    # remove the scene

Active Scene

Use scenes.select_scene(name) for explicit scene switching. The registry proxy also exposes registry.registry.current_scene_name for compatibility and low-level control.

Focus And Modal State

Keyboard input is routed through scene focus. Dialogs and other modal flows can activate a modal UID so input is constrained to that subtree until the modal is deactivated.

scenes.set_focus('Main', widget_uid)
scenes.set_previous_focus('Main')

scenes.activate_modal('Main', dialog_uid)
active = scenes.get_active_modal('Main')
scenes.deactivate_modal('Main', dialog_uid)

Transactions

v0.5 exposes scene transactions for grouping multiple widget updates. Use them around batches of changes that should be committed together before the next visible frame.

scenes.begin_transaction('Main')
# update several widgets
scenes.commit_transaction('Main')

Stats And Compaction

Scenes track activity and memory statistics such as buffer_count, current_focus, last_active_frame, pixel_bytes, and approx_heap_bytes. Cold scene compaction can release pixel storage from inactive scenes while preserving the scene structure.

stats = scenes.get_scene_stats('Main')
freed = scenes.compact_scene_pixels('Main')
compacted_count = scenes.compact_cold_scenes(
    cold_frames=300,
    min_pixel_bytes=1_000_000,
    keep_active_scene=True,
)

Hierarchy

Buffers can form parent/child trees. v0.5 layout builders rely on this hierarchy so parent containers can rebuild child geometry before compositing. Self-parenting and cycles are rejected by the buffer layer.