Internal & Advanced API Reference
TUIX Core exposes specialized subpackages designed for advanced users, custom UI frameworks, high-frequency render loops, and low-level C bridge integrations. This page documents the low-level subsystems across `command_buffer`, `compositor`, `event`, `renderer`, `sub_cycles`, `viewport`, and `_lib`.
Command Buffer Subsystem (tuix.core.command_buffer)
The command buffer subsystem enables batched opcode execution and transactional frame commits directly across the C-Python boundary.
| Function | Signature | Description |
|---|
| tuix_command_buffer_execute | command_buffer.tuix_command_buffer_execute(data: bytes = b'') -> int | Executes a serialized stream of binary opcodes in the native core. |
| tuix_batch_clear_pending | command_buffer.tuix_batch_clear_pending() -> None | Clears all pending batch operations without applying them. |
| tuix_batch_global_commit | command_buffer.tuix_batch_global_commit() -> int | Atomically commits all batched object mutations across all scenes. |
Compositor Subsystem (tuix.core.compositor)
| Function | Description |
|---|
| compositor.tuix_compositor_compose_scene(scene) -> int | Runs full buffer hierarchy traversal and blits visible pixel layers into final output buffer. |
| compositor.tuix_compositor_mark_hit_map_dirty() -> None | Invalidates spatial hit-test map, forcing regeneration on next pointer event. |
| compositor.tuix_compositor_get_last_traversal_cache_hit() -> int | Returns 1 if last frame reused cached scene traversal paths, 0 on cache miss. |
| compositor.tuix_compositor_resolve_geometry(buf_addr) -> int | Resolves proportional and nested layout slot geometry into absolute terminal coordinates. |
Renderer Subsystem (tuix.core.renderer)
| Function | Description |
|---|
| renderer.tuix_renderer_stream() -> None | Streams current dirty terminal delta bytes directly to standard output. |
| renderer.tuix_render_streaming(buf) -> None | Emits ANSI sequence stream from a raw native buffer handle. |
| renderer.tuix_renderer_create_native_buffer(py_buf) -> int | Allocates a contiguous native buffer structure from Python buffer data. |
| renderer.tuix_renderer_free_native_buffer(handle: int) -> None | Frees native buffer memory allocated by tuix_renderer_create_native_buffer. |
| renderer.tuix_renderer_apply_patch_and_render(handle: int, patch: bytes) -> bytes | Applies a compact binary patch to a native buffer and renders differential ANSI output. |
| renderer.tuix_renderer_mark_rows_dirty(start_row: int, count: int) -> None | Explicitly marks vertical row ranges as dirty for next render pass. |
| renderer.tuix_renderer_invalidate_all() -> None | Invalidates entire screen buffer, forcing a full redraw on next frame. |
| renderer.tuix_renderer_get_last_stats() -> dict | Returns rendering timing statistics (diff_ms, ansi_encode_ms, write_ms, bytes_emitted). |
| renderer.tuix_renderer_get_last_frame_bytes() -> int | Returns number of ANSI bytes transmitted in the last frame. |
Sub-Cycles & Event Bridges
| Module & Function | Description |
|---|
| sub_cycles.tuix_sub_cycle_init(scene_name, obj_ptr) -> int | Initializes a high-frequency sub-cycle loop for a specific widget. |
| sub_cycles.tuix_sub_cycle_free(scene_name, uid) -> None | Frees and unregisters sub-cycle resources for the specified widget UID. |
| event.tuix_event_clear_pending() -> None | Clears pending queued native events. |
| event.tuix_event_commit_python() -> int | Dispatches queued native events into registered Python event listeners. |
| viewport.tuix_object_is_viewport(obj_ptr) -> int | Returns 1 if widget acts as a viewport owner (has virtual content size and scrolling offset). |
| viewport.tuix_object_get_viewport_offset(obj_ptr) -> tuple[int, int] | Returns virtual (offset_x, offset_y) coordinates for viewport container. |
| viewport.tuix_object_get_viewport_content_size(obj_ptr) -> tuple[int, int] | Returns virtual (content_width, content_height) in terminal cells. |
Low-level Binary Patch Protocol
For ultra-low-latency remote streaming or custom renderer bridges, patches are packed into 20-byte fixed-size binary records:
- `index`: 4-byte uint32 (cell linear index in buffer)
- `sym`: 8-byte uint64 (interned UTF-8 symbol identifier)
- `fgr, fgg, fgb`: 1 byte each (RGB foreground color)
- `bgr, bgg, bgb`: 1 byte each (RGB background color)
- `flags`: 2 bytes (bold, dim, italic, underline, wide bitflags)