Buffers API

The buffers module is the safe public surface for buffer lifecycle, hierarchy, z-index, layout overrides, grid placement, and snapshots.

Method	How to use it	Why it exists
buffers.free_buffer(scene_name, uid) -> None	Free a specific object/buffer UID when you remove it from a scene.	Releases native buffer/object resources without clearing the whole scene.
buffers.set_buffer_parent(scene_name, uid, parent_uid) -> int	Attach an existing buffer under a parent buffer.	Builds hierarchy for nested layout, clipping, and traversal-order compositing.
buffers.get_buffer_parent(scene_name, uid) -> int	Read parent UID when debugging hierarchy or detaching children.	Lets app code inspect the current hierarchy relation safely.
buffers.get_buffer_z_index(scene_name, uid) -> int	Read root-buffer z-index for diagnostics or ordering UI.	Exposes painter ordering without reading raw buffer memory.
buffers.set_buffer_z_index(scene_name, uid, z_index) -> int	Set root-level stacking order for overlapping widgets.	Controls scene-wide painter order while preserving child traversal.
buffers.set_buffer_layout_slot_by_uid(uid, *, grow=0.0, shrink=1.0, basis=-1, min_w=0, min_h=0, max_w=-1, max_h=-1, align_self=-1, grid_row=0, grid_col=0, row_span=1, col_span=1) -> int	Configure how a child participates in Row, Column, or Grid layout.	Gives parent layout builders typed child constraints and placement data.
buffers.get_buffer_layout_slot_by_uid(uid) -> dict \| None	Inspect a child layout slot while debugging layout output.	Shows grow, shrink, min/max, align, and grid fields without raw access.
buffers.set_buffer_layout_rect_by_uid(uid, offset_left, offset_top, width, height) -> int	Write an explicit terminal-cell rectangle for a child buffer.	Allows layout builders or advanced apps to override final child geometry.
buffers.clear_buffer_layout_rect_by_uid(uid) -> int	Remove an explicit layout rectangle override.	Returns a child to normal proportional or parent-driven layout.
buffers.set_buffer_grid_placement_by_uid(uid, row, col, row_span=1, col_span=1) -> int	Place a child inside Grid rows and columns.	Provides a concise helper for the most common grid slot fields.
buffers.get_buffer_snapshot(scene_name, uid) -> dict \| None	Read buffer state for a known scene and UID.	Provides lock-safe inspection of geometry, ownership, hierarchy, and layout data.
buffers.get_buffer_snapshot_by_uid(uid) -> dict \| None	Read buffer state when UID is known but scene lookup should be automatic.	Simplifies diagnostics and wrappers that track UID globally.

Snapshot Keys

Buffer snapshots can include uid, pixels_owned, width, height, required_redraw, margin_left, margin_top, parent_uid, z_index, flat_index, children_count, children_capacity, layout_slot, and layout_rect.

Layout Example

row_uid = objects.create_object(builders.ROW, 'Main', 0.9, 0.2, 0.05, 0.05)
row = objects.get_object_by_uid(row_uid)
child_uid = objects.tuix_stack_add_object(row, 'Main', builders.TEXT, 1.0, 1.0)

buffers.set_buffer_layout_slot_by_uid(child_uid, grow=1.0, min_w=12)
snap = buffers.get_buffer_snapshot_by_uid(child_uid)