Scenes API

The scenes module (tuix.core.scenes) manages scene lifecycle, scene queries, and focus routing between interactive widgets.

scenes.init_scene(name)

from tuix.core import scenes

result = scenes.init_scene(b"main")

Parameter	Type	Description
name	bytes	Unique scene name

Returns	Description
int	0 on success, 1 if scene name already exists

Creates a new scene with the given name. Scenes use exponential growth for their internal buffer arrays (initial capacity 4, doubling on overflow). Duplicate names are rejected.

scenes.free_scene(name)

scenes.free_scene(b"main")

Parameter	Type	Description
name	bytes	Scene name to destroy

Destroys a scene and frees all its buffers and associated memory. The scene cannot be used after this call.

scenes.clear_scene(name)

scenes.clear_scene(b"main")

Parameter	Type	Description
name	bytes	Scene name to clear

Frees all buffers in the scene but keeps the scene structure allocated. Use this to remove all widgets from a scene without destroying the scene itself. New widgets can be added to the scene after clearing.

scenes.get_scene(name)

scene_ptr = scenes.get_scene(b"main")

Parameter	Type	Description
name	bytes \| str	Scene name to look up

Returns	Description
int	Native scene pointer address (0 if not found)

scenes.get_scenes()

all_scenes = scenes.get_scenes()

Returns a Python-side view of the native scenes collection exposed by the Cython bridge.

scenes.set_focus(scene_name, uid)

scenes.set_focus(b"main", input_uid)

Parameter	Type	Description
scene_name	bytes \| str	Target scene
uid	int	Widget UID that should receive input focus

Returns	Description
int	0 on success, non-zero on failure

Focus routing is scene-local. Use this when multiple interactive widgets share one scene and only one should handle keyboard events.

scenes.set_previous_focus(scene_name)

scenes.set_previous_focus(b"main")

Restores the previous focused widget for the given scene.

scenes.get_scene_stats(scene_name)

stats = scenes.get_scene_stats(b"main")

Returns	Description
dict \| None	Scene stats dictionary containing: buffer_count, active, current_focus, last_active_frame, last_compacted_frame, pixel_bytes, approx_heap_bytes

scenes.compact_scene_pixels(scene_name)

freed_bytes = scenes.compact_scene_pixels(b"main")

Returns	Description
int	Number of pixel bytes freed by conservative scene compaction

scenes.compact_cold_scenes(cold_frames, min_pixel_bytes, keep_active_scene=True)

count = scenes.compact_cold_scenes(120, 64 * 1024, keep_active_scene=True)

Parameter	Type	Description
cold_frames	int	Minimum inactivity window in frames
min_pixel_bytes	int	Only compact scenes with at least this many pixel bytes
keep_active_scene	bool	If True, skip the currently active scene

Returns	Description
int	Number of compacted scenes

Data-First Cache Strategyv0.3 favors measuring and compacting cold scenes over eager global caching. Start with get_scene_stats(), then compact selectively.

Example: Scene Switching

from tuix.core import scenes, registry

# Create scenes
scenes.init_scene(b"menu")
scenes.init_scene(b"form")

# ... create widgets and remember their UIDs ...
choice_uid = 101
input_uid = 102

# Start with menu scene
registry.registry.current_scene_name = b"menu"
scenes.set_focus(b"menu", choice_uid)

# Later switch focus to input widget
scenes.set_focus(b"menu", input_uid)

# Switch scene
registry.registry.current_scene_name = b"form"

# Restore prior focus in menu when returning
registry.registry.current_scene_name = b"menu"
scenes.set_previous_focus(b"menu")

# Clean up
scenes.free_scene(b"menu")
scenes.free_scene(b"form")