Ui & Plot

CPU reference/diagnostic composite -> upload RGBA8 oa::Texture. pending work in the engine's matching private recorder completes before reading base. Realtime consumers must use DetectionOverlay or another resident path.

Compute-compose path used by the ordinary image/video widgets.

Non-blocking update. A three-slot completion-tracked ring prevents the CPU from overwriting records still consumed by a previous GPU frame.

upload caller-provided planes. inPlanes and inDtypes must have the same length (1–4). Each span is W*H * sizeof(dtype) bytes. Synchronous.

Decode any stb_image-supported file to planar U8. 1-channel files → gray (channelCount=1). 3-channel files → RGB (channelCount=3). 4-channel files → RGBA (channelCount=4). HDR (.hdr) → planar F32. synchronous (transfer completes on return).

Records the exact UI consumer completion. Abandoning the value before completion transfers all owned plane buffers to engine retirement.

Returns true if inEvent was consumed by a matching action.

YAML schema: {version: 1, bindings: [{action, key, modifiers, context, allow_repeat}]}. Loading is transactional for syntax and schema errors. Without yaml-cpp these calls report Unimplemented, never success.

register the reusable Realm tool bindings. This installs named actions with no callbacks; the application owns every operation they trigger: F12 — screenshot ctrl+R — start/stop recording Space — toggle camera ctrl+Z — undo (node graph) ctrl+Y — redo ctrl+S — save F — fit-to-view (node canvas)

Configuration and direct mutations are result-bearing. Rejected input never changes the current navigation state.

Animate pan/zoom to fit all nodes. call every frame until isAnimating().

── input: update pan/zoom from raw deltas ────────────────────────────────

── Coordinate transforms ─────────────────────────────────────────────────

zoom centered on inFocusScreen (screen pixel).

Selects the nearest generated physical-pixel strike. Returns nullptr for unmapped codepoints or an invalid font/size.

Zero identifies direct grayscale coverage to the shared glyph shader; positive values remain reserved for a future SDF lowering.

measure text extent without appending.

Shape inText at inOrigin. Appends to inOutGlyphs (does not clear).

valid after widgets are submitted and until the next beginFrame. This is a flat, caller-borrowed platform-adapter snapshot, not an OA-owned desktop or document tree. bounds are ancestor-clipped physical pixels.

The viewport is required only by top-layer popup/tooltip placement. Viewer supplies its live compose extent. content scale converts the init style's logical geometry into physical pixels; event coordinates and explicit PixelRect values remain physical. Non-finite/non-positive scale is a frame error.

── layout containers ─────────────────────────────────────────────────────

beginPopup/endPopup render through the same deferred UI compositor, but their commands are submitted after every base-layer command. Popup calls must use the same parent scope as openPopup.

Explicit rows hug measured item widths and advance with layout.gap. Column items otherwise stretch across the panel's padded inner width.

Scroll panels retain only interaction/offset state under their stable ID. content coordinates are shifted and every nested draw/hit-test is clipped to the viewport. inContentHeight includes any layout padding. The caller owns content data; endScrollPanel must close the matching begin call.

Borrows the Viewer-owned atlas and allocates completion-tracked dynamic glyph slots. Bind once before the first frame; the atlas must outlive Ui.

labels identify controls within the active panel/row scope and must be unique there. mouse activation fires on release-inside; Tab/shift+Tab traverse focus and Return/Space activate the focused control. Returns true on click or keyboard activation.

Returns true when state changes.

Explicit circular OSD control with a GPU-drawn previous/next chevron. inLabel is both the stable widget identity and accessibility label.

Explicit renderer completion and release boundary. Waits every exact frame completion accepted by markFrameSubmitted before releasing pipelines, descriptor slots, and transient upload storage.

Passive color preview participating in panel/row layout.

Selection is caller-owned. Empty lists, invalid selection indices and invalid popup metrics are reported through recordRender.

draw a source-anchored glyph batch from one persistent coverage atlas.

One reusable viewport/chart/canvas grid. The default decimal hierarchy is 10-unit minor, 100-unit major, 1000-unit super-major, plus black axes and a subtle theme-derived vertical background gradient.

Host values → heatmap through the same bounded frame-safe upload ring as PlotLine. Intended for compact metric tables and recorded oa::plot figures.

Matrix convenience overload. rows/cols and value type are inferred when omitted, and matrix byte offsets are honored for views.

GPU buffer → heatmap (zero-copy — reads directly from inBuffer on GPU).

texture values are engine-checked before recording. Buffer-backed shared leases are retained through the exact markFrameSubmitted completion.

Planar path: blitPlanar.slang handles per-channel dtype conversion + sRGB. inPlanes must remain at a stable address through markFrameSubmitted; that call attaches the exact consumer event used by its non-blocking RAII path.

draw one plane as grayscale without constructing a non-owning planes value.

source stage/access describe the producer's last write made visible to this sampled read. Defaults preserve compute storage-image producers; graphics render targets must pass their color-attachment scopes.

Called once after init, before the first frame. inComposeImageView: vkImageView (as void*) of the compose storage image (set=1, slot 0).

── input state ───────────────────────────────────────────────────────────

Single-line UTF-8 editor. Returns true only when inOutText changes. The caller owns the value; the field retains bounded local edit history and IME composition state. It supports single/double/triple-click caret/word/all selection, shift and word navigation, scalar-safe deletion, clipboard, ctrl/Cmd+Z redo variants, Home/End, horizontal scrolling, visible native pre-edit and committed UTF-8 input. An external value replacement rebases local undo history; document-level undo remains application policy.

label does not soft-wrap; text wraps to the current panel's inner width. Both honor explicit newlines, require an active panel and a bound text atlas, and report misuse through recordRender instead of dropping text.

draw an anti-aliased screen-space line in one GPU dispatch.

Marks transient resources sampled by this frame. Plot buffers are recycled only after the exact engine-owned graphics completion is reached.

Menu items require an active popup and close it after activation.

draw one adaptive world-space canvas grid in one compute dispatch. Canvas screen coordinates are local to inRect; colors follow the current style.

at most one interactive popup owns pointer/keyboard input. The no-anchor overload anchors to the most recently submitted interactive item. The explicit overload supports context menus and application-defined anchors.

CPU float array → line chart.

ring-buffer variant: reads inCount floats from inData[inOffset % inCount].

CPU explicit-X/Y metric arrays -> one GPU polyline dispatch. The shader handles arbitrary segment direction without one dispatch per segment.

Finite fractions are clamped to [0, 1]. An empty overlay renders a rounded integer percentage; an explicit overlay is centered without soft wrapping.

Draws a passive compact label/value row. Empty values leave the returned Value rectangle available for a caller-owned editor control.

── style stack (O(1), max depth 32) ─────────────────────────────────────

Record all widget dispatch commands into inCmd.

draw filled or outlined axis-aligned rectangles directly into the GPU compose image. Rectangles must already be clipped to its extent.

draw normalized rectangle records from a bindless GPU buffer in one dispatch. inDstRect maps source-image coordinates into the compose image.

route a platform event. Returns true when an active/focused widget consumes it.

Draws a one-pixel horizontal rule in columns or a vertical rule in rows.

Sliders clamp the referenced value into [min, max] and return true only when it changes. Focused sliders accept arrow-key adjustment (1% of the range, shift=10x, ctrl=0.1x); pointer drags remain captured outside bounds.

Divides an explicit rectangle without beginning either child panel. The caller owns and may persist inOutRatio; it is the first region's fraction of the extent remaining after handleSize. Pointer drags retain capture outside the handle. Focused row splits accept Left/Right, and focused column splits accept Up/Down; shift/ctrl use the shared coarse/fine scale.

Draws one caller-owned tab sequence. Selection and overflow position live in inOutState; close and reorder are returned as requests so OA never owns documents or mutates their order. Left/Right/Home/End navigate the focused sequence and ctrl/Cmd+W requests closure of a closable focused tab.

Returns and clears a focused editor's pending copy/cut payload so the platform layer can publish it without introducing SDL into Ui.

Positioned GPU text primitive for plots, overlays, and other fixed-layout drawing. It does not participate in panel flow; inRect is an absolute compose-space clip/alignment rectangle. Stretch alignment is invalid.

Explicit transport timeline. inOutFraction is normalized to [0, 1]; returns true when pointer scrubbing changes it.

Attaches to the immediately preceding interactive item. tooltip geometry is passive and shares the top-layer command route with popups.

One row of a caller-flattened hierarchy. The caller owns open/selection state and applies open when openChanged is returned. Pointer activation on the disclosure toggles only; activation elsewhere selects. Focused tree rows use Up/Down to select among prior rendered rows, Left/Right to close or open, and Return/Space to activate. Explicit rectangles make the row directly compatible with virtualRows.

Called after a compose image rebuild (resize) to refresh the image descriptor.

Returns the visible half-open row range for the active scroll panel. rows start after layout.padding.top and use inRowHeight + inRowGap stride. Overscan is expressed in rows and is clamped to the item count.

Platform bridge for enabling native committed-text/IME input only while a field rendered in the current frame owns keyboard focus.

Full-surface audio scrubber backed by a GPU [bins, 2] min/max envelope.