Rendering Pipeline

TUIX renders through native buffers. Each object has a buffer, builders fill pixel data with interned UTF-8 symbols, the compositor resolves visibility, paint-masking, and layering, and the streaming renderer emits minimal terminal ANSI diffs.

Pipeline Stages

1. Read and route input snapshots.
2. Resolve terminal size, object modifiers, parent layout, viewport offsets, and explicit layout overrides.
3. Call builder resize/layout/event/content callbacks as needed.
4. Composite root and child buffers using z-index, parent traversal, viewport clipping, paint-mask partial compose, and modal rules.
5. Generate the hitmap used for mouse picking.
6. Render terminal-visible diffs with ANSI color and cursor optimization.

Geometry Resolution

Basic geometry starts from width_mod, height_mod, margin_top_mod, and margin_left_mod. Layout parents can then override child rectangles by writing layout rects or grid placement data. Scroll containers and viewport widgets contribute offsets and clipping in content space.

Pixel Ownership & Return Policy

v0.6 manages pixel ownership through TuixPixelReturnPolicy (`TUIX_PIXEL_RETURN_PERSISTENT` or `TUIX_PIXEL_RETURN_TEMPORARY`) and `TuixBuffer.pixels_owned`. Builders declare their policy in their `TuixBuilder` descriptor, allowing the core to either reference persistent builder buffers or copy temporary pixels into owned storage.

Dirty Marking & Redraw Generations

TUIX optimizes frame rendering through fine-grained dirty tracking. Mutating a widget marks its buffer redraw generation via `tuix_buffer_mark_redraw_by_uid()`. Modifying dimensions or parent layout marks child hierarchies via `tuix_buffer_mark_children_geometry_dirty_by_uid()`. The compositor checks these generation flags to bypass clean subtrees entirely during traversal.

Unicode & Terminal Output

TuixPixel uses interned immutable UTF-8 symbols with length and cell-width metadata. The renderer sanitizes terminal control characters (tabs, carriage returns, raw escapes) before emitting diffs. Wide characters (such as CJK ideographs) take 2 terminal columns and are handled without corrupting row diff calculations or cursor positions. Terminal probing gates wide glyph features according to terminal capabilities.

Viewport-Aware Compositing

Viewport widgets expose offset, insets, and content size callbacks. The compositor uses those values to clip child buffers and make hitmap picking match the visible content, including scrolled children.

Hitmap Picking

A frame-local hitmap maps terminal cells back to topmost visible buffer UIDs. Input routing uses it before builder dispatch so mouse clicks follow actual painter order and viewport clipping.

Diff Stability

The text and halfblock renderers compare terminal-visible ANSI color output rather than unstable intermediate color values. This reduces unnecessary redraws when equivalent colors pass through different internal paths.