Buffers API

The tuix.core.buffer package is the safe public surface for buffer lifecycle, hierarchy, z-index, layout overrides, grid placement, dirty marking, screen metrics, and snapshots.

Method	How to use it	Why it exists
buffer.tuix_buffer_free(scene_name: bytes, uid: int) -> None	Deallocates buffer storage for the given object UID.	Reclaims pixel memory.
buffer.tuix_buffer_set_parent(scene_name: bytes, uid: int, parent_uid: int) -> int	Attaches buffer UID into parent_uid child hierarchy.	Builds nested container/layout trees.
buffer.tuix_buffer_get_parent(scene_name: bytes, uid: int) -> int	Returns parent buffer UID, or 0 if root.	Tree traversal and hierarchy inspection.
buffer.tuix_buffer_get_z_index(scene_name: bytes, uid: int) -> int	Returns z-index layering order.	Determines paint stacking order during compositing.
buffer.tuix_buffer_set_z_index(scene_name: bytes, uid: int, z_index: int) -> int	Sets z-index integer layer.	Controls overlay and depth priority.
buffer.tuix_buffer_set_layout_slot_by_uid(uid: int, 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	Configures flex/stack layout constraints for a child buffer in a container.	Controls flexible resizing, alignment, and track placement.
buffer.tuix_buffer_get_layout_slot_by_uid(uid: int) -> dict	Reads configured layout slot parameters dictionary.	Inspects layout constraints.
buffer.tuix_buffer_set_layout_rect_by_uid(uid: int, offset_left: int, offset_top: int, width: int, height: int) -> int	Sets absolute layout rectangle override in terminal cells.	Bypasses proportional float calculations with exact cell geometry.
buffer.tuix_buffer_clear_layout_rect_by_uid(uid: int) -> int	Clears explicit layout rect override, returning buffer to proportional modifiers.	Restores default layout behavior.
buffer.tuix_buffer_set_grid_placement_by_uid(uid: int, row: int, col: int, row_span: int = 1, col_span: int = 1) -> int	Positions child buffer within a Grid parent.	Sets grid cell indices and row/col spans.
buffer.tuix_buffer_get_screen_rect_by_uid(uid: int) -> tuple[int, int, int, int]	Returns resolved screen rect tuple `(x, y, w, h)` in terminal cells.	Retrieves exact rendered screen coordinates.
buffer.tuix_buffer_get_screen_metrics_by_uid(uid: int) -> dict	Returns comprehensive screen metrics dict (screen_x, screen_y, width, height, visible, z_index, parent_uid).	Diagnostics and bounding box inspection.
buffer.tuix_buffer_mark_redraw_by_uid(uid: int) -> None	Increments buffer redraw generation, marking it dirty for next render pass.	Notifies compositor of content changes.
buffer.tuix_buffer_mark_children_geometry_dirty_by_uid(uid: int) -> None	Marks all child buffers dirty for geometry recalculation.	Triggers recursive layout recalculation on container resize.
buffer.tuix_buffer_get_snapshot_by_uid(uid: int) -> dict	Returns thread-safe snapshot dictionary of buffer state and pixel metadata.	Read-only diagnostics and testing.

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(content_builder.ROW, b'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, b'Main', content_builder.TEXT, 1.0, 1.0)

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