Internal API Reference
This section documents the internal modules that bridge between the Python API and the compiled C core. These are not part of the public API — they are implementation details that may change between versions.
Internal Use OnlyThe modules documented here (tuix.core._lib, tuix.core._structs, tuix.core._tuix_cy) are internal. Do not depend on them in application code. Use the public API modules (engine, scenes, objects, buffers, input, builders, registry) instead.
v0.3 API CleanupPublic raw buffer pointer getter APIs were removed from the recommended public surface in favor of lock-safe snapshot APIs (buffer and object snapshots by UID).
tuix.core._lib — C Bridge
The _lib module loads the compiled Cython extension (_tuix_cy) or falls back to loading the shared library via ctypes.CDLL. It provides wrapper functions that call into native C code.
Module Variables
| Variable | Type | Description |
|---|
| _mod | module | None | The loaded Cython module (_tuix_cy), or None if unavailable |
| lib | CDLL | None | The loaded C shared library handle, or None |
Functions
| Function | Description |
|---|
| get_func(name, restype, argtypes) | Look up a native function by name in the Cython module or CDLL. Returns a callable. |
| tuix_render_streaming(buf) | Render a TuixFinalBuffer to the terminal using the streaming renderer. |
| tuix_create_native_buffer(py_buf) | Create a native buffer from a Python buffer object. Returns an integer handle. |
| tuix_free_native_buffer(handle) | Free a native buffer by handle. |
| tuix_apply_patch_and_render(handle, patch) | Apply a binary patch to a native buffer and render the result. Returns ANSI bytes. |
| make_patch_bytes(updates) | Convert a list of (index, sym, fg, bg) tuples to 20-byte binary patch records. |
Each patch record is 20 bytes:
| Offset | Size | Field |
|---|
| 0 | 4 bytes | Pixel index (little-endian uint32) |
| 4 | 8 bytes | UTF-8 symbol (null-padded) |
| 12 | 3 bytes | Foreground RGB |
| 15 | 3 bytes | Background RGB |
| 18 | 1 byte | Flags (bold, italic, underline, dim) |
| 19 | 1 byte | Reserved |
tuix.core._structs — C Structure Bindings
The _structs module defines Python ctypes.Structure classes that mirror the C structures used by the engine.
TuixRGBTuple
| Field | Type | Description |
|---|
| r | uint8 | Red channel (0–255) |
| g | uint8 | Green channel (0–255) |
| b | uint8 | Blue channel (0–255) |
TuixPixelStyles
| Field | Type | Description |
|---|
| fg | TuixRGBTuple | Foreground color |
| bg | TuixRGBTuple | Background color |
| custom_bg | uint8 | Has custom background color flag |
| custom_fg | uint8 | Has custom foreground color flag |
| bold | uint8 | Bold text attribute |
| underlined | uint8 | Underline text attribute |
| italic | uint8 | Italic text attribute |
| dim | uint8 | Dim text attribute |
TuixPixel
| Field | Type | Description |
|---|
| sym | char[8] | UTF-8 character (up to 8 bytes) |
| styles | TuixPixelStyles | Pixel style attributes |
| q_fg | TuixRGBTuple | Quantized foreground (cache) |
| q_bg | TuixRGBTuple | Quantized background (cache) |
| q_cached | uint8 | Whether quantized cache is valid |
TuixObject
| Field | Type | Description |
|---|
| uid | int | Unique object identifier (auto-assigned) |
| builder | void* | Pointer to the TuixBuilder that created this widget |
| state | void* | Pointer to per-widget opaque state |
| width_mod | float | Width as fraction of terminal width |
| height_mod | float | Height as fraction of terminal height |
| margin_top_mod | float | Top margin as fraction of terminal height |
| margin_left_mod | float | Left margin as fraction of terminal width |
TuixBuffer
| Field | Type | Description |
|---|
| obj | TuixObject* | Pointer to the parent object |
| pixels | TuixPixel* | Pointer to the pixel buffer array |
| width | int | Current resolved width in columns |
| height | int | Current resolved height in rows |
| required_redraw | int | Dirty flag — 1 if buffer needs rebuild |
| margin_left | int | Resolved left margin in columns |
| margin_top | int | Resolved top margin in rows |
TuixFinalBuffer
| Field | Type | Description |
|---|
| pixels | TuixPixel* | Composited pixel array (terminal_width × terminal_height) |
| width | int | Width in columns |
| height | int | Height in rows |
| full_redraw | int | Force all pixels to be re-rendered |
| Field | Type | Description |
|---|
| term_x | int | Terminal width at snapshot time |
| term_y | int | Terminal height at snapshot time |
| mouse | void* | Pointer to TuixMouseKey event data |
| keyboard | void* | Pointer to TuixKeyboardKey event data |
TuixRegistry
| Field | Type | Description |
|---|
| scenes | void* | Pointer to TuixScenes container |
| subcycles | void* | Pointer to TuixSubcycles container |
| builders | void* | Pointer to TuixBuilders container |
| current_scene_name | char* | Pointer to the active scene name string |
| next_uid | int | Next UID to assign (auto-incrementing counter) |
| terminal_width | int | Current terminal width |
| terminal_height | int | Current terminal height |
| terminal_width_old | int | Previous frame's terminal width |
| terminal_height_old | int | Previous frame's terminal height |
tuix.core._tuix_cy — Cython Extension
The _tuix_cy module is a Cython extension that wraps all C function calls. It is compiled from _tuix_cy.pyx and linked against the C source files. The Python API modules call _tuix_cy functions when available, falling back to ctypes when the Cython module is not loaded.
The Cython layer is a thin wrapper — it converts Python types to C types, calls the native function, and converts the result back. It does not add additional logic beyond type marshalling.
C Engine Architecture
The compiled C core is organized into these subsystems:
| Subsystem | Files | Purpose |
|---|
| Main Loop | main.c, main.h | Per-frame pipeline orchestration |
| Init/Shutdown | init.c, init.h | Registry setup and teardown |
| Rendering | rendering.c, rendering.h | Delta renderer with color quantization |
| Compositor | compositor/ | Scene buffer compositing with clipping |
| Geometry | compositor/geometry_resolver.c | Proportional layout resolution |
| Buffer Manager | buffer_manager.c | Buffer allocation, lookup, and freeing |
| Object Manager | object_manager.c | Widget creation with builder dispatch |
| Scene Manager | buffers.c | Scene CRUD and buffer array management |
| Builders | content_builder/ | Widget type registration and routing |
| Widget Impls | content_builder/builders/ | Canvas, Choice, Input, Progressbar C code |
| Input | input/ | Platform-specific keyboard and mouse capture |
| Subcycles | subcycles/ | Internal control objects for per-frame handler execution |
| Batch Executor | batch_executor.c | Binary command buffer parser (internal optimization) |
Optional C Modules
The source distribution includes modules not compiled into the default build. Advanced users can include them by modifying setup.py:
| Module | File | Description |
|---|
| Halfblock Renderer | rendering_halfblocks.c | 2× vertical resolution using Unicode halfblock characters (▀). Pairs two pixel rows into one terminal row. |
| Cache Manager | cache_manager.c | Experimental caching module; v0.3 production strategy is data-first scene stats and cold-scene compaction. |