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.
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/ | Per-frame handler registration and 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 | Planned caching subsystem for v0.3. |