173 KiB
Kryon API
This reference covers 0.4.0 and Unreleased changes on master.
Kryon is an ordinary Ziran package. An application imports the modules it
uses; no widget names are recognized by the Ziran compiler or .zx loader.
The public package imports are declared in ziran.toml.
Reusable component sources are grouped under src/ui/<component>/; shared
tree, input, theme, and paint infrastructure stays in src/ui/. Applications
import only the packages they use. For example, use kryon/text,
kryon/button, kryon/button_group, or kryon/progress_ring; checklist tasks
and swipe actions are available from kryon/onboarding_checklist_task and
kryon/swipe_props.
With KRYON_HOSTED_UI, the same named widget packages expose their hosted
contracts. Retained-only components such as Page and Toast require a local
tree. Hosted kryon/menu keeps the menu's props, types and state; its menu
bar Draw comes only with a local tree. Pointer and keyboard sampling remain
separate imports.
Rendering hosts that retain pixels can call CommitFrameDamaged(session) to
commit the tree and compare paint while leaving changed commands queued. An
unchanged result needs no raster work; a partial result supplies its damage
rectangle. The host clears and clips that area before PaintFlushArea, or
clears its whole surface before PaintFlush. EndFrameDamaged keeps its
existing behavior of emitting a full repaint immediately.
frame_transition.FrameSurfaceCopy(surface) copies a borrowed retained frame
into an owned surface before its target is reused. Capture before committing the destination
frame, draw with FrameTransition, and call FrameSurfaceRelease when the
transition ends. An invalid source or failed allocation returns an empty surface.
TreeSubmittedCount(session) and TreeSubmittedNodeAt(session, index) expose
the current frame's submitted geometry while building. Native skins can paint
retained controls from it while input continues using the committed tree.
| Import | Surface |
|---|---|
app |
Window, Frame, and Run for a small executable application |
text, button, image, page, ... |
One named package per widget, with Props, Draw, and widget-specific results |
semantic |
Semantic kinds for document-oriented applications |
PageRoute |
Browser route path, hash, and history (GetRoutePath, PushRoute, GetRouteOrigin, ...) for Canvas profiles |
geometry, drawing_props, session, tree, surface, paint_queue, style, style_sheet, control_props, font_metrics, scroll, semantic, tree_input, widget_kind |
Building blocks for widget packages |
Vector path coverage
vector_path rasterizes the portable KVP1 filled-path format and round
polyline strokes into caller-owned 8-bit coverage. VectorPathFill accepts an
affine VectorTransform, so hosts can render either a complete image or an
integer-translated tile with identical pixels. VectorPolylineStroke uses the
same transform, target, and VectorAdd / VectorErase coverage arithmetic.
File helpers are bounds-checked; callers retain ownership of all bytes and
coverage storage.
Calls share bounded scratch storage and must be serialized. Targets may be up
to 8192 by 16384 pixels; invalid input or exhausted scratch returns false.
Toast actions
Toast.Draw(session, Toast.Props) -> Toast.ToastResult accepts an optional
action_label: string. A new nonempty message captures that label in
Toast.ToastState.action_label; keep passing result.state on later frames.
An empty label retains the existing passive toast.
The action is a standard Button, with its label exposed to accessibility and
normal pointer, Tab, Enter and Space activation. Toast.ToastResult.action_clicked
is true only on the submission that consumes the activation. The caller owns
the action and dismissal; set clear = true when it should disappear.
A replacement message replaces the action; expiry and clearing remove both.
Bottom navigation
Navigation.Draw(session, props, items) defaults to a full-width 80-unit tonal
bottom bar. Reserve Navigation.NavigationBarHeight(props) above the bottom of the view.
For an embedded preview or panel, use compact = true with bounds;
fit_items = true fits the shortcuts into that rectangle.
Each Navigation.NavigationBarItem accepts an optional icon_shape (the standard Shape
format) or image; the icon is 24 units inside a 64 by 32 selection pill, with
its label below. With neither icon, the label is centered inside the pill.
Item keys, route results, disabled hit testing and custom style rules retain
their existing contracts. Pointer hover/press and keyboard focus draw state
layers; keyboard focus adds a ring. compact retains the scrolling dock/rail
layout used by Breeze, including its footer and drag/close behavior.
Timed motion and keyframes
Import kryon/motion for a timed scalar transition or keyframe track.
The module takes time and state from the caller and depends only on scalar
math. Apply a sample to opacity, position, size, or several chart points.
Motion.TimingFor(.EaseOut)creates a CSS timing preset. The choices are.Linear,.Ease,.EaseIn,.EaseOut, and.EaseInOut.Motion.CubicBezier(x1, y1, x2, y2)accepts CSS control points, including overshoot. Invalid control points yield linear timing. UseMotion.Progressto ease a unit interval directly.Motion.BuildTrack(frames)validates a borrowed slice ofMotion.Keyframerecords. Start at offset0, end at1, and place any other offsets in increasing order. A keyframe's timing governs the segment leaving it. Keep the slice alive and unchanged.Motion.At(track, progress)samples by normalized progress.Motion.Sample(track, elapsed, duration, iterations, alternate, reduced_motion)samples by seconds and reports.valueand.active. Reduced motion settles at the same endpoint as ordinary playback.Motion.TweenTo(*state, target, now, duration, timing, reduced_motion)starts an implicit transition when the target changes. Give each value its own zero-initializedMotion.TweenState. The first call initializes at the supplied target. Changing targets mid-flight starts at the current value. Pass monotonic seconds and request motion frames while.activeis true.
The checked usage example samples a whole series with one easing calculation per frame and shows an interrupted hover transition. Keep the chart's scale and the input series stable while they interpolate. Pass the resulting values to your usual chart drawing code.
Retained style and layout motion
kryon/style_motion installs typed transition rules and keyframes over the
normal widget style cascade. For CSS authoring, use css/motion to install
a parsed or packed sheet. Buttons use animated background, text and border
colors, opacity, corner radius, border width and content offset. Text and
links animate their color and opacity. Images animate the surface properties
the image already paints. Give each moving widget a stable key.
kryon/layout_motion moves keyed children through a reflow or reorder. Open a
layout scope and call LayoutMotion.Children(session) before drawing its
children. Set .resize = true to animate width and height changes and
.enter = true to grow newly mounted children from zero size at their placed
origin. Each option applies to direct keyed children of that scope.
Set .seconds, .timing and .reduced_motion to control the transition.
The layout reserves each child's target space while its visible size changes.
Paint and hit testing use the sampled bounds, and interrupted transitions
continue from the current sample. Moving a parent also moves its relative
children. Reduced motion and zero duration settle immediately.
Layout :: #import "kryon/layout";
LayoutMotion :: #import "kryon/layout_motion";
Button :: #import "kryon/button";
#import "kryon/tree"
row := Layout.Row(session, .{.key = 1, .gap = 12})
if row.opened {
unused LayoutMotion.Children(session, .{.seconds = 0.24,
.resize = true, .enter = true})
unused Button.Draw(session, .{.key = 2, .label = "First"})
unused Button.Draw(session, .{.key = 3, .label = "Second"})
unused End(session)
}
For exit motion, keep the child’s data and a LayoutMotion.PresenceState in
application state. Call LayoutMotion.Presence each composed frame, including
while the child is absent. Its first sample is fully visible if present and
fully hidden if absent. Later changes animate from the current sample and
honor reduced motion. The result gives a fraction from 0 to 1. Submit the
child while draw is true. Use interactive to disable input as soon as
exit begins. Optional PresenceOptions control .seconds, .timing and
.reduced_motion.
LayoutMotion :: #import "kryon/layout_motion";
Button :: #import "kryon/button";
#import "kryon/session"
#import "kryon/tree"
#import "kryon/tree_input"
#import "kryon/widget_kind"
PrintAction :: (session: Session, presence: *LayoutMotion.PresenceState,
available: bool) -> bool {
sample := LayoutMotion.Presence(session, presence, available)
if !sample.interactive {
previous := TreePrevious(session, TreeCurrentParent(session), 7,
cast(s32)WidgetKind.WidgetKindButton)
TreeBlurAt(session, previous)
}
if !sample.draw { return false }
// Keep a positive explicit height throughout the transition.
return Button.Draw(session, .{.key = 7, .id = 7, .label = "Print",
.bounds = .{0.0, 0.0, 88.0, 1.0 + 35.0 * sample.fraction},
.fit_content = true, .disabled = !sample.interactive}) != 0
}
Hold one state per child and session. If your composition can cancel a frame, sample into a copy of the state and keep the copy when the frame commits.
A custom retained host can set monotonic seconds with
kryon/frame_motion.SetFrameMotionTime before BeginFrame and use
FrameMotionMoving after commit to keep the frame loop active during motion.
Desktop, Android and Canvas frame hosts supply their own clocks. The web DOM
backend uses CSS motion through the browser.
Widget motion
Menu.Props, TabBar.Props, Navigation.Props, and Collapsible.Props
accept motion: *TransitionMotionState, now: float64 in monotonic seconds,
and reduced_motion: bool. Import each widget from its named package.
Retain one zero-initialized motion state per widget, with a stable widget key.
Motion runs in native widgets and VM-rendered widgets. The portable
KRYON_HOSTED_UI TabBar bridge currently supports immediate rendering with
motion = null only. A nonnull pointer payload is rejected before dispatch;
hosted motion needs an explicit state-value and write-back protocol. Guest
addresses are never accepted as native host state pointers.
The state must outlive every call and must not be shared between widgets. A
null pointer keeps the widget immediate.
Each result adds animating: bool. Request another application frame while
any submitted widget returns true, supplying the real clock on that frame.
Once every result is false, motion needs no further frames. The first
submission initializes at the current target; subsequent target changes
retain position and velocity, including reversals. Time zero is valid. Equal
or backward timestamps do not advance the spring; a long pause advances at
most 0.1 seconds per submission. Retained session and tree identities reset
state when the widget moves to another parent, remounts, or changes kind.
Menus fade, grow from 96 percent, and translate six units into place, with 0.28-second opening and 0.16-second closing springs. Continue submitting the menu and its current groups during closing. Closing panels keep visual paint but immediately release their scrim, rows, focus, and activation ownership. The menu retains indices and a content signature, never borrowed item slices.
Tab indicators stretch toward the selected tab using separate edge springs: the leading edge uses 0.26 seconds with no bounce, and the trailing edge uses 0.42 seconds with 0.14 bounce. Navigation selection bounds use 0.42 seconds with 0.16 bounce in both full and compact layouts. Hit targets and returned selection geometry follow the actual controls independently of the paint.
Collapsible uses a 0.40-second spring for its reveal and quarter-turn chevron.
content is the animated reveal rectangle; the application draws and clips
its body inside that rectangle and owns body interaction while closing.
open, focus, keyboard navigation, and close results keep their logical
meaning throughout the transition.
Explicit reduced_motion, theme SetReducedMotion(true), or a nonpositive
theme motion multiplier snaps to the target and clears animating. A
positive theme multiplier scales spring durations. These controls affect
actual widget paint and reveal geometry.
The four widgets use the shared TransitionSpringAdvance(spring, target, delta, duration, bounce, immediate) -> TransitionSpring integrator.
TransitionMotionBegin, TransitionMotionValue, and
TransitionMotionActive expose its caller-owned, four-channel state for
compositions. TransitionMotionBegin takes the clock, reduced-motion flag,
session slot/epoch, parent identity, own identity, and widget kind; callers
using it directly must supply actual retained identities. Treat a widget's
state as opaque while that widget owns it.
Buttons
Installed system palettes give buttons the full (capsule) shape. A button
taller than 56 units is a tile, such as a launcher or keypad tile, and takes
20-unit card corners instead of becoming a stadium; pill and circle still
force a capsule. Neutral soft buttons are tonal: a light tint of the palette's
accent over the background. A labeled image in a tile fills the spare
height instead of staying at the styled icon size: up to 64 units above the
label, or up to 40 units beside it. A vector icon_shape still takes
precedence over an image and keeps the styled size.
A button draws only the icons its program imports. A vector icon_shape and
pixels handed over as image.texture always draw. A file picture in
image.asset_path draws once the program imports kryon/image, and a
built-in icon_type once it also imports kryon/icon. A button without an
icon carries no picture decoder, asset path or icon atlas. The same holds for
pictures a toolbar, title bar or modal header hands to its buttons.
Breadcrumbs
Breadcrumb.Draw(session: Session, props: Breadcrumb.Props, items: []Breadcrumb.BreadcrumbItem) -> Breadcrumb.BreadcrumbResult is exported by kryon/breadcrumb. Items borrow
label: string for the frame and carry a unique, stable, nonzero key: u64
and disabled: bool. No labels are interpreted as paths.
Props contain key, bounds, id, class_name, active_index (-1 for none),
disabled, focused, and focused_index. Enter/Space in trigger_input
activates the caller's focused item; focused_index = -1 addresses overflow,
where Down also opens the menu. Native retained button focus works normally.
The widget never changes the caller's selection or focus. Read
activated_index (-1 for none), activated_key (0 for none), and changed:
repeat activation still reports the item, with changed = false.
open and close request overflow transitions; internal open state persists.
overflow_label defaults to an ellipsis. menu_input: DropdownMenuInput
provides Up/Down/Home/End, commit and Escape. Result open, opened, closed
reports menu state. Pointer, native Escape/focus dismissal and scrolling use
standard Popup and Scroll behavior. Submit after earlier page controls.
Widths use resolved Button styles and font advances. The tail and active ancestor remain visible, compressed when necessary; all other hidden ancestors remain in original order in a viewport-constrained, virtualized overflow. Labels are clipped/fitted without slicing UTF-8. Borrowed lists of at least 2,048 items are supported without submitting offscreen rows. Zero, negative, or fully clipped bounds submit no controls. Keys, not indices or labels, preserve retained item identity and menu highlight across reorder.
Context menus
ContextMenu.Draw(session, props: ContextMenu.Props, items: []ContextMenu.ContextMenuItem) -> ContextMenu.ContextMenuResult is exported by kryon/context_menu. The caller
keeps open and the pointer position (x, y); the result reports
activated_id (0 for none) and closed. Submit it after the page's other
controls.
ContextMenu.ContextMenuItem fields, in order: id: s32 (positive; reported when
chosen), label: string, disabled: bool, separator: bool (a divider; the
other fields are ignored), inline: bool (a compact cell sharing a row with
its inline neighbours), parent: s32 (the id of the row whose submenu holds
this one; a row others name shows › and opens the submenu instead of
reporting), accelerator: string, checkable: bool, and checked: bool.
New fields are appended, so positional .{id, label, disabled, separator}
initializers keep their meaning.
accelerator is a shortcut label such as "Ctrl++", drawn right-aligned in
the row in the theme's muted text colour, or in the disabled colour on a
disabled row, before any ›. The panel widens so each row's label, a 32-unit
gap and its accelerator fit. The menu only shows the label; the caller
handles the shortcut.
A checkable row draws a 14-unit check box at the row's left inset: empty
when unchecked, with a check mark when checked. When any row of a panel
is checkable, every label in that panel starts after the box column so the
labels line up, as in GTK menus; panels without check rows keep the plain
inset. Choosing a check row reports its id like any command, and the caller
flips checked. Check rows keep the option role and expose checked as the
row's selected state. Menus have no icons.
Cards
Card.Draw(session, Card.Props) draws a filled, elevated or outlined Material surface.
Import it as Card :: #import "kryon/card";. Set variant to CardFilled
(the default), CardElevated or CardOutlined, and supply bounds and a stable
key. The returned content rectangle has 16 units of padding, reduced for
small bounds. Draw your content in that rectangle; Card does not open a scope.
Cards are decorative by default. clickable enables the standard Button's
pointer, keyboard, focus and disabled behavior; activated reports activation.
An optional label is drawn centered and announced by the clickable surface.
Selected and explicit state props retain their usual meaning. Installed Card
style rules apply by id, class and emphasis (soft, filled and outline for the
three variants). Elevated cards and floating menus/dialogs use two fixed,
1-unit contact strips, with no blur, offscreen bitmap or animation timer.
A ListBox with no explicit row height uses 40 units. Its icon size does not
set its row height. Explicit row_height and style offset_y still win.
Widget packages
EmptyState.Props.disabled and Banner.Props.disabled keep configured action and dismiss buttons visible with disabled styling and semantics. They reject pointer and keyboard activation, including input queued before disabling, and become usable again when enabled.
Carousel.Props.disabled disables swipe, wheel, keyboard navigation, arrows,
and the selected action together. It defaults to false; item-level disabled
continues to disable only that item's action. Disabled controls use their normal
disabled styling and become interactive again when reenabled.
Carousel.Props.logo_max_width optionally caps the cover logo's logical width;
logo_top optionally positions it below surrounding controls, relative to the
carousel bounds. Zero preserves the default title layout. CarouselArtwork
accepts the same optional values after its source rectangle for startup covers.
A widget that is not part of the core catalog lives in its own Git package and depends on Kryon. Plot and DataViews are examples. Import the building blocks by their package-qualified names, so a reader sees which package each name comes from:
#import "kryon/session"
#import "kryon/tree"
#import "kryon/surface"
#import "kryon/paint_queue"
Tests that need a host bind Kryon's internal capabilities the same way, for
example --bind kryon/raster_text:RasterText=my_test_host:RasterText with
ziran bundle --project.
Source coloring is the separate Syntax
package. Its SyntaxColorSpan has the same fields as TextArea.ColorSpan.
Hosts with stable font measurements call font_metrics.GlyphMetricsChanged()
after initializing their font services and whenever fonts or their advances
change. This lets TextArea retain wrapped rows in a bounded cache of owned
content. Publish revisions on the UI's owning thread. The pixmap host enables
reuse automatically for its bundled, fixed
font outlines. Hosts that have not published a metrics revision keep measuring
rows on each call; they do not acquire an invalidation requirement implicitly.
Font size, typeface, wrap width and content changes always select a new layout.
TextArea.Props.manual_scroll keeps a reader's scroll position independent of
caret and selection changes. Wheel, scrollbar and touch scrolling remain
available. Editors keep the normal caret reveal unless they enable this flag.
Scroll.Props.manual_scroll similarly suppresses automatic focused-field
reveal for a reader that owns its viewport.
TextField.Props.capture_tab defaults to false. An editable field can opt in
so an unmodified Tab queued before BeginFrame remains available through
KeyboardTake(session) for application completion. Only the actual retained
focus owner can capture it, using its last committed intent; disabled,
read-only, fully clipped and unfocused fields do not capture. Shift+Tab retains normal focus traversal.
Control-, Alt- and Super-modified Tab stay queued for application input. Intent is scoped to the retained
node and session epoch, including suspended embedded-app input.
input.focus also transfers actual focus to a newly submitted TextField in
its first frame, so the next queued key reaches it without an idle render.
Intrinsic layouts and bound text fields
A retained form can use Layout.Draw for a column and Layout.Row for a row.
Submit ordinary widgets inside the scope and close it with End(session).
Omit the bounds of an intrinsic button in a row or a bound text field in a
column. The button sizes to its content, and the field fills the column's inner
width and uses the themed control height. Layout.Gap(.ThemeMetricSpace2)
resolves a theme spacing token in logical units. Layout.LayoutContentBounds
measures unset outer dimensions from child rectangles, direction, main-axis gap
and padding. Its optional padding_y sets the vertical inset independently.
Pass a calculated dimension in Layout.Props.bounds to fit it to
content, or use an explicit width to compose inside a viewport.
Retained layout rules match StyleKindRow() or StyleKindColumn() and the
optional Layout.Props.id and class_name. Styles support StyleGap as a
shorthand and StyleRowGap, StyleColumnGap, StylePaddingX and
StylePaddingY for independent spacing, rounded to the nearest logical pixel.
A single-line row uses column_gap between children and a column uses row_gap.
Layout.Props accepts uniform gap and padding over the style and independent
row_gap, column_gap, padding_x and padding_y over those shorthands.
Set the corresponding _override flag to supply explicit zero. Negative
spacing is clamped to zero.
For a native bound field, initialize state.bytes once from application-owned
storage and set state.length to the number of UTF-8 bytes in the initial
value. TextField.Bind(session, *state, props) draws and applies edits to that
storage. Give each field a stable key. The same field keeps focus, selection,
scroll and IME preedit across frames and resize. It consumes editing input from
the focused session and uses the platform clipboard. Use the returned changed,
committed, escaped and paste_without_text flags for application actions.
For deterministic input, pass false as the fourth argument to Bind
and provide the sample in props.input. Custom hosts can pass an IME sample
in props.input.composition_event. Native platform text requests use the
same bound widget.
// name.bytes points to persistent application storage.
form := Layout.Draw(session, Layout.Props.{.key = 11, .bounds = bounds,
.gap = Layout.Gap(.ThemeMetricSpace2)})
if form.opened {
edited := TextField.Bind(session, *name, TextField.Props.{.key = 42, .label = "Name"})
if edited.committed {
SaveName(TextView(name.bytes[:name.length]))
}
unused End(session)
}
TextField.State keeps a field's value and interaction state in caller-owned
storage. Import it and its helpers as TextField :: #import "kryon/text_field";.
Give bytes a writable slice and set length, cursor, anchor, scroll_x
and focused as needed. Every byte of the slice is usable capacity; length
does not include a terminator and the helpers do not write one.
// Keep the bytes and state alive between frames.
name_bytes: [96]u8;
name: TextField.State;
// Initialize once: name.bytes = name_bytes[:]
// In Frame, use the existing widget and keep the application's commit policy.
edited := TextField.Draw(session, TextField.StateProps(name, TextField.Props.{
.key = cast(u64)42, .bounds = bounds, .label = "Name", .input = input}))
if TextField.StateApplyResult(*name, edited) && edited.committed {
// Save or navigate according to the application's workflow.
}
TextField.StateProps(state: TextField.State, props: TextField.Props) -> TextField.Props
fills value, selection, scroll and focus, and limits max_bytes to storage
capacity while preserving stricter application limits and all other props.
The value borrows the buffer; consume borrowed result text before mutating it.
An invalid length or UTF-8 value disables the field; zero capacity is read-only.
TextField.StateApplyEdit(state: *TextField.State, edit: TextField.Edit) -> bool
accepts only ordered ranges within the existing value, with both ends at
UTF-8 scalar boundaries, valid UTF-8 replacement text, and a result that fits
the slice. The current value must also be valid UTF-8. Replacement can borrow
any part of the destination: a temporary owned join is freed after the call.
Rejected edits, including allocation failures, preserve every byte and state
field. An accepted changed edit collapses selection after the replacement.
An unchanged edit is accepted without changing state. Application-specific
text limits beyond storage capacity are enforced by the widget's props.
TextField.StateApplyResult(state: *TextField.State, result: TextField.Result) -> bool
applies the edit and copies cursor, anchor, scroll and focus together. A rejected
edit preserves all of them. Successful application clamps cursor and anchor
to scalar boundaries in the resulting text and scroll to zero or greater;
the widget still owns grapheme navigation. true means accepted, including
navigation with no edit; it does not mean committed. Enter, Escape, clipboard
and IME composition remain available on the original result for the application
to handle, with their existing borrowed-text lifetime requirements.
Native TextArea and TextField snapshots retain the supplied cursor and anchor and return only the changed grapheme-aligned span as their edit. An unchanged snapshot updates selection without a text edit. This keeps a correction near the beginning of a long note from revealing the document end on its edit frame. Applications must apply the edit and preserve the result's cursor and anchor.
A TextArea can preview a markup language over its value without changing
it. hidden bytes take no width or caret stop, strong bytes are bold and
italic bytes slanted when the host registers a slant raster (otherwise upright), and colors tint spans.
lines draws a logical line at its own size (TextArea.Line.scale), such as
a heading: its rows wrap, take caret stops and take height at that size.
blocks adds boxes under a line, one under another in order, the first in
place of its last row with cover, each drawing image fitted inside it or
a soft frame with label while the image is missing; a press inside a box
is the end of its line. Every list is sorted, with starts at line starts and
at most one size per line, or ignored as a whole; without them the layout is
the plain area's. During an IME composition, lines and
boxes after it move with the preedit.
MarkdownEditor :: #import "kryon/markdown_editor"; shares the inline
Markdown editor extracted from Inner Breeze Diary. Call
MarkdownEditor.Draw(session, MarkdownEditor.Props.{.area = area, ...})
with ordinary TextArea.Props and retain its result's edit, cursor, anchor,
scroll and focus. muted_color and link_color color list/quote markers and
links. Headings, emphasis and links preview while the caret's active lines
show their original syntax. The value and edit offsets always address the
original Markdown; there is no HTML conversion or second document.
The optional kryon/markdown_preview module exposes Scan(preview, text, cursor, anchor, editing, images) for hosts that need the formatting ranges.
An app resolves its own media into ImageSpan values and corresponding
area.blocks; the editor owns only their layout and syntax visibility.
It never reads a file or fetches a URL. kryon/text_props exposes the
text/range data types without importing a text renderer.
Import kryon/pointer_input for SamplePointer(), which also works inside a
hosted widget frame. The host returns the pointer sample for the session passed to WidgetHostBegin;
an inactive frame cannot read input, and another session's sample is not exposed.
The pointer value schema lives in input_protocol, independently of the native
retained input implementation.
frame_snapshot.CaptureFrameInput(session: Session) -> FrameInputSnapshot
returns the host's immutable observations for the current frame. available
is false before a host publishes, after it ends the frame, or for an invalid
or different session. The result owns its keys: [512]u8 array and nested
pointer values: retained copies survive subsequent polls and hosted calls.
Test snapshot.keys[KeyLeft] & cast(u8)FrameKeyHeld for sustained movement.
Each entry combines FrameKeyHeld (1), FrameKeyPressed (2),
FrameKeyReleased (4), and FrameKeyRepeated (8). A repeat is distinct from
a fresh press; holding a key does not invent repeats. Indices use the existing
uppercase ASCII and named Key codes; index zero is unused.
The snapshot also carries pointer, secondary, focused, modifiers,
wheel, and elapsed_ms, delta_ms, sequence. Desktop and Canvas
sample a monotonic clock once per successful host poll: first delta is zero,
later deltas are nonnegative, and repeated captures have identical timing.
Sequence starts at one for each opened host. Pointer coordinates use the
host's logical zoom.
On focus loss, held keys become released for one poll, held pointer buttons
are released, and pressed/repeated keys, modifiers and wheel are cleared.
Further unfocused polls have no held keys or repeated releases. The first
focused poll after focus loss may report held keys but suppresses fresh
press and repeat flags, preventing a focus change from activating a shortcut.
Hosts publish on the session's owning thread with FrameInputBegin(session, snapshot) -> bool and call
FrameInputEnd(session) after the callback, including failure paths. Publishing
copies the value and rejects replacement while that session's frame is open.
Kryon's standard Desktop and Canvas app loops do this automatically.
Desktop freezes raw SDL key events for its own window; Canvas freezes existing
DOM held state and edge queues before widget reads. Both clear publication on
callback cancellation, terminal polls and host teardown. Custom Desktop or
Canvas loops call DesktopFrameInputBegin(session) or
CanvasFrameInputBegin(session) after the matching successful poll, and
FrameInputEnd(session) when their callback ends (including failure paths).
The host also ends publication before presentation can yield. Other providers must supply
equivalent gathered state; this API does not infer held keys from consumed
keyboard events. A hosted
bundle requests only frame_snapshot.CaptureFrameInputHost; WidgetHostCall
validates the session against the active WidgetHostBegin before returning
that session's published snapshot. No input is queried outside that frame.
Capturing never consumes KeyboardTake, TypedTextTake, IME, clipboard, or Escape routing. Applications retain movement,
simulation, repeat cadence, and navigation policy. The existing FrameInput
replay record and its apply/field helpers retain their contract.
Scroll reveals a newly focused text input and adjusts when the viewport
resizes, such as when a phone keyboard opens. It retains that focus transition
on the scroll node. Keeping an input focused never recenters it after manual
scrolling; applications should not repeat their own focused-field reveal loop.
BeginFrame routes Escape to the topmost retained modal or popup, even
while a field has focus. DismissibleOverlay and Popup report it through
closed; a non-dismissible modal consumes Escape without closing. Hosts
send KeyEscape with KeyboardSend, and application shortcuts check
TreeEscapeCaptured(session) before handling that same Escape. KeyF3 is the
canonical F3 key code (292) for application shortcuts.
Modal.Props.dismiss_on_outside defaults to false. Its full-viewport scrim
owns pointer presses that start outside the panel and consumes their releases,
including drags that cross the panel boundary, without reporting dismissed.
Set dismiss_on_outside = true to opt into outside-release dismissal. Escape
dismisses the modal by default; dismiss_disabled = true prevents both Escape
and outside dismissal. Overlay.Props.outside_dismiss_disabled blocks outside
releases independently of Escape.
Overlay.Popup and context menus keep their separate press-outside dismissal
and click-through behavior.
Swipe rows
SwipeRow.Draw(session, props, state) follows a horizontal drag, paints the revealed
strip and returns its content offset plus state for the next frame. Right
uses start, left uses end; an action needs icon_shape. threshold is a
share of row width (zero means 0.35). Optional end_threshold overrides it
for left swipes; zero uses the effective shared threshold. A release emits swiped_start or
swiped_end; clicked reports a separate tap or keyboard activation, while
right_clicked and pointer_x/pointer_y expose a secondary-button release.
The app chooses what a tap does. Vertical scrolling does not activate swipe actions.
Optional long_start and long_end actions add a second stage in either
direction. long_threshold is a width share (zero means 0.5) and must exceed
that direction’s effective short threshold; otherwise that stage is ignored. Its strip
color/icon appears at that distance. Release emits swiped_long_start or
swiped_long_end, exclusively with the short results, using the final distance
even after crossing and retreating. Each chosen action's removes controls
whether the row settles back. Without long actions, existing behavior remains.
Positive start_width or end_width replaces that side's row-width share with
a fixed bounds-unit travel span; zero retains row-width behavior. A two-stage
strip divides that span into equal first and second containers and clamps the
drag at the configured span.
For short-swipe completion and long-swipe editing, set equal start_width halves,
threshold = 0.5, end_threshold = 0.35 to retain row-width left deletion,
long_threshold = 1.0, put completion in start and edit in long_start, and
handle their separate results. A tap need not complete the row.
Style rules
InstallStyleRules copies typeface text into Kryon-owned storage and returns
false without replacing the active rules when the rule count is outside
0..320 or the combined typeface text exceeds 65,536 bytes.
InstallParsedStyleRules reports the same storage failure.
Use Image.Draw(Image.Props) for UI images. Its asset path, bounds, fit, and alt
text describe the image at the widget boundary. Backend texture calls are
renderer primitives, not alternate widget APIs.
Asset paths may name PNG, JPEG, WebP or AVIF files on image-loading hosts. WebP is
recognized by its content: lossy, lossless and transparent pictures load as
RGBA, and an animated WebP shows its first frame (Kryon images are still).
See WebP images and AVIF images for each host's decoder.
Image.Props.radius gives an image rounded corners in native and hosted UI;
a positive value overrides its style radius.
kryon/image brings file pictures, so a program that imports it links a host
that measures them. Code that only needs the image placement rules, such as
ImageFitBounds and ImagePreviewSource, imports kryon/image_behavior,
which needs no host or picture.
Import kryon/bitmap_image to create a runtime RGBA image for the same
Image.Draw(session, Image.Props.{.texture = image, .smooth = true, ...}):
BitmapImageCreate(session: Session, width: s32, height: s32, rgba: []u8) -> Texture2D,
BitmapImageUpdate(session: Session, image: Texture2D, rgba: []u8) -> bool, and
BitmapImageRelease(session: Session, image: Texture2D). Bytes are tightly packed,
row-major straight RGBA8 and copied/consumed synchronously; reuse the input buffer
after the call. Create failure returns a zero texture. Update returns true for
accepted unchanged data, and false preserves the old pixels. Only successful
changed data invalidates retained paint. Smooth sampling and alpha use the
ordinary Image renderer on Desktop/Cairo, pixmap and Canvas. Explicit Image.Props.tint, including white for original colors,
applies to straight RGBA pixels. GPU reset and native window close/reopen
preserve the session's CPU image; textures are recreated when next painted.
Completed native worker frames own deduplicated copies of the revisions they
draw, so an update or session close cannot change pending pixels. Each frame
retains at most 64 revisions and 32 MiB of straight pixels; pressure fails the
frame explicitly. The native texture cache has the same 64-image/32 MiB bound.
Managed handles belong to the complete Session (slot and epoch) and current
provider. Dimensions must be positive, at most 4096 each and 4,194,304 pixels;
byte count must equal width × height × 4. There are at most 64 images, with a
64 MiB total and 32 MiB per-session budget for straight and premultiplied CPU
copies. Provider copies have the same bounded dimensions/count. Bad, modified,
stale and cross-session handles are rejected; releasing them is harmless.
Closing a Session releases its images. Closing/replacing the Canvas provider
also releases its images. Call on the session/provider's frame thread, outside
an active raster emission. Native renderer texture handles keep their existing
contract. Standard hosted widget policy continues to reject all guest runtime
texture IDs and does not advertise bitmap lifecycle capabilities; an embedding
must provide a separate authenticated ownership policy to grant those effects.
In a zx bundle the player owns these pictures: kryon build defines
KRYON_ZX for zx profiles, and the same three calls become the host calls
BitmapImageCreateHost, BitmapImageUpdateHost and BitmapImageReleaseHost
(pixels cross once as a byte view), so the player's raster draws them. The
desktop zx player provides them for the session it runs; a player without
them refuses the bundle.
System text clipboard and PRIMARY
Import kryon/system_clipboard for the ordinary UTF-8 text clipboard. The
existing SystemClipboardText(buffer), SystemClipboardAvailable(),
SystemClipboardHasText(), and SystemClipboardSet(text) calls keep their
ordinary CLIPBOARD semantics.
On hosts with a distinct selection clipboard, use
SystemPrimaryText(buffer) -> string, SystemPrimaryAvailable() -> bool, and
SystemPrimarySet(text) -> bool. SystemPrimaryText returns a caller-owned,
whole-UTF-8 prefix borrowed from buffer; an empty result can mean either an
empty selection or an unsupported host, so use SystemPrimaryAvailable when
that distinction matters. Linux SDL desktop hosts connect these
calls to the platform PRIMARY selection. Android, Canvas, terminal, pixmap,
bundle and unsupported desktop hosts return unavailable rather than falling
back to CLIPBOARD.
Custom hosts implement the snapshot functions SystemPrimaryOpenHost() -> s32
and SystemPrimaryByteHost(index) -> s32, plus
SystemPrimaryWriteHost(text) -> bool. Open returns the byte count, including
zero for an available empty selection, or -1 when unavailable. The snapshot
remains valid until the next open call; write copies the text during the call.
Optional native MIME clipboard on Linux
Import kryon/MimeClipboardLinux in an X11/XWayland native app and link
-lxcb (for example in LDLIBS). Existing text and PNG modules retain their
interfaces. This module owns one dedicated connection and unmapped selection
window, without toolkit callbacks or changes to the toolkit's connection.
It does not implement a Wayland-only data source or clipboard persistence.
Call MimeClipboardOpen() -> bool on the application's GTK/X11 owning thread,
then keep every call serialized on that same thread until
MimeClipboardClose(). Calls from another thread fail; close there does nothing.
Close is idempotent and destroys only the transport's own connection/windows,
freeing its copied publications and outgoing transfer snapshots. No callbacks
or caller buffers remain registered after any call returns.
MimeClipboardPublish(payloads: []MimeClipboardPayload) -> MimeClipboardPublishResultcopies every{mime: string, bytes: []u8}before publishing the complete target set in one selection ownership change. Reuse/free input storage after return. Result fields arestatusandowner: u64. Duplicate/empty/NUL names, reserved selection protocol targets and invalid counts fail without replacing the prior publication. Empty byte payloads are supported.MimeClipboardRead(mime: string, buffer: []u8, timeout_ms: s32) -> MimeClipboardReadResultrequests exactly that target, including incoming INCR. It returnsstatus,bytes: []u8,size: s64andowner: u64. OnlyOkexposes bytes, borrowed from the supplied buffer. The buffer may contain partial data on failure; ignore it unless status isOk. Empty success differs fromAbsent.sizeis the bytes observed, the direct property's exact size, or an INCR lower bound/hint when rejected as too large. INCR hints are untrusted.MimeClipboardPump(max_events: s32) -> s32serves at most 256 events per call (zero for nonpositive budgets). Call regularly from the app frame loop while publishing. Reads also serve queued requests; self-reads copy directly without waiting for a toolkit loop. Pump retires abandoned/expired transfers.MimeClipboardOwner() -> u64returns zero for no owner/unavailable transport. Local ownership returns the local generation token. Foreign ownership returns an observational XID; it cannot identify content changes within that window.MimeClipboardRelease(owner: u64) -> boolclears only the still-current publication created by this transport, comparing server ownership atomically. Every successful local publish has a fresh window and generation token; stale tokens, including across close/reopen, cannot clear newer local data. Foreign tokens always fail, even if a read returned that token: a foreign application may republish different data from the same window.
MimeClipboardStatus is Ok, Absent, Error, TooLarge, or Timeout.
Absent means no owner or a refused target. Invalid arguments, malformed
conversion properties, connection errors and owner replacement during a read
return Error. Read timeouts are total monotonic deadlines (1–5000 ms),
including trickling INCR chunks; ordinary X-server request round trips assume
a responsive local X server. Only the UI thread may open; concurrent first
calls and reentrant calls are unsupported.
Limits: 32 targets; names 1–255 bytes; 16 MiB aggregate copied publication; 16 MiB per read even with a larger caller buffer; 16 outgoing INCR transfers with 16 MiB aggregate snapshot bytes and a five-second total serving lifetime. Transfers use 32 KiB chunks and survive local republish/owner loss using their own copied snapshots. No MIME conversion, URI validation or file operation policy occurs here. Clipboard data and remote ownership are observations, not an authorization or a trustworthy content generation identifier.
Run make mime-clipboard-linux-test for source and saved-IR native tests against
independent Xlib fixtures and installed xclip, under private HOME/XDG/D-Bus/Xvfb.
Optional native drag source on Linux
Import kryon/DragSourceLinux in an X11/XWayland native app and link -lxcb
to drag data out of the app with XDND version 5, for example files onto a web
browser's upload area, a file manager, the desktop or an editor. The module
owns its own connection, an unmapped source window and an optional icon
window; it never grabs the pointer or changes the toolkit's connection.
Call DragSourceBegin(payloads: []DragSourcePayload, actions: u32, icon: DragSourceIcon) -> bool
while the primary button is still held, typically once the pointer has moved
past the platform drag threshold from the press. Each payload is a
{mime: string, bytes: []u8} pair copied during the call (at most 32 targets
and 4 MiB in total). actions combines DRAG_ACTION_COPY, DRAG_ACTION_MOVE,
DRAG_ACTION_LINK and DRAG_ACTION_ASK. icon is straight RGBA up to
256×256 with a hot spot; pixels at least half opaque are shown in a shaped
override-redirect window that follows the pointer. A zero-sized icon shows none.
While DragSourceActive() is true, call DragSourceUpdate() -> DragSourceState
once per frame on the same thread and keep frames coming (on the Desktop host,
DesktopRequestFrame()). Update follows the pointer, finds the top-level window
under it (honouring XdndProxy), sends Enter/Position/Leave/Drop, answers
XdndStatus, and serves the XdndSelection conversions, including TARGETS.
The suggested action follows GTK: Control+Shift links, Control copies, Shift
moves, Alt asks, otherwise the first offered of copy, move and link. The state
reports status, the root pointer position, modifiers (1 Shift, 2 Control,
4 Alt), the current action, whether a foreign target accepted it, and
local when the pointer is over a window of this process (identified by
_NET_WM_PID). Over its own windows the module sends no XDND messages, so the
app performs internal drops itself.
status is Dragging until the button is released. A release over this
process gives Local; over an accepting target the drop is sent and the status
is Dropped until the target's XdndFinished (or a 15 second timeout) gives
Finished with performed and success; anywhere else gives Cancelled.
DragSourceCancel() abandons a drag, for example on Escape. After reading a
final status, call DragSourceEnd() to release the selection, icon and copied
data. The application performs no file operation for a foreign drop: the
target does, as with any XDND source.
Run make drag-source-linux-test for source and saved-IR tests that drop onto
an independent python-xlib XDND target on a private Xvfb.
Optional GTK3 theme rendering on Linux
Import kryon/GtkStyleLinux only in a Linux native application that links GTK3.
This module reads the current GTK settings, screen CSS providers, icon theme and
Pango fonts. It renders offscreen; the application supplies its selectors, layout,
input and accessibility. Call its functions on the GTK owning thread, and call
GtkStylePoll() from a non-GTK event loop to deliver up to 32 pending GLib events.
A GtkStyleNode contains widget_type (for example "GtkButton"), CSS element,
CSS ID name, classes: []string, GTK state: u32 and optional
providers: []GtkStyleProviderAttachment. Each attachment contains a live
provider: u64 handle and native priority: u32; it applies only to that node's
GTK context, including ancestor contexts. At equal priority, GTK gives context
providers precedence over screen providers, using its own selector rules. Pass an ancestor-to-leaf
slice of nodes. Optional sibling_count (1–64) and zero-based sibling_index
describe a homogeneous sibling group for native child selectors. Zero count
leaves position unspecified. Header measurement builds the same column group,
so first/middle/last CSS borders affect its real child allocations. State constants are GtkStyleNormal, GtkStyleActive,
GtkStylePrelight, GtkStyleSelected, GtkStyleDisabled, GtkStyleFocused and
GtkStyleChecked; combine flags for compound states.
GtkStyleQuery(nodes, scale)returnsGtkStyleMetrics:available,foregroundandbackgroundas RRGGBBAA,border,paddingand CSSmarginin logical pixels, a copied NUL-terminatedfont_family: [256]u8, logical-pixelfont_size: float64, Pangofont_weightandfont_style, and screendpi. GtkTreeView selectors also expose nativevertical_separatorandhorizontal_separatorstyle properties.GtkStyleRaster(nodes, width, height, scale)paints the CSS background and frame. Its bounds are the CSS border box; callers lay out CSS margins separately.GtkStyleIndicatorRaster(nodes, width, height, scale, indicator)asks GTK to draw the last node's check box (0), radio option (1) or submenu arrow (2, pointing right, or left in a right-to-left context) withgtk_render_check,gtk_render_optionorgtk_render_arrow.GtkStyleRasterRegion(nodes, width, height, scale, x, y, crop_width, crop_height)renders a crop of the original logical CSS box, preserving gradients and borders. Logical boxes can reach 8192 pixels per axis; the allocated crop retains the ordinary 4096-axis and 4,194,304-pixel bitmap limits.GtkIconRaster(name, size, scale, nodes, force_size = true, styled = false)resolves a named icon using the current GTK icon search path and theme inheritance. PNG, SVG and symbolic icons use GTK's loader; symbolic colors come from the supplied style context. Clearforce_sizeto retain the theme's natural artwork, as GtkImage does. Setstyledwith the image's full CSS ancestry to render through GTK's icon surface painter, including native transforms, shadows, direction and state.GtkIconSize(category)resolves GTK's menu/toolbar/button size categories.GtkUserDirectory(index)returns GLib's borrowed XDG user-directory path.GtkWidgetMeasure(nodes, text = "", sort_arrow = false, allocation_width = 0, allocation_height = 0, options = .{})returnsavailableand minimum/natural width and height for GtkButton, GtkEntry, GtkMenuBar, GtkMenuItem, GtkToolbar, GtkToolButton, GtkStatusbar or a horizontal GtkPaned. It constructs an offscreen hierarchy with the supplied classes, names and providers. Tree-view header selectors use a real GtkTreeViewColumn, including its label and native sort arrow. Menu bars include one item with the supplied label; icon toolbars include one item with the supplied icon name at GTK's large toolbar size. For these containers,item_x/y/width/heightreport GTK's representative child allocation. Zero allocation dimensions use the natural size. Headeritem_*fields describe its label, andarrow_*describe its visible sort image. For entries,textoptionally names the primary icon;item_x/yare native layout offsets,item_widthis the remaining text-area width,item_heightis the layout height, andarrow_*is the icon area. Status bars usetextas their message and return the label allocation. The offscreen root is never shown. Entry allocation realizes an offscreen backing surface so GTK can supply its text-area bounds; it creates no visible window.GtkWidgetMeasureOptions.marginoverrides the final widget's template margins on edges selected bymargin_edges; the default zero mask preserves all native margins. CombineGtkWidgetMarginLeft/Right/Top/Bottom, or useGtkWidgetMarginVerticalorGtkWidgetMarginAll. Values use logical pixels. Status-bar label allocation follows its actual supplied message, native alignment and ellipsis, so cache it with the message text. A paned widget includes two empty visible children, so its preferred width measures the native separator without adding application content widths.GtkCellTextMeasure(nodes, text)andGtkCellTextMeasureMany(nodes, texts, width_chars = -1, ellipsize = false)measure actual GtkCellRendererText requisitions in a native GtkTreeView hierarchy. The batch reuses one renderer and reports component-wise maximum minimum/natural dimensions; renderer padding, Pango metrics and optional end ellipsis are included.GtkTextMeasure(nodes, text, width, scale, font = "", markup = false)returnsavailable, logical-pixelwidth,heightandbaseline. A zero width measures natural size; a positive width wraps by word or character.GtkTextRaster(nodes, text, width, height, scale, align, font = "", markup = false, ellipsize = false, snap_y = false)paints Pango text and GTK text shadows onto transparency, vertically centered and clipped to the box. Alignment is 0 left, 1 center or 2 right. An emptyfontuses the computed CSS font; a Pango description overrides it for application settings such as a clock font. Setellipsizefor a single line with native Pango end ellipsis instead of wrapping. Setsnap_yfor integer vertical positioning, matching GTK's widget and cell allocations.
Text layouts use GTK's widget Pango context, including explicit GTK font settings. Unresolved Cairo font options inherit the native display backend's defaults, queried from an empty compatible surface, before rasterization. This preserves the glyphs used by realized GTK widgets when drawing to RGBA.
Native GTK backend adapters can use GtkNativeReady() and
GtkNativeWidgetNodeApply(widget, node) on the GTK owning thread. The latter
validates selectors/providers and applies them to a borrowed live GTK widget;
the adapter owns its widget lifecycle. GtkNativeSurfaceBitmap(surface, width, height) copies a borrowed Cairo ARGB32 image surface into an owning bitmap.
It checks status, type, format, exact dimensions, stride and allocation bounds;
release the returned buffer with GtkStyleBitmapRelease.
kryon/GtkScrollLinux owns offscreen GTK scrolled windows for native scrollbar
layout, adjustments and drawing. GtkScrollCreate(nodes) accepts a GtkWindow
root, optional GtkBox/GtkGrid ancestors and a final GtkScrolledWindow;
it returns a bounded owning handle, or zero. Release it with
GtkScrollRelease(handle). GtkScrollCancel(handle) cancels an owned drag
on focus loss or hiding; valid handles are idempotent. All calls stay on GTK's
owning thread.
GtkScrollUpdate(handle, props) takes viewport/content dimensions, offsets,
enabled axes, overlay policy and optional pointer state. Its metrics expose the
actual viewport, bar allocations, opacity, adjustment ranges and slider limits.
Use those allocations for content layout rather than reserving a fixed gutter.
GtkScrollWheel(handle, delta, horizontal = false) applies the native discrete
wheel distance immediately. Positive deltas move toward the start. Its page-based
unit follows GTK and its adjustment keeps fractional offsets across notches;
the returned metrics expose the updated values in the same call.
GtkScrollRaster(handle, horizontal = false, scale = 1) returns an owning
straight RGBA bitmap for the allocated native bar, at scale 1–4; release it with
GtkStyleBitmapRelease. Draw it over content at its reported bar allocation.
GtkScrollRasterOver(handle, backdrop, horizontal = false, scale = 1) accepts
a borrowed RGBA backdrop matching the scaled allocation. GTK draws
directly over it on an owned native compatible surface, preserving window
curve coverage and per-layer alpha rounding. The result replaces that backdrop.
GtkPainterScrollOver(painter, handle, bounds, horizontal = false) supplies the
painter's current backdrop and clips that replacement to its visible area.
GtkNativeWidgetRaster(widget, width, height, scale, backdrop) provides
the same bounded raster operation for a borrowed allocated GTK widget. The
caller retains widget ownership; only newly allocated surfaces are read.
Scroll.Props.external_scrollbar and GridMulti.Props.external_scrollbar let a
caller supply native scrollbar visuals and input. They preserve the complete
supplied viewport while retaining wheel, keyboard reveal, content dragging and
momentum; the caller synchronizes the resulting offset with its native bars.
Scroll.Props.immediate_wheel and GridMulti.Props.immediate_wheel opt out of
wheel gliding while retaining drag behavior. The default retains wheel gliding.
ScrollWheelTake(session, key, bounds, scrolls, horizontal = false) consumes
the targeted wheel once; horizontal mode includes the sideways wheel.
GridMulti.Props.preserve_scroll_on_focus retains a native view's manual offset
when focus returns. Its default preserves the existing focus reveal; cursor,
navigation, initial-open, layout and viewport changes still reveal the item.
An explicit valid TreeSetCursor shape also applies to disabled controls;
loading controls retain their loading cursor policy. Without an override,
disabled controls continue using CursorDisabled.
Desktop PollPointer and PollSecondaryPointer expose the gathered frame
sample, including focus-loss release and cleared held state. Raw SDL collection
stays separate from this published view. On X11, physical button sampling also
recovers transitions missed while another window owns focus; queued event edges
still preserve taps completed between polls. Other SDL drivers retain their
existing event sampling.
GtkStyleRasterRegionOver takes the same box/crop coordinates as
GtkStyleRasterRegion, followed by a borrowed straight-alpha RGBA backdrop
matching the scaled crop. CSS background and frame layers draw directly over
that backdrop with Cairo's native rounding. Rendering uses a newly allocated
surface compatible with the GDK window backend, with an image-surface fallback.
The backdrop uploads with Cairo SOURCE; readback maps only that owned surface.
Device scale is normalized before allocation so the supplied CSS scale is
applied once, independently of GDK_SCALE. The returned bitmap is owned;
release it with GtkStyleBitmapRelease. An empty backdrop means transparent.
GtkPainterStyleOver(painter, nodes, bounds) draws those layers on the current
painter pixels and replaces the clipped crop without applying alpha twice.
Toolbar GtkWidgetMeasure results include the actual child button rectangle
in control_* and image rectangle in arrow_*, relative to the toolbar.
GtkFileIconRaster(path, size, scale, nodes) resolves a local file's GIO icon
through the active GTK theme, including MIME inheritance, special user folders
and the filesystem root. GtkFileDescription(path, output) returns the native
localized content description. GtkFileLinkTarget(path, output) queries the
link itself and returns its raw target without following it. These byte-path
APIs accept up to 4095 bytes without NUL; text helpers write NUL-terminated
output and return its byte length, or -1 on failure. The caller must escape
raw filenames and link targets before displaying them. GtkImageRaster(path, width, height) uses installed GdkPixbuf loaders and preserves aspect ratio.
GtkFormatFileSize(size, output) uses GLib IEC units. GtkFormatFileDate(unix_time, output, style = .LocaleDate, now = -1, domain = "") uses the local timezone and
locale date format. Its GtkFileDateStyle.RelativeDate option uses local calendar
days: Today, Yesterday, weekday names for two through six days ago, and the locale
date otherwise. Zero or invalid timestamps use Unknown in relative mode.
Relative labels use the native gettext catalog named by domain, or the
application's default catalog when empty. A negative now uses the current time;
an explicit timestamp permits deterministic comparisons and midnight refreshes.
The same formatter is available without GTK initialization as
kryon/FileDateLinux.FormatFileDate, with its DateStyle enum.
GtkFileSystemFree(path)
returns available bytes from GIO, or -1 when unavailable.
GtkSerializedIconRaster(value, size, scale, nodes) resolves a serialized GIcon
without discarding its native identity or fallback names. GtkContentDescription
accepts a GIO content type and the same output-buffer contract as file descriptions.
kryon/GtkPainterLinux composes these rasters into one managed Image per
surface. Own one GtkPainter; call GtkPainterBegin(*painter, session, bounds),
GtkPainterPaint(*painter, nodes, bounds, text = "", kind = 0, align = 0, revision = 0) and
GtkPainterEnd(*painter, key) inside a retained frame; it returns upload success.
GtkPainterBitmap(*painter, bounds, bitmap) composites a borrowed native bitmap
at its exact pixel dimensions, with the current clip and draw order. It copies
no ownership into the tile cache; the caller can release or reuse the bitmap
immediately. Invalid dimensions/buffer lengths return false without painting.
Kinds are CSS surface (0),
ellipsized text (1), themed icon (2), local file icon (3), image thumbnail (4),
Pango markup (5), serialized GIcon (6), styled naturally sized themed icon (7),
wrapped text (8), and the theme's own check box (9), radio option (10) and
submenu arrow (11) for the last node, such as menuitem > check:checked.
Text snaps to integer positions; thumbnails and natural icons center their
actual bitmap within the allocation. Cached RGBA layers follow Cairo's 8-bit
premultiplied OVER rounding. revision invalidates cached file pixels
when caller metadata changes. clip is a logical rectangle within the surface. The
painter caches at most 256 CPU tiles and 32 MiB, invalidating them when GTK
settings/providers change. It uploads only changed pixels. Call
GtkPainterRelease(*painter) before closing its session; release is idempotent.
Input, semantic labels, layout and file actions remain the application's
responsibility. This module requires an ordinary Kryon raster host.
Large surfaces use an exact, shared 64-pixel region atlas while retaining the
managed image limits. The CPU canvas is bounded to 16,777,216 pixels and 8192
pixels per axis; the atlas holds at most 1024 unique regions (4,194,304 pixels).
GtkPainterEnd returns false if allocation or the bounded unique-region budget
cannot represent the surface. Callers must handle that result.
Set markup = true to validate and render Pango markup, including styled spans,
bold text and escaped characters. Malformed markup fails without painting.
GtkMarkupPlain(markup: string, output: []u8) -> s32 uses the same parser to
decode a plain label for accessibility. It returns the UTF-8 byte count excluding
the terminating NUL, or -1 for invalid input or insufficient space. Failure
leaves the output unchanged; success writes a terminating NUL. This helper
requires no display. Parsing performs no file, network or application actions.
Raster calls return an owning GtkStyleBitmap with physical width, height
and straight RGBA8 rgba bytes. Upload using BitmapImageCreate, then release
the CPU buffer with GtkStyleBitmapRelease(*bitmap). Do not copy owning values.
Release is safe on an empty bitmap and resets its fields. Failure returns an
empty bitmap or metrics with available = false, including when no display is
available. Background color metrics alone cannot represent a CSS gradient;
use the raster call for its actual appearance.
Scale is 1–4. Style paths have 1–32 nodes and up to 32 classes per node;
selector strings and font descriptions are at most 255 bytes with no NUL.
Text must be valid UTF-8 without NUL and at most 65,536 bytes. Raster axes are
at most 4096 physical pixels with a 4,194,304-pixel total limit; icon edges are
at most 2048 physical pixels. Icon names cannot be paths.
GtkStyleProviderCreate(css: string) -> u64 parses CSS with GTK's native parser,
without installing it. Zero means failure. GtkStyleProviderInstall(handle, priority: u32) -> bool installs that provider on this process's default GTK
screen. Repeating the same installation is a no-op. A provider can also be
attached to several node contexts at different priorities without screen
installation. GtkStyleProviderReplace(handle, css) -> bool parses a fresh
provider before replacing the existing one. Parser errors, invalid lengths,
embedded NUL, input above 1,048,576 bytes, and recoverable allocation failures
leave the old provider and generation unchanged. Empty CSS is valid. GTK/GLib's
own fatal allocation policy remains in effect. CSS may reference resources;
applications choose which CSS they trust.
GtkStyleProviderRelease(handle) -> bool removes its screen installation and
releases owned refs. Remove attachments using that handle before the next query;
a stale attachment rejects the whole path. Zero, stale and double release return
false. There are at most 64 live providers and 32 attachments per node. Handles
are process-local, never reused, and must not be persisted. Release works after
display environment variables change, without reinitializing GTK.
GtkStyleDarkPreferencePush(value: bool) -> u64 temporarily sets this process's
gtk-application-prefer-dark-theme. GtkStyleDarkPreferenceRestore(token) -> bool removes that scope. The newest live scope wins, even when older scopes
are restored out of order. The last restore reinstates the original value and
releases the settings reference; the next push captures a fresh original.
There are at most 64 live scopes. Zero/stale tokens fail without changing the
setting. These calls do not modify desktop configuration files or other
processes. Coordinate writes to this same property while scopes are active.
GtkStyleGeneration() -> u64 changes immediately on successful provider
installation, replacement or release and effective preference changes. Creating
an unattached provider and failed calls do not change it. Cache query, raster,
text and icon results with this generation and the complete path (including
attachments, priorities and states). The bridge itself retains no result cache.
Native GTK settings notifications invalidate generation synchronously, without
retaining a settings owner. A default-settings identity change invalidates
on the next bridge call. Default icon-theme changed notifications also
invalidate generation. Unrelated GLib callbacks leave caches valid.
GtkStylePoll() returns nonzero once after API invalidation
as well as for delivered events. Call it before checking cached styles. All
provider/settings APIs share the GTK owning thread rule and fail safely without
a display. This opt-in Linux module adds no GTK dependency to portable, WASM,
Windows or Go application imports.
Image.Props.clip_polygon clips an image without stretching its content.
Supply 3–4096 points in normalized destination coordinates (0–1); the path
closes automatically. Empty leaves the image unchanged. Invalid coordinates,
too few points, or combining a polygon with a mesh draw nothing. Native,
hosted and browser images retain their own copy of the supplied points.
Image.Props.mesh warps the same image over a grid of columns × rows
screen points, row by row from the source's top left, each cell drawn as two
textured triangles: a cut-out puppet's painted arm can bend at its elbow, or
a picture can follow a curve. The bounds still clip it; fit, origin,
rotation and the style radius do not apply, and a grid with too few points
draws nothing. Points are copied when the image is queued, at most 4096 per
image (256 through a portable bundle's hosted Image).
Image.Props.preview_path names a small copy of the same picture that draws in
its place, with the image's own bounds, fit, mesh and clip, while the picture
loads or when it is unavailable, so something shows at once and the picture
replaces it when ready. A preview of part of a picture (a nonempty source,
such as a jigsaw piece) needs Image.Props.full_size, the picture's size in
pixels, to map that rectangle onto the preview; without it the image waits for
the picture. Hosted previews pass the same asset policy as their picture.
image_showing.ImageShowingOf(session, image) reports ImageShowingNone
(loading), ImageShowingPreview, ImageShowingFull or
ImageShowingUnavailable, natively and through a portable bundle's host, so
an app can wait for a picture before what belongs with it. Asking starts the
host loading the picture, which also fetches pictures shown soon.
image_mesh.ImageMeshQuad(bounds, camera, points) constructs a four-corner
mesh for the standard Image.Props.mesh. It uses the same 2D Camera as
WorldToScreen, with caller-owned space for four points; too little space
produces an empty mesh. Rotation and scale stay on the standard image surface.
TileMapProps.pixel_snap fits and positions whole-pixel cells. nearest selects
nearest-neighbour sampling for the whole map; nearest_tiles selects individual
tile indices while the rest remain smooth. Sampling survives the hosted codec.
A hosted map uses batched sampling only when its host advertises
tile_map.sampling; hosts without mesh support draw the same standard Images individually.
Pixel snapping uses bounds fitted by the bundle.
WidgetPaletteUse scopes semantic colors along with widget rules. Hosted
AppThemeColor calls and compositions using canvas, surface, text, border and
accent see the same palette. WidgetPaletteRestore restores the surrounding palette when calls nest,
including its text style and semantic tokens. The host frame unwinds palettes
a guest leaves open. Sixteen nested parents are retained; scopes beyond that
restore to the deepest retained palette, then unwind to the original host.
The outermost restore preserves the complete prior token set, including
host-specific colors and the absence of unset tokens.
Hosts call PaintResourcesChanged() when replacing raster resources without
changing widget props. Retained frames then compose and paint again, including
when a browser graphics context resets or an app updates its image assets.
Shape.Draw(Shape.Props), Circle(Shape.CircleProps), Shape.Ring(Shape.RingProps) and
Shape.Triangle(Shape.TriangleProps) draw lines, circles, radial gradients,
rings and triangles. Like Box, each
is decorative: it submits a node covering what it draws and queues one paint
command. Kryon cuts the shape into triangles, clips them to its parent's clip
and sends each colour's triangles to the host in one RasterTriangles call;
a radial fade is drawn as rings of one colour each. Box.Props.fill_bottom
with has_fill_bottom fades a box's fill from top to bottom.
Import kryon/shape to use these shapes, including in a portable hosted
bundle.
The smallest executable application imports kryon/app and the widgets it
draws:
App :: #import "kryon/app";
Text :: #import "kryon/text";
main :: () -> s32 {
window := App.Window.{ .title = "Hello", .width = 320, .height = 160 }
return App.Run(window, Draw)
}
Draw :: (frame: App.Frame) {
Text.Draw(frame, Text.Props.{ .text = "Hello, world!", .size = 32 })
}
Such a file is a program: it owns main, and kryon/app selects the desktop
host for a Linux C build and the Canvas host for a web build. In this
checkout, ziran build --project --target=c --exe --entry hello:main hello.zi
builds it directly: Kryon's [package] links names the desktop host's system
libraries, so no caller LDLIBS is needed. Ziran applies those links to the
root manifest only; an application that depends on Kryon builds through the
project tool, which supplies them.
A program carries only what it uses. kryon/app imports each platform's
window (desktop_window, page_window) and frame loop (frames_desktop,
frames_web) as separate modules, so App.Show(window) reaches only the
window: on Linux the checked program of examples/window.zi is the window,
kryon/app, app_types, desktop_window, desktop_process_linux,
sdl_event, pixmap_sdl and C strings. In a portable bundle the window is zx_window: the checked program is
the window, kryon/app, app_types and zx_window, and the bundle asks its
host only for the window, its events, clearing and presenting
(ZxWindowOpenHost, ZxWindowEventHost, ZxWindowClearHost,
ZxWindowPresentHost, ZxWindowCloseHost). Kryon's desktop zx player binds
them to the same SDL window and runs the bundle's main as native code, so
with the player installed (make install-user) ziran run --backend native window.zx opens the window. The same capabilities are a host library,
libkryon-desktop.so from zx_window_host.zi (make zx-window-host), which
make install-user registers as kryon-desktop.library, so zx2native window.zx writes a Linux executable that links them and opens the window
itself. make zx-window-test checks both on a private Xvfb, and that with no
library registered zx2native stops at the gap naming ZxWindowOpenHost. In
the browser, a project profile with backend = "canvas" and codegen = "zx"
takes a program entry too: its bundle is the program's own main, and the ZX
canvas player binds the window to the page's canvas (window_page_player),
lowers the bundle to Wasm in the page and runs it, each wait for an event
yielding to the page. App.Run(window, Draw) brings the frame loop, the widget tree's frame
driver (TreeFrameUse) and, on Linux, the accessibility tree
(DesktopAccessibilityUse). The desktop raster loads pictures, smooth copies and
fonts when a frame first draws them, video when it opens, and the test driver
only with KRYON_TEST_DRIVER. make pay-per-import-test checks the examples'
generated C, the window's checked programs and its bundle's modules and host
capabilities.
The project tool accepts a program as a project's entry. When the entry module
declares main, kryon build --profile NAME generates a host that only calls
that main, for a desktop profile and for a canvas page alike. A program
entry uses codegen = "c99" for native source builds. Desktop and Canvas
codegen = "zx" profiles also accept a program with its own main; the
player binds its window capabilities. Frame entries use the frame host.
The selected host owns the process entry point, calls BeginFrame and
EndFrame, supplies input to the session, and presents paint operations.
Every host reports the same key codes through KeyboardTake: letters as
uppercase ASCII and named keys as KeyEnter, KeyBackspace, KeyLeft, and
the other Key constants. A letter is the one the active keyboard layout types,
not its physical position. TypedTextTake collects pending text into the caller's byte
buffer, and TextFieldInputFor(key, modifiers, text) turns both into a
focused TextField's input.
An entire Unicode scalar must fit before it is consumed; a buffer of at least
four bytes guarantees progress. tree_input.TypedCodepointPeek(session) reads
the next scalar without consuming it, and TypedCodepointCapacity(session)
reports free slots in the bounded 32-scalar session queue.
Every graphical host owns an ordered key/text queue and exposes one session
delivery call: DesktopInputTake(session) or CanvasInputTake(session). Poll the host every frame, including while session
text remains unread, then call its take once before composition. The take
transfers one editing action or a printable-key/text run into that session and
returns (key, modifiers) using portable key and modifier codes. Unread text
delays later editing actions; Return can commit a text run delivered in the
same call. Focus loss cancels queued keys so an old shortcut cannot fire after
focus returns, while text already committed by the platform remains ordered.
Desktop's bounded 256-record delivery queue backpressures SDL key and text
events without blocking window lifecycle events. Run
build-queue -- make test-focus TEST=desktop_input_backpressure for the native
SDL source and saved-IR regression.
The Canvas app host retains unread key presses, repeats, IME commits and
gamepad navigation across drawing frames. Pressed/released snapshot flags still
expire at the frame boundary; delivery does not replay them. Each queued press
or repeat retains its browser event's Shift, Control/Meta and Alt modifiers.
Custom loops call CanvasInputTake(session); an empty take reports current held
modifiers. CanvasModifiers() and CaptureFrameInput(session).modifiers still
report held state at their own sampling time, so consuming a shortcut never
changes held keys or snapshot flags.
Application code owns its product state and calls widgets within Frame.
The complete manifest and build commands are in PROJECTS.md.
Individual .zi modules under src/ui can also be imported by
non-graphical Ziran programs. A program that does not import Kryon uses no
Kryon code. A portable .zx links only imported modules and needs a host
binding for any platform effect they call.
To run a portable .zx as a windowed app in a host such as TaijiOS, use
kryon/host/surface. The bundle runs
ordinary Kryon widgets with its own session and software raster. The host
supplies the window, pixel presentation and ordered input events.
An application runs another .zx inside its own window with
hosted_app: HostedAppOpen takes the
bundle's bytes, HostedAppStart asks the host about every capability the
bundle requests and binds them to one HostCall, and HostedAppRun runs it
under a step limit. HostedAppRestart keeps the working instance until the
new one passes the host's handshake. It draws that
bundle's widgets with widget_host. The
bundle calls each widget's HostedHost function; the host binds
WidgetHostCall for the functions WidgetHostSupports lists, and wraps each
bundle frame in WidgetHostBegin(session, asset_allowed) and
WidgetHostEnd(). The callback decides which asset paths the bundle may
draw; texture handles never cross. Records match fields by name, so a bundle
and its host may be built against different Kryon layouts.
Hosted image_raster.ImageWidth(path) and ImageHeight(path) return typed
dimensions for assets approved by the same callback. Paths resolve through
the active bundle owner; denied paths and calls outside a frame are rejected.
An unresolved approved image returns -1, and an empty path returns 0.
Host replies copy returned strings into the bundle's memory, including text
inside records and collections. A host may reuse its reply buffers on its
next call; the bundle can retain those strings across calls and instance runs.
scripts/generate-widget-codecs.py
generates the codecs for Kryon's widget records and, with --uses, for an
application's own records.
A bundle measures text with its host's fonts through
text_measure: TextWidth(session, props) is
the width a line takes and TextHeight(session, props) the height Text
takes to draw a paragraph wrapped in props.bounds.width.
A vector icon that is not a button, such as a symbol beside a name or a coin
beside an amount, is SvgIcon(session, SvgIconProps.{bounds, shape, color})
from svg_icon_widget; a bundle submits it
to its host like the other widgets. An icon is rasterized once at the
screen's pixels and kept, with the 255 others painted most recently, as the
rectangles it paints, so a screen with many icons does not rasterize them
again every frame. A host that draws textures registers
SvgIconUseTextures(make, free) and then paints each icon as one image of
the same pixels.
A bundle draws a row of choices, such as a week or calendar view, with
SegmentedControl.Draw(session, props, options) from
segmented_control_widget; its host
draws it as it draws its own, with up to 32 options. It frames a form's
sections with Fieldset.Draw(session, props) from
fieldset_widget, and places a toggle at a
row's end with the size ToggleSize(session, props) from
toggle_measure answers, which stays apart from
the toggle widget as text_measure stays apart from Text. Lines, circles,
rings and triangles from shape_widget are
hosted too, so a bundle can draw a chart's lines and dots; their host fills
them with the renderer's RasterTriangles. Slider and DiscreteSlider
from slider_widget and Progress from
progress_widget are hosted as well: the
host drags the slider with its own pointer and answers the value, and paints
the progress bar.
open_uri opens a link with the platform's
handler: OpenUri(uri) passes it unchanged to the desktop opener, Windows'
shell, an Android ACTION_VIEW intent or a new browser tab,
and CanOpenUri(uri) says whether that platform can open it. Android code
reaches the activity through android_jni.
The generated Android activity also exposes public static synchronized String takeLaunchUri() (JNI static signature ()Ljava/lang/String;). It consumes the
latest nonempty intent data string of at most 4,096 UTF-16 units and returns
"" when none is pending. Capture occurs before native startup and on
onNewIntent; recreation with saved state does not replay the original launch.
The single slot is process memory only; a newer bounded value replaces it.
Null, empty, oversized or unreadable data leaves the slot unchanged. Values
are preserved without decoding or truncation. The application owns URL
allowlisting, UTF-8 copy bounds, user confirmation and any resulting action.
The bridge does not open URLs or validate their origin. Applications own
their manifest intent filters and custom-activity integration.
kryon/play_billing exposes PlayBillingBuy(id, accountID, output) for
Google Play editions. Pass the signed-in account's stable ID. The bridge sends
buy:product|account and sets Play's obfuscated account ID to the lowercase
64-character SHA-256 digest of the account ID's UTF-8 bytes. Empty IDs,
embedded NULs, delimiters and oversized requests are rejected without opening
a purchase sheet. Each queued sheet retains the account from its request.
The application server must verify the paid purchase and its account binding
before crediting it; this client binding alone grants no balance or referral
reward. Other editions/platforms return an empty answer.
Other platform services an application may import:
| Module | Surface |
|---|---|
file_export |
ExportBytes and ExportFile: hand a finished file to the user as a browser download or through Android's share sheet |
pdf_export |
PdfOpen, PdfImage, PdfText, PdfPage and PdfClose: compose Linux-native PDF pages from full-resolution images and searchable UTF-8 text |
file_picker |
PickFile(FilePickerProps, output): zenity on Linux and BSD, Windows' common dialog, and the browser's chooser, which copies the file into the page's file system |
window_close |
WindowCloseWatch(window) and WindowCloseTake(): close requests for the application's own SDL or Win32 window, so it can ask first or hide to a tray |
idle_time |
IdleMilliseconds() from the session's idle service over D-Bus, and IsWaylandSession() |
notification_desktop |
The notification host for Linux and BSD desktops, through notify-send |
android_picker |
AndroidPickerOpen, AndroidScannerOpen and AndroidPickerPoll: asynchronous document and QR selection. Import accepts one MIME type or a comma-separated allowlist; custom activities use the scaffold's org.kryonlabs.platform.DocumentTypes.apply to set Android's primary type and EXTRA_MIME_TYPES. Android filters by MIME type rather than filename extension. AndroidSavePickerOpen returns a private staging path through the same poll; write it, then AndroidSavePickerCommit confirms the selected document was written and closed. The activity implements openImportPicker, openQrScanner, openSavePicker and savePickedFile. |
android_text_editor |
Input method editing on Android: the activity's input connection sends snapshots of the focused field, so composition, autocorrect and suggestions work; android_device's text input uses it when the activity implements setTextInputState and nativeTextInputState |
file_download |
FileDownloadStart, FileDownloadPoll and FileDownloadRelease: a large file downloaded to a path, appearing only when complete, through curl, the browser's streaming fetch into the page's file system, or the Android activity |
http_transfer |
HttpTransferStart, HttpTransferPoll and HttpTransferCancel: HTTP requests that run while the application draws, through curl on a worker thread, the Android activity's transport, or the browser's fetch |
page_socket |
PageSocketOpen, PageSocketPoll and PageSocketClose: a browser WebSocket for text events, polled each frame, with bounded messages and a token carried as a subprotocol |
browser_viewport |
BrowserViewportMeasure and BrowserResizeSettled: the room a canvas application has in the browser, and when a new size has settled enough to resize to, for applications that size their own canvas |
After a completed HTTP poll, transfer.failure distinguishes a response that
exceeded the caller's buffer (HTTP_TRANSFER_FAILURE_CAPACITY) from a transport
failure. Failed responses never publish partial bytes. A new start or cancel
clears the failure. Large logical transfers can use this result to switch to
the service's paged API and preserve progress without enlarging frame memory.
src/ui/modules.txt is the core build inventory.
make test checks source, saved .zir, .zx, and generated C/Go behavior.
See FEATURE_MATRIX.md for package and host verification.
Portable apps can import kryon/input_protocol for pointer observations,
key codes, modifier bits and PointInBounds without loading the native tree
implementation. Existing tree_input imports retain that surface.
kryon/file_picker exposes the native file chooser; kryon/app_theme reads
optional host theme colours from a portable app.
An app embedded by a supervising host, such as Harmony's app host, draws in
the host's theme by default on Linux. The host names its process and the
window it embeds the app in (HARMONY_APP_HOST_PID, HARMONY_APP_CONTAINER)
and keeps its palette on that window (_HARMONY_APP_THEME).
SystemThemeLinux.SystemPaletteRead() returns that palette after checking
that the host is the app's parent and owns the window; started on its own, an
app gets the desktop's GTK palette as before. Each call reads the host's
current palette, so an app that reads it again follows a theme change.
ParentThemeLinux.ParentThemeActive() says whether a host supplies the theme,
and ParentPaletteRead(*palette) reads only the host's palette. libX11 is
loaded at run time and only when a host is named.
SystemThemeHostLinux.SystemPaletteFollow(), called once per frame, applies
that palette (the desktop's when not embedded) the first time and again
whenever the host changes it, and returns true when it applied, so an app
follows its host's theme change with one call; portable apps call
SystemThemeHost.SystemPaletteFollow(). Applying installs the palette's style
rules and sets the active theme's colours (SystemPaletteApply), so code
that draws from CurrentPalette() follows too.
SystemTheme.SystemPaletteColors(palette) expands a system palette into a full
theme Palette (surfaces, text levels, borders, accent, controls) for an app
that draws from one.
Cover carousels
kryon/carousel provides Carousel.Draw(session, props, items, state) for a
full-cover browser. Keep a Carousel.CarouselState, pass Carousel.CarouselItem values with
portrait and landscape art, an optional source crop, an optional logo and
caption, and an action label. A zero source uses the whole selected image.
It returns the activated item index, or -1. Swipe, wheel, arrows and
Enter/Space share one selection; only that selection exposes an action.
The caller keeps game launching and any footer controls. CarouselArtwork
paints the same cover composition for a native loading screen and accepts the
same optional source crop, defaulting to the whole image.
Loading surfaces
kryon/loading_screen provides LoadingScreen.Draw(session, LoadingScreen.Props)
for app starts and longer operations. Supply a title, localized detail and
an app icon (icon_shape or icon_asset). Its responsive composition uses
the current canvas, surface, border and accent tokens in native and hosted
apps. A quiet arc moves with now; reduced_motion keeps it still. Set
has_progress, completed and total only for measured work, to show a
slim standard progress bar instead. It never invents a percentage. The same
surface is exported by kryon/loading_screen; title/detail class IDs allow text styling.
Use loading_indicator for small inline waits, with the same theme accent.
Game touch controls
Import kryon/cursor for CursorSet(session, CursorProps) -> bool,
CursorSetDefault(CursorProps) -> bool, CursorSetPointing(CursorProps) -> bool
and CursorHover(session, shape) -> bool. A request persists until the next
deliberate change: repeating it every frame changes nothing, frames never clear
it, and the empty request .{} withdraws it. CursorSetDefault sets the
application cursor that every session inherits; it replaces the default, arrow,
clickable and disabled widget shapes, while text, crosshair and resize shapes
still show through. CursorSetPointing sets the application's pointing cursor,
shown instead only where a click does something: over clickable widgets and
over targets the app marks with CursorHover. Without one, clickable shows the
application cursor. A session's own request wins over all of them. Requests
copy their asset path; disposing or closing a session drops its request.
A target the app draws and hit-tests itself (a painted hotspot, a field)
reports the shape under the pointer with CursorHover(session, shape) while it
builds the frame, from the same test that decides its clicks. A frame keeps its
highest-priority mark, and its commit replaces the previous frame's, so the
cursor changes only when the hovered target does; a retained, cancelled or
failed frame keeps the committed mark, and a frame without one shows the
default. A widget with its own shape under the pointer wins over the mark,
except a disabled one the app's mark covers. A Press the app refines with its
own hit test, such as a painted shape inside its bounds, sets
Press.Props.cursor to CursorArrow while the pointer is off that shape; only
the cursor changes, never presses, touch or keys. Invalid shapes and inactive
sessions return false.
#import "kryon/cursor"
// Once at startup: a calm arrow everywhere, a hand only where a click works.
unused CursorSetDefault(CursorProps.{.asset_path = "assets/arrow.webp",
.width = 32, .height = 32, .hotspot_x = 6, .hotspot_y = 2})
unused CursorSetPointing(CursorProps.{.asset_path = "assets/hand.webp",
.width = 32, .height = 32, .hotspot_x = 8, .hotspot_y = 1})
// Each frame, from the hit test that opens the painted door.
if DoorAt(pointer.x, pointer.y) { unused CursorHover(session, cast(s32)CursorShape.CursorClickable) }
// A deliberate tool state; .{} returns to the application cursors.
unused CursorSet(session, CursorProps.{.asset_path = "assets/can.webp",
.width = 32, .height = 32, .hotspot_x = 4, .hotspot_y = 6})
width, height and the integer hotspot are logical units, each size 1–128,
independent of the source image size and UI zoom; the hotspot is measured from
the top left and must be inside. Hosts rasterize at their own pixel density
(desktop XCURSOR_SIZE/24, web devicePixelRatio), so give a source at least
two to four times the logical size. asset_path is at most 4095 bytes with no
NUL. With no asset, use shape (the CursorShape values 0–10) or hidden;
size and hotspot must then be zero. An asset and hidden together are invalid.
Invalid requests return false and keep the last valid request. A missing or
undecodable image falls back to the requested system shape; only an explicit
hidden request hides the pointer. CursorResolve(session, widget_shape) returns
what a host shows.
The SDL/Cairo desktop host applies a real bitmap cursor scoped to its own
windows, caches decoded cursors, and calls the system only when the resolved
cursor changes, so switching between requests never flickers. X11 receives
premultiplied pixels and other drivers straight alpha, so soft edges show no
light fringe. It restores the system cursor on close. Canvas draws the
image into a CSS cursor (a 1x image plus an image-set density entry) with the
same hotspot on the canvas. Other hosts
retain their system pointer; touch feedback is drawn by the application. These
requests never move, lock, grab or warp a pointer.
A picture cursor needs the host's image decoder. Importing kryon/cursor, as
an application does to request a cursor, registers the decoder through the
CursorPictureHost(asset_path, width, height, pixels, premultiplied) -> bool
host capability; the cursor module the hosts themselves import does not, so a
program that requests no cursor links no image decoder. A host that shows no
picture cursors exports the capability and returns false, as the terminal and pixmap hosts do, and a custom host linked with a program
that imports kryon/cursor exports it too. An application that hosts widget
bundles imports kryon/cursor for its guests' picture cursors.
The test driver (kryon/test_driver) is test code and an ordinary build
leaves it out: its procedures then pass the platform's input through
unchanged. A build that a test drives defines KRYON_TEST_DRIVER, either with
--define KRYON_TEST_DRIVER on a direct ziran build or by setting the
variable in the environment of kryon build. The program then obeys the
directory the same variable names when it runs. A program built without the
driver and started with the variable set stops at once and says how to build
it, so a test fails with the reason instead of waiting for a reply.
On Android, the private kryon-test-driver folder activates a compiled test
driver. Normal builds ignore a folder left by an earlier UI test.
A test captures what the app draws with DriverCapture(driver, path) (the
capture path= command): the desktop host writes its next finished frame to
that file as a PNG, the same raster it shows. Hosts without a raster to read
reply "this host does not capture frames". A custom host captures by writing
its next finished frame to TestDriverCapturePath() when that is not "" and
reporting with TestDriverCaptured(written).
Portable hosted apps use CursorSet and CursorHover with KRYON_HOSTED_UI
(the application cursors belong to their host). Their only effects are
cursor.CursorSetHostedHost and cursor.CursorHoverHostedHost, which marks
only the active session's building frame; WidgetHostCall requires the active
WidgetHostBegin session. Asset requests must name a normalized packed path
under assets/, pass that instance's existing asset policy, and resolve through
its existing asset resolver. The host copies the resolved path before returning;
no guest image bytes, pointer or native cursor handle crosses this boundary.
An unavailable resolution returns false. Hosts apply the resolved cursor after
committing the frame with DesktopCursor(session) or CanvasCursor(session);
the standard loops already do this. Custom hosts must restore cursors before
teardown.
The desktop host selects the native arrow when its window opens, before the
first frame. DesktopSetIcon(width, height, rgba) copies straight RGBA into
that host's window icon. Dimensions must be 1–512 and the slice must contain
exactly width * height * 4 bytes. The caller retains its pixels; theme-aware
applications can pass GtkIconRaster output and release it immediately.
The generic desktop player extracts packed assets into a private directory under
TMPDIR (an existing absolute directory), or the system default when unset,
and removes that directory on normal exit.
kryon/joystick provides SwipeArea (swipes and taps over a board) and
its secondary_tap option reports a right click as a tap at that position.
It is off by default. The same module provides
Joystick (a stick to lean). kryon/direction_pad provides
DirectionPad(session, DirectionPadProps), a four-way pad like a game
controller's D-pad, drawn in the largest square of its bounds. Directions are
0 left, 1 up, 2 right and 3 down. It returns the arm held (direction) and
step: true when an arm is pressed or the thumb slides onto another arm,
then while held after twice repeat_seconds and at each repeat, like a held
arrow key. The hub stops, and a quick tap steps once. floating lays it
over a board: lighter arms and outlined arrows let the pieces under it show
through, and drawn after the board it takes the presses there. It is composed
from Press, Box and SvgIcon, so hosted games can use it.
DirectionPadBounds(usable_viewport) places a floating pad at the bottom left
with 24–32 logical units of edge padding and a 168–216 unit side on normal
phone screens, in either orientation. Pass the area inside system insets and
app bars; very small embedded areas shrink the pad to fit.
joystick.SwipeFeedback(session, SwipeFeedbackProps.{key, gesture, size})
draws a faint base at a SwipeAreaResult's contact start and a glowing ball
following the finger, clamped to that base. It disappears on release and
does not take input. Draw it after the board; size is the base diameter
in logical units (56 by default). The app keeps its movement rules.
Rotated text
Text.Props.rotation rotates text clockwise in degrees about bounds top left
plus Text.Props.origin (logical units). Zero keeps horizontal text; origin = Vector2.{bounds.width / 2.0, bounds.height / 2.0} rotates about the box centre.
Layout and font sizes stay unchanged. Native and Canvas rasters preserve the same pivot; local text clipping rotates with the text,
while ancestor clipping stays in its original coordinate space.
Reading pages
text_measure.TextPage(session, props, start) returns a UTF-8 byte range
(start, end, next) that fits props.bounds. Draw text[start:end] with
the same Text props and continue at next. Only separating whitespace is
skipped; a viewport shorter than a line reports no progress. Apps keep their
own content anchors and page indexes so reflow preserves the reading place.
Text.Props.line_gap supplies extra units between lines. typeface names a
registered face or a font asset. Hosted fonts pass the same asset policy as
images; absolute host paths are refused. Native and Canvas hosts select the face
for measurement and for queued paint, restoring the interface font afterward.
Native Text typography
Stylesheets set typography on Text and Button through style.StyleData. Set the
matching control_props.StyleField bit for each value.
| CSS property | StyleData fields | Supported values |
|---|---|---|
font-weight |
StyleFontWeight, font_weight: s32 |
normal (400), bold (700), numbers from 1 to 1000. |
font-style |
StyleFontStyle, font_style: FontStyle |
FontStyleNormal, FontStyleItalic, and FontStyleOblique. |
letter-spacing |
StyleLetterSpacing, letter_spacing: float32 |
normal (0) or a signed logical pixel length, including fractions, bounded to ±1024 logical pixels. |
line-height |
StyleLineHeight, line_height: float32, line_height_unit: LineHeightUnit |
LineHeightNormal with value 0 uses the natural glyph height. LineHeightFactor multiplies the font size by the value (so 125% is 1.25). LineHeightLength takes a logical pixel length. Both numeric units accept zero. |
Explicit line height replaces the interline gap and centers the natural glyph
box within each line. Text measures and paints the same rounded line height.
Button measures the label's line box before positioning the glyphs and its optional
detail. Legacy styles with a positive line_height and no unit keep the existing
widget behavior. Text uses Text.Props.line_gap, and Button uses the legacy pixel height.
Cairo/Pango and Canvas use their platform's font matching and synthesis when a
family lacks the requested face. Canvas tracking requires CanvasRenderingContext2D.letterSpacing.
Pixmap's bundled regular outlines apply tracking between extended graphemes.
Android's selected Pixmap typeface uses Paint's native shaping and letter spacing.
Android API 28 and later use numeric weights. Earlier versions group them into
normal and bold, and Android maps oblique to italic. CSS relative weights and
angle-based oblique are outside this API.
Text.Props.wrap = Text.Wrap.TextWrapAnywhere wraps at extended Unicode grapheme
boundaries, including inside unbroken usernames. Combining marks, emoji ZWJ
sequences and flags stay whole. Spaces are preserved and CR, LF and CRLF end
lines. A single grapheme wider than the bounds stays whole on its own line;
nonpositive widths disable wrapping. The default TextWrapAuto still wraps at
word boundaries and keeps oversized Latin words intact. Supply enough height
for the resulting lines.
View transforms
view_transform.ViewFit(viewport, page_width, page_height, maximum) returns
the state for a page that fills its viewport at zoom 1. The pure mapping and
mutation helpers convert between page and screen coordinates, zoom at a point,
pan, resize while preserving the visible centre, and drive a two-finger pinch.
Every mutation keeps zoom in range and leaves no empty space around the page.
Hosts observe wheel, pointer, and touch input and pass those observations in;
ViewWheelFactor(notches) supplies the bounded 1.2-per-notch wheel factor.
Desktop host parts
The SDL2/Cairo desktop host (desktop_runtime) carries optional parts that
only programs importing them link. Key codes are Kryon's: letters as
uppercase ASCII, named keys from 256 (Escape), as desktop_keys maps SDL's.
desktop_runtimeitself routes each SDL event to the window it names, andDesktopWheelMoveX()gives the poll's sideways wheel steps (positive to the right) besideDesktopWheelMove(). Over another window of the program the main window's pointer is at -1, -1 and presses nothing.OpenDesktopWindow(width, height, title, options)opens the window with any ofDesktopWindowResizable,DesktopWindowUndecorated,DesktopWindowTopmostandDesktopWindowAlwaysRun(keep the frame cadence while hidden or minimized);OpenDesktopTitledis the resizable window.DesktopFrameRate(fps)caps drawing atfpsframes a second, or draws without waiting with 0 (the default is 60, settling to 15 while nothing changes).DesktopExitKey(key)makes a key end the loop as closing the window does (0 turns that off).PollMiddlePointer()reports the middle button likePollSecondaryPointer()the right one, andDesktopPrepareGlyphs(text)loads the fallback faces non-ASCII text needs before a frame draws it.kryon/desktop_activity:DesktopWaitForActivity(descriptors, milliseconds)sleeps until one of the program's own descriptors (such as a terminal's PTY) is readable, window input is queued, or the time ends, and returnsDesktopActivityDescriptor,DesktopActivityInputorDesktopActivityNone. Queued input stays for the nextPollDesktop. Windows and Android returnDesktopActivityUnsupported; keep drawing there.kryon/desktop_keyboard:DesktopKeyDown(key),DesktopKeyPressed(key)(the first press),DesktopKeyRepeated(key)(keyboard auto-repeat) andDesktopKeyReleased(key), for the lastPollDesktop.kryon/desktop_window_state:DesktopMinimize,DesktopMaximize,DesktopRestore,DesktopRaiseandDesktopSetAlwaysOnTop(enabled)ask the window manager;DesktopMinimized,DesktopMaximizedandDesktopAlwaysOnTopreport what it did.DesktopSetFullscreen(enabled)andDesktopToggleFullscreen()fill the monitor at the desktop's own resolution andDesktopFullscreen()reports it.DesktopMonitorBounds()andDesktopMonitorUsable()give the window's monitor in desktop pixels, andDesktopDisplayScale()its density over 96 dpi (X11'sXft.dpiwhen set).kryon/desktop_secondary_window: up to three more windows, each with its own Cairo surface, presenter and events:OpenSecondaryWindow(title, x, y, width, height, flags, background, scale),CloseSecondaryWindow,BeginSecondaryWindow/EndSecondaryWindowaroundBeginSecondaryFrame/EndSecondaryFrame,SecondaryWindowInput,PumpSecondaryWindows,IsSecondaryWindowClicked,RightClicked,Dragged,TakeSecondaryWindowClose,GetSecondaryWindowSize,Position,ClickPosition,SetSecondaryWindowKeyboardGrabandCloseSecondarySession, plus each window's own keys (IsSecondaryWindowKeyDown,KeyPressed,KeyRepeated,KeyReleased),IsSecondaryWindowFocusedandSecondaryDesktopWindow(its SDL window).kryon/cairo_assets:RasterUseAssets(read)gives the raster the program's own assets, such as files embedded in its executable: a picture whose bytesread(path)returns decodes from memory in any format the raster decodes.RasterAssetsClose()forgets them. Each asset the decoders read, and each facekryon/cairo_typefacesis given as bytes, is a file of its own: an in-memory file on Linux, and on Windows a file in the user's temporary folder, removed when it is closed or when the program exits.kryon/cairo_typefaces:kryon/typeface_source'sRegisterTypefaceData,RegisterTypefaceFile,RegisterSystemTypeface,UseTypefaceandClearTypefaceson Pango and fontconfig. Registered faces also serve scripts the selected face lacks.kryon/cairo_render_scale:RasterSetTransform(scale, offset_x, offset_y)maps layout points to pixels aspoint * scale + offset. It rejects scales outside(0, 16]and nonfinite offsets. The transform survives window resize;RasterScale()reads its scale. Custom hosts map their raw pointer withRasterPointFromPixels(point)before routing input to the widget tree.
make desktop-windows-test checks these on a private Xvfb with XTest input.
Asset audio
kryon/Media retains MediaOpen, pause/stop/state/message and text fetching.
It also exports MediaAudio(session, command: MediaAudioCommand) -> MediaAudioResult. A hosted bundle uses KRYON_HOSTED_UI and requests only
media_audio.MediaAudioHost for this function. The same types/function are
available directly from kryon/media_audio.
MediaAudioCommand has operation: MediaAudioOperation, voice: s32,
asset: string, music: bool, looping: bool, and gain: float32, plus the PCM fields below.
MediaAudioOperation is Capabilities, Load, Play, Gain, Stop,
Unload, Status, CreateStream, SubmitStream, Pause, or Resume. Voice IDs are caller-selected 1..16, local to one
actual app instance. Each loaded voice has an independent decoder and gain;
several effects and music voices can play together. Load uses asset,
music, and gain; unload an occupied ID before reloading it. Play starts
from the beginning and uses looping, which is accepted only on a voice
loaded with music = true. Gain changes only that voice. Gain must be
finite and in 0..1; out-of-range, NaN and infinite values are rejected,
without clamping or changing playback. Zero-initialized gain means silence.
Stop retains a decoded voice for replay; Unload stops and frees it.
Status updates the stream and reports actual completion. Capabilities
does not need a voice ID. There is no queued playback or automatic transition.
MediaAudioResult owns message: string across the hosted boundary, with
code: MediaAudioCode, state: MediaAudioState, capabilities: u32, and
writable: bool for PCM streams, has_position: bool, and position_seconds: float64.
Codes are Ok, Unsupported (no provider), Unavailable (no device/reader
or an operation already in flight), Suspended (browser context cannot play,
including before an autoplay-unlocking gesture), Invalid, Denied,
Missing, Limit, Failed (provider/decode failure), and Backpressure
(a full PCM stream). States are Unloaded,
Ready, Playing, Stopped, Finished, and Paused. A failed command does not
imply playing; inspect code first. Capability bits 1, 2 and 4 mean asset
effects, asset music and gain. Providers retain those capability bits when
the device is unavailable or suspended. Bit 8 advertises bounded PCM streams.
Bits 16, 32 and 64 advertise asset pause/resume, asset-music position, and PCM pause/resume respectively. A partial provider need not implement these features; check its bits and result code. Existing operation/state wire values are unchanged; Pause, Resume and Paused are appended.
Pause changes Playing to Paused, preserving the individual voice's offset,
loop, gain and queued PCM copies. Repeating Pause on Paused succeeds. Resume
changes Paused to Playing; repeating it on Playing succeeds only when the
device/context is available. Both operations reject Ready, Stopped and Finished
with Invalid, and unloaded IDs with Missing. Resume never starts a new voice or
replays a stopped one. Play remains an explicit restart from the beginning.
Neither operation suspends the shared device/context or another owner.
Asset-music Status sets has_position only when position_seconds contains a
finite, nonnegative provider playhead in seconds, within the current loop
iteration (it wraps at the loop boundary). Paused time freezes. Browser time
also freezes during external context suspension, using AudioContext.currentTime;
Status then reports Suspended with its available frozen position. Resume while
suspended returns Suspended and queues nothing; retry explicitly after unlocking.
PCM and effects have has_position = false; zero seconds alone never indicates
support. PCM exposes neither a drained counter nor an estimated elapsed duration.
Paused PCM is not writable and rejects submission with Invalid, preserving the
same bounded queued copies until Resume; Stop and Unload clear those copies.
using Media :: #import "kryon/Media";
// Once, after verifying the capability/result:
loaded := MediaAudio(session, MediaAudioCommand.{.operation = .Load,
.voice = 1, .asset = "assets/my-game/chime.wav", .gain = .6})
if loaded.code == .Ok {
played := MediaAudio(session, MediaAudioCommand.{.operation = .Play, .voice = 1})
// Consume played.code in the application's audio policy.
}
CreateStream occupies one of the same 16 voices. Set format: MediaAudioFormat
to S16LE (signed little-endian 16-bit interleaved samples), sample_rate to
8000–48000 Hz, channels to 1 or 2, frames_per_block to 2048–8192, and
gain to a finite value in 0..1. These are the provider's supported bounds;
no other PCM formats are advertised. Creation accepts no samples. Play
starts an empty stream; repeating it clears pending samples. SubmitStream
uses pcm: string as binary bytes, including NULs, and requires exactly
frames_per_block * channels * 2 bytes (at most 32768). Samples are copied
before return; the guest retains no host pointer. Format/rate/channels are
fixed until Unload; submission uses the voice's creation settings.
Status returns writable: bool, true only for a running stream with room
for a complete block. SubmitStream returns Backpressure without accepting
any bytes when full; retry the same block later. Ok means the entire block
was copied. The provider holds at most two blocks in its existing stream
buffers; no application command queue is added. Stop clears queued samples,
Gain changes only that voice, and Unload frees the stream. Streams remain
Playing across frames and underruns, emitting silence while empty: they are
open-ended and do not claim Finished or a precise drained count. Asset voices
retain their existing completion semantics. Suspended/unavailable providers
reject creation, play and submission without queuing them for later autoplay;
after a trusted browser gesture the app must retry explicitly. Owner reset,
revocation, close and successful restart dispose streams with asset voices.
Wurm's synthesis, phrase scheduling, crossfades and game policy stay in Wurm;
its existing mono 22050 Hz / 2048-frame transport fits these bounds.
Only packed paths under assets/ pass: absolute paths, empty path components,
traversal, backslashes and schemes are refused before the host's existing
allowed-asset callback and packed reader. An asset is at most 8 MiB; there
are at most 16 loaded voices per owner and no command queue. Resource bytes
are copied/decoded into provider-owned storage; no native pointer or decoder
handle crosses the VM. The host reply codec uses named fields, and the VM
copies its strings before the host reuses the reply buffers.
HostedApp.audio stores the owner for the actual VM instance. The existing
AppContextCall dispatches audio only in an identified app's active widget
frame, validates its session and existing widget asset policy, and reads
only that runtime's packed resources. AppContextRun / AppContextRunFrame
service streams; audio commands disable quiet-frame replay so effects cannot
repeat as cached UI. HostedAppClose and successful HostedAppRestart
release all voices. Failed restart preserves the previous instance's audio.
Before changing an existing context's account/resource ownership, the host
must call AppContextAudioReset(app); it revokes in-flight decoding too.
Never use the outer Session alone as the resource owner.
A custom hosted widget host can supply its own instance's MediaAudioOwner
and packed reader as the final optional arguments to
WidgetHostBegin(session, allowed, resolve, audio, audio_read, audio_context).
The original arguments remain sufficient. Without an owner, audio returns
Unsupported. WidgetHostEnd clears dispatch only; music survives frames.
The custom host must call MediaAudioOwnerClose(owner) on actual disposal,
account/resource context changes and instance close. Keep the owner storage
alive until an in-flight synchronous host call returns; a browser decode may
yield. A revoked decode discards its temporary resource before returning.
Native app hosts can use MediaAudioBegin(owner, session, allowed, read, context) / MediaAudioEnd() around each callback, and
MediaAudioOwnerTick(owner) once per host frame while voices continue.
Binding a changed session or resource context closes previous voices;
close explicitly before replacing a reader or changing its policy in place.
closing an invalid session is also detected by the next tick. Owner close
is explicit and idempotent. Closing one owner never closes the shared device
or another owner's voices. Hosts can register a different actual provider
with MediaAudioUseProvider; existing owners retain their provider until
closed. The caller retains cue selection, score/synthesis, volume UI, mute,
phrase scheduling and any single-in-flight music transition policy.
kryon/media_audio_desktop's MediaAudioUseDesktop() installs the UI
provider over std/audio and std/audio_sink. The same provider works on
Android: the selected sink uses AAudio from API 26 and OpenSL ES for the
minSdk-21 scaffold. Device opening is asynchronous; voices and PCM blocks can
be queued during opening. A confirmed device failure returns Unavailable.
Kryon owns the UI commands and resource lifetime; audio works without a UI:
std/audiomixes voices into 48 kHz float32 stereo. It provides decoded clips, streaming music, signed PCM16 blocks, gain, pitch, looping, pause/resume, position, length, seeking and a mixed-output tap.std/audio_sinkselects SDL, Android or WebAudio.AudioSinkOpen()starts opening;AudioSinkPending(),AudioSinkReady()andAudioSinkUnavailable()report progress.AudioSinkClose()explicitly joins device teardown. SDL's disk driver supports deterministic tests.- Decoders register by import:
std/audio_decode_wav(PCM16, float32 and IMA/MS ADPCM),std/audio_decode_mp3andstd/audio_decode_vorbis. MP3 uses the coreziran_mp3archive; Vorbis links the core recipe'svorbisfile,vorbisandoggarchives.audio/decode_opusoptionally registers Ogg Opus decoding and links libopus. A custom decoder registersAudioUseDecoder(probe, open)with anAudioSource.
make desktop-audio-test exercises the mixer and UI provider through SDL's
disk driver. make android-audio-test ANDROID_SERIAL=ZE2223BQZT exercises
the same UI PCM provider, source and saved IR, on the USB Moto.
Document persistence
The existing kryon/app_context export provides DocumentStorageReady() -> bool
and DocumentFlush() -> bool, bound to app_context:DocumentStorageReadyHost
and app_context:DocumentFlushHost (both zero arguments, bool result).
AppLocal and the direct Canvas app host implement them. Other hosts must
explicitly grant and dispatch these capabilities; importing them grants no access.
Readiness is nonblocking: true requires an open private document namespace and,
in a browser, successful initial IndexedDB hydration. Before readiness, reads
report DOCUMENT_ERROR, writes and flush return false. The host opens storage
with AppFilesOpen after hydration; the guest does not initialize host storage.
DocumentWrite/WriteStore retain their queued browser semantics. A true write
result alone does not acknowledge persistence. After successful writes,
DocumentFlush returns true only when the backing store has acknowledged a
snapshot including those writes. It waits for any previous snapshot, then
requests and awaits a fresh one. Later writes remain in memory for a subsequent
flush; this operation neither clears a host's pending-write flag nor reloads
files from storage. Failure, unavailable storage, a 15-second browser deadline,
or namespace revocation returns false. False does not roll back queued bytes
or promise that an already running backend transaction has been cancelled.
The native provider syncs file bytes before atomic replacement and syncs parent directories after rename, including new ancestors. Platforms/filesystems that cannot sync directories reject that write rather than claim durability. The browser reuses IDBFS and Asyncify; its acknowledgement is the successful IDBFS transaction callback, subject to the browser's persistence/eviction policy. Atomic replacements have distinct mtimes even within one millisecond, as IDBFS uses mtimes to detect changes.
Hosts use AppFilesReady(files) and AppFilesFlush(files) for their authorized
AppFiles. The no-argument guest operation cannot name or read another node.
The browser backing store is the existing shared /kryon-apps mount: the host's
physical sync can include other queued namespaces, without exposing their paths,
bytes, handles, or authority to the guest. An AppFiles outside this mount can still stage packed assets, but reports
false for durable readiness and flush. Initial hydration is never restarted by flush.
Call on the owning thread. Browser flush yields; keep the owner and its AppFiles
alive until it returns and never reenter its running VM while suspended. Close
with AppFilesClose before changing account/resource ownership or rebinding the
namespace; close/open increments a generation, and an in-flight flush then
returns false even if its old snapshot succeeds. Do not overwrite live AppFiles
or mutate its root/lock directly. Readiness is availability, not an account grant.
make -j1 document-storage-test exercises native and actual disposable headless
IndexedDB storage, source/saved compilation and portable AppLocal dispatch.
Local notifications
kryon/notification_schedule schedules Android OS reminders independently of
push, network access, and the running app loop. DailyNotificationsSupported()
reports scheduler support independently of permission. Other native platforms
return false; portable apps use their authenticated host capability.
ScheduleDailyNotification(props, hour, minute=0, suppress_on_open=false, not_before_unix_ms=0, weekdays=127, skip_local_date=0)persists one rule. Weekday bits are Sunday=1 through Saturday=64. Times use the device's current timezone;not_before_unix_msis an absolute UTC lower bound.skip_local_dateexcludes one YYYYMMDD date, for example today's completion.ScheduleNotificationAt(props, year, month, day, hour, minute=0)schedules one local date; an elapsed date/time is rejected.ScheduleNotificationDates(props, dates, hour, minute=0)keeps one alarm for a caller-evaluated, finite sequence of at most 3660 strictly increasing valid YYYYMMDD dates. Apps own recurrence and refresh this explicit horizon.CancelDailyNotification(tag, id)cancels any of those rule types and its visible notification. Reusing(tag,id)replaces the rule.NotificationAppOpened(tag,id)durably marks that particular rule's local date and cancels its visible notice. Games call it on actual game entry, resume and local date changes while playing. A collection host must never mark its other games opened when the host foregrounds.
Scheduling persists even before permission is granted and never prompts.
Applications request permission through notification.RequestNotifications;
Kryon's Android host prompts once and preserves a refusal. System notification
settings remain authoritative. Failed scheduling returns false. Android's
inexact alarms can arrive later during idle; force-stopped applications cannot
receive alarms until relaunched. Reboot, clock, timezone and package-replacement
broadcasts rebuild future alarms from private preferences. Dates already opened
or delivered remain suppressed when the clock moves backward. Android allows at
most 480 active Kryon rules per host package and 64 per authenticated hosted app;
replacements do not consume another slot and cancellation frees it.
The Android scaffold declares the notification receiver, POST_NOTIFICATIONS
and RECEIVE_BOOT_COMPLETED permissions, and receiver actions.
Include android_notifications in the native graph so receiver exports survive
linking. notification_desktop dispatches immediate notification effects to the
Android implementation when ANDROID_BUILD is defined. Custom activities provide
requestKryonNotifications() using the scaffold's UI-thread callback.
In-app Toast.Props.seconds is independent: a toast's caller chooses display
length. OS notifications have no app-chosen toast deadline and remain subject
to Android's notification settings and user dismissal.
Compiled canvas host extensions
canvas_app_run.CanvasAppMainLoop(false) runs an AppContext app compiled into
its page. Bind canvas_app_run:CanvasAppMain=app:Main. Private documents retain
/kryon-apps/<app id> on IndexedDB. The bare runner supports mini mode only.
A host may install canvas_app_hooks.CanvasAppHooks with CanvasAppUseHooks
before entering the loop. Every callback is optional: start(mini) -> bool
runs once after persistent storage and the app's documents are open; pump()
runs before input each frame; stop() -> bool runs after a successful start, before
storage flush and teardown. A false stop result makes the loop fail after cleanup.
A failed start must clean up its own partial work.
supports(capability) and service(name, request) provide host-owned optional
services. An absent service returns the usual unavailable JSON response.
frame(session, bounds, key, modifiers, input) -> s32 runs inside the runner's
frame. Return 0 to run the app, 1 to replace its entire frame, or -1 to fail the
loop. Replacement frames exclusively receive input; the app callback is skipped,
including on the frame that closes an overlay. The host draws widgets but never
calls BeginFrame/EndFrame. Callbacks run on the frame thread. Account, payment,
authentication and application navigation policies belong to the embedding
package. A host decides which services it offers in mini mode.
Multi-select grid
GridMulti.Draw(session: Session, props: GridMulti.Props, items: []GridMulti.GridMultiItem, selected: []bool) -> GridMulti.GridMultiResult is exported by kryon/grid_multi.
Each borrowed item has key: u64, label: string and an
optional image: Image.Props. Import kryon/icon and kryon/image for
ImageForIcon(icon_type: s32, bounds: Rectangle, alt_text: string) -> Image.Props
and IconType. For example, assign
ImageForIcon(cast(s32)IconType.IconHome, Rectangle.{}, "Home") to an item's
image; the grid assigns its destination bounds. Ship the referenced icons/
atlases as ordinary application assets. Images use the ordinary Image renderer, including
assets, previews and session-owned textures. Bounds and child image keys are
assigned by the grid. Use unique nonzero item keys to retain identity across
reordering; zero falls back to the current index. Remap caller state when the
application reorders or replaces items.
Keep the mutable selection slice (exactly one bool per item), cursor,
anchor and scroll_offset between calls. Items, labels and image data are
borrowed for the call; normal Image asset/texture lifetimes still apply.
The grid never retains the selection slice. Mismatched storage returns
valid = false without changing selection. Empty matching slices are valid,
with cursor/anchor -1 and zero scroll. changed reports selection changes;
clicked_index reports every accepted pointer click, even when selection
is unchanged; keyboard selection never sets it. activated_index reports Enter;
ordinary pointer clicks and Space do not activate. Hosts currently expose no
canonical double-click activation signal; callers retain their pointer-click
action policy. Space only toggles selection. Missing actions use -1.
selected_count includes offscreen items. Keep application actions in the caller.
GridMulti.GridMultiLayout.GridMultiIcon (default) measures columns from available width,
places the image above the label, and scrolls vertically. Compact measures rows
from height, places a smaller image before the label, and scrolls horizontally.
Set cell_width, cell_height, image_size, gap, padding, scale, bounds,
a stable session-unique widget key (including across embedded host roots), and optional style class_name/focus id. Default logical
cells are 96 by 96 (Icon) and 180 by 32 (Compact). Partial cells and their image
and label children clip to the viewport. Set invisible = true to retain
selection, input, scrolling and accessibility while supplying native painting. Use the normal retained frame for image
clipping and pointer routing.
Supply edge/repeat decisions through navigation: GridMulti.GridMultiInput and modifiers
through control and shift; keyboard input requires focused and an enabled
grid. Icon Left/Right moves within a row, Up/Down by measured columns; Compact
Up/Down moves within a column, Left/Right by measured rows. Incomplete final
rows/columns clamp to their last item. Ctrl arrows move focus alone, Ctrl click
and Space toggle, Shift extends from the persistent anchor, and Ctrl+Shift adds
a range. Home/End select the first/last item with the same modifiers; Enter
selects and activates the cursor. Navigation, a newly focused cursor and viewport
resize reveal focus; ordinary frames retain manual scrolling. scroll_delta
adds caller movement, while the standard Scroll handles sampled wheel/drag input.
Disabled grids accept no input. Unfocused grids still accept pointer input.
AVIF compression and RGBA previews
The native image_preview module provides
ImageCompressAVIF(data: string, file_type: string, orientation: s32, quality: s32 = 35) -> ImageAVIFResult. On success, data owns actual AVIF
bytes and source_bytes/encoded_bytes support a real size comparison.
width/height are the full stored dimensions. Call ImageAVIFFree(*result)
when finished. Encoding does not resize or discard a larger result.
ImageAVIFEncodingAvailable() reports whether this host supports encoding.
Browser hosts return false, and compression returns UnsupportedCapability
without linking native codec archives. Browser RGBA previews remain available.
Accepted still 8-bit JPEG, PNG and WebP sources retain ICC, Exif and XMP when
the container metadata is supported; AVIF uses the headless package's direct
re-encode path. Alpha stays lossless. Animated, high-depth, gain-map and
unsupported color/metadata cases return an explicit shared DecodeError.
PNG compressed ICC and compressed text profiles currently return
UnsupportedCapability. A host that already baked a nonidentity orientation
must provide raw pixels before compression can preserve the stored orientation.
ImagePreviewRGBA(data, file_type, max_edge, orientation) returns owned upright
straight RGBA8 with pixels, width, height and stride. It uses Lanczos-3
and retains transparency. ImagePreviewRGBAPixels accepts already decoded
pixels with 1..4 channels. Call ImagePreviewRGBAFree(*result) to release the
output. These RGBA previews avoid temporary JPEG files and preserve transparent
edges for before/after comparison. Existing JPEG preview callers retain their
existing API.
Programmable scene materials
Import kryon/scene, kryon/scene_render and kryon/shader. RenderScene
executes camera-projected, depth-tested 3D meshes into a std/image.Image.
SceneCamera.shift_x and shift_y optionally offset a perspective view in
normalized device coordinates, with zero preserving the symmetric projection.
Positive X moves the scene right; positive Y moves it up. An offset of 1 moves
it by half the viewport width or height. Position, target, field of view and
aspect stay fixed, so this pans a bounded crop without rotating or translating
the camera. The CPU and GPU apply the offset before homogeneous frustum
clipping; render only the requested viewport. Orthographic bounds retain their
existing meaning and do not use these perspective offsets. Async GPU completion
metadata retains the exact submitted offsets with its camera.
The shader implementation is portable Ziran on CPU, including on Android and
WebAssembly. It does not compile GLSL or require a GPU shader context.
ShaderCompile(program: *ShaderProgram, code: []ShaderInstruction) -> ShaderDiagnostic validates and copies up to 128 instructions into owned,
bounded storage. ok, zero-based instruction (or -1 for program errors),
and static message describe failures. A rejected replacement preserves the
previous executable. Do not modify compiled storage directly.
ShaderFree(*program) invalidates it and is idempotent. Programs have no
external handles or allocations and survive presentation-context recreation.
ShaderProgram.input_mask records which initial inputs the validated code reads:
SHADER_INPUT_COLOR, SHADER_INPUT_POSITION, SHADER_INPUT_NORMAL and
SHADER_INPUT_UV. Reads after overwriting an input register do not require
that initial value. The renderer uses this metadata to avoid normalizing
unused shader normals; UV-only albedo programs retain identical output.
Each instruction has op, dest, a, b, c, slot and value.
Registers hold ShaderValue.{x,y,z,w:float64}. Registers 0–3 initially contain
linear base RGBA, world XYZ/1, world-normal XYZ/0, and UV/0/0. The renderer
perspective-correctly interpolates these values. Registers 4–31 start undefined;
validation rejects reads before writes and invalid destinations. Operations are
ShaderLiteral, ShaderUniform, ShaderSample, ShaderMove, ShaderAdd,
ShaderSubtract, ShaderMultiply, ShaderDivide, ShaderMin, ShaderMax,
ShaderSin, ShaderCos, ShaderFract, ShaderDot, ShaderNormalize,
ShaderMix, ShaderDiscardLess, and ShaderOutput (members of ShaderOp).
Arithmetic is component-wise; dot and normalization use XYZ; dot broadcasts its
result and normalization preserves W for nonzero XYZ (zero XYZ returns zero
RGBA). Mix uses A, B and C per component.
Divide by zero returns zero. DiscardLess discards when A.x < B.x. Output takes
A and must end the program. Nonfinite outputs discard. No unbounded loops.
Set SceneMaterial.shader to the program address, shader_uniforms to a
borrowed slice of up to 16 vec4 slots, and shader_samplers to borrowed slots
(up to 8). Owners must remain alive and unchanged during RenderScene;
values and pixel contents can change between renders without recompilation.
ShaderBindings reports missing slots, released programs, nonfinite uniforms
and invalid RGBA dimensions. RenderScene rejects invalid bindings before
drawing. SceneFree never frees borrowed programs, uniforms or sampler pixels.
ShaderPrepare(*prepared, program, uniforms, samplers) validates bindings once
and produces a bounded ShaderPrepared draw plan with folded constants and
unused instructions removed. Reprepare after changing the program, uniforms,
sampler bindings or sampled pixels. The plan owns its instructions/constants
and borrows sampler storage for the draw. Its input_mask describes the initial
inputs still needed after preparation.
ShaderRunPrepared(*prepared, *scratch, inputs) executes one pixel with exact
interpreter arithmetic. ShaderRunBatch(*prepared, *scratch, inputs, outputs)
executes up to SHADER_BATCH (32) pixels per instruction dispatch and returns
false for an unprepared plan, oversized input or insufficient output storage.
Use ShaderScratch for scalar execution and ShaderBatchScratch for batches;
each concurrent caller owns separate scratch. Programs, bindings and samplers
remain unchanged during execution. RenderScene prepares per mesh each frame
and batches its pixel shader calls, preserving changes between frames.
ShaderSampler.{width,height,pixels,repeat} samples straight linear RGBA bytes,
top row first. UV V=0 selects the bottom row. Sampling uses nearest-neighbor
clamp-to-edge by default, or repeat including negative coordinates. Supply
linear data when loading an sRGB image for a custom sampler. ImageMaterial
is the standard sRGB image path described below.
Shader output replaces base RGBA before standard lighting and tone mapping.
Use UnlitMaterial for direct colour, or LitMaterial for procedural surfaces
that keep scene lighting. Set transparent=true for fractional alpha;
alpha_test also applies to shader output. Discarded and zero-alpha fragments
write neither colour nor depth. Shadow maps still use mesh geometry; custom
shader discard does not cut holes in shadow casters.
The renderer clips triangles against all six homogeneous camera planes,
preserving attributes when triangles cross the eye or near plane.
Present its straight sRGB output with BitmapImageCreate/BitmapImageUpdate
and the standard Image widget; widget clipping and alpha remain in effect.
RenderSceneRelease() releases shared scratch buffers, recreated on the next
render. Render and release on one owning thread; this renderer is not reentrant.
Native builds with POSIX_THREADS prepare immutable mesh states and clipped
triangle commands once per frame, then render through std/parallel_linux.
The pool defaults to one lane per online logical processor, up to 64 lanes.
Set ZIRAN_PAR_THREADS to select a lane count. A value of 1 runs serially.
Each lane clears, draws and resolves its own full pixel rows in the original
opaque and sorted transparent order. One completion barrier joins the frame.
Conservative row bounds skip empty triangle regions while retaining the
original edge equations at all four sample positions.
Soft-shadow disk radii are initialized once. Each lane memoizes exact disk
rotations in a 512-entry cache for its frame; the light's radius and depth
comparisons are still evaluated per fragment. This uses about 44 KiB of
temporary stack per lane, without a full-frame cache or changed shadow samples.
RenderSceneWorkerCount() reports available pool lanes, including the caller;
it returns one before initialization and after RenderSceneRelease(), which
also closes the pool. Small draws and thread-creation failure remain serial.
Portable bundles and WebAssembly builds without this capability remain serial.
Borrowed programs, uniform values and sampler pixels must remain immutable
until RenderScene returns on the owning thread.
For expensive opaque materials with more than two projected surface layers, the renderer first tests depth and material discard without lighting. It then shades only candidates near the final opaque depth, preserving the original draw order, float32 depth comparisons and four coverage samples. Conservative depth ceilings temporarily reuse the existing sample color bytes; this adds no frame-sized buffer. Empty samples regain the scene background before the original sorted transparent pass. Low-overlap scenes retain the single pass. Programs and alpha textures still run during visibility testing, so savings depend on overlap and lighting cost.
RenderSceneStatistics() returns the last completed render's
opaque_projected_layers (summed clipped opaque triangle area divided by image
area), depth_prepass, depth_fragments and shaded_fragments. Fragment counts
are pixel-center material evaluations after coverage and depth testing, shared
by covered MSAA samples; they include evaluations that discard. The depth count
belongs to the optional visibility pass, and the shaded count includes opaque
and transparent color passes. Lanes accumulate private counts before joining.
Release resets the snapshot.
RenderSceneMemoryBytes() reports retained backing-buffer bytes for renderer
scratch, including transformed vertices and prepared draw commands. It excludes
the caller's scene, textures and output image, static color tables, allocator
overhead and worker stacks; it is not process RSS. Color and depth buffers grow
without geometric spare capacity. Sized buffers retain capacity across renders
and all reported scratch is freed by RenderSceneRelease().
RenderSceneMemoryUsage() returns the same backing storage split into
framebuffer_bytes, shadow_bytes, vertex_bytes, triangle_bytes,
draw_bytes, node_bytes and ordering_bytes. These fields sum to
RenderSceneMemoryBytes(). Triangle commands refer to shared draw states and
do not copy material bindings. The four coverage positions are shared constants,
not stored in each command. Geometry reservation allows one eighth of source
size plus 32 records for clipping; additional growth uses the same bounded
headroom. Camera frames within retained capacities allocate no geometry storage.
Transparent depth-sort keys also retain capacity across frames and are included
in ordering_bytes.
Render at a bounded resolution and reuse the image while camera, geometry, lights and material inputs remain unchanged. CPU rendering every UI frame at full window resolution can be expensive.
tests/shader_scene_test.zi demonstrates mutable uniforms, sampling,
diagnostics, clipping, alpha and recreation. Focused targets are
make shader-scene-test and make shader-host-test, through build-queue --.
Renderer performance benchmark
Run build-queue -- python3 tests/scene_render_benchmark.py --output PATH
on Linux. The benchmark enables POSIX_THREADS; ZIRAN_PAR_THREADS=1 selects
the same renderer serially. CC can select a compiler wrapper. The benchmark
retains four MSAA samples per pixel and the complete 960x600 and 420x900 output. It measures
clear/resolve, unlit meshes, textured meshes, a 12-instruction programmable
material, and standard lit meshes. The texture is 1024x1024; the scene has a
wall and four rounded boxes. Each workload warms once, then measures three
camera positions. Geometry construction and full-frame hashing are outside
the timed region. Rows contain width, height, workload, frame, wall nanoseconds,
process CPU nanoseconds and an RGBA pixel hash. CPU time separates rendering
work from scheduling delays; it does not predict an application's frame rate.
Use --compare PATH with an earlier output to require all 30 pixel hashes to
match and report median speed ratios. Add --motion for 120 changing-camera
frames per workload at 960x600, 420x900 and 1280x800. It reports p50/p95/p99,
the count within the 16.67 ms budget, cold render time, retained scratch and
sampled process peak RSS/HWM; it also checks all 1,800 motion hashes when the
comparison contains them. Every sample is retained, including slow frames.
--shadows instead adds 120 motion frames at each resolution for a lit
programmable material, a 1024-square shadow map and the unchanged five-tap
soft-shadow disk. Compare against an earlier --shadows output to check all
360 shadow hashes. The original 30 reference frames still run in this mode.
--overdraw instead adds 16 opaque lit programmable planes, with 12 changing
camera frames at each resolution after warming that camera path's clipping
capacity. Compare against an earlier --overdraw output to check all 36 motion
hashes. Statistics rows record the final frame's projected layers, visibility
pass choice and material evaluation counts.
The benchmark checks fixed scratch capacity during these camera motions and
zero scratch after release. It measures rendering only: presentation, image
uploads and application geometry/state updates require application profiling.
These are local tests, not GPU timings or application frame-rate claims.
The renderer reuses sized scratch buffers, converts fragment output once for its covered samples, and caches the exact byte-to-linear transfer. The output lookup searches thresholds generated from the original transfer and rounding; it does not reduce color precision. Shader vector arithmetic dispatches once per instruction. These changes retain clipping, blending, depth and sampling behavior; the shader regression renders both sides of every output-byte edge.
Portable GLSL translation and optional native GPU rendering
kryon/shader_glsl translates the same ShaderProgram into a GLSL ES material
function. ShaderGLSLTranslate(program) returns ShaderGLSLResult with a
diagnostic, owned source text, and uniform/sampler counts and input mask.
Check diagnostic.ok before composing its kryonMaterial function into a host
shader. ShaderGLSLBindings validates the borrowed values for GPU execution.
Translation is portable Ziran; it does not create a graphics context. GPU
highp arithmetic has different precision from the CPU's binary64 arithmetic,
so GPU comparisons use documented pixel tolerances rather than exact hashes.
Native desktop applications can explicitly import kryon/scene_gpu and link
-lEGL -lGLESv2 -lGLX -lm. This optional host is separate from the core UI, portable
CPU renderer and WebAssembly path. It owns a surfaceless EGL/GLES3 context and
renders the existing Scene, materials and SceneCamera into a reusable
std/image.Image for ordinary Kryon Image presentation. A web build (OS == .WEB) links none of EGL or GL: SceneGpuProbe reports the GPU unavailable,
and SceneGpuRenderOrCPU draws with RenderScene.
Android code generation defines ANDROID_BUILD and uses the default EGL display
through eglGetDisplay, including at API 21. kryon_android_app supplies the
EGL and GLESv3 system libraries; the Android path has no GLX imports.
Keep one SceneGpuContext at a stable address on its owning thread.
SceneGpuProbe(context) reports availability, diagnostic, renderer labels,
texture limits and MSAA support. The host requires highp fragment precision,
15 texture units and four MSAA samples; it reports unavailability when those
requirements cannot be met. pcf_available reports hardware bilinear depth
comparison. When the probe fails, the GPU fragment shader performs the four
depth comparisons and bilinear interpolation at each of the five shadow taps.
SceneGpuRender(context, scene, camera, image) preserves the requested image
dimensions and returns SceneGpuFrame with ok, accelerated, diagnostic
and submission/readback/conversion timings. Failure leaves the output untouched.
SceneGpuRenderOrCPU explicitly permits the full-quality CPU renderer on
failure, setting accelerated=false; inspect that flag when measuring GPU work.
SceneGpuSetProfiling(context, true) adds stage timings in frame.profile.
shader_setup_ms covers material program lookup, binding validation and shader
setup. texture_upload_ms measures the driver calls that upload scene textures.
For synchronous readback, gpu_completion_ms measures the explicit finish
before pixel_transfer_ms measures the read. For async readback it measures
the elapsed time from fence submission until a poll first sees it ready, so it
includes polling delay. image_copy_ms measures publication to the owning
Image, including any required pixel conversion. Profiling is off by default.
direct_resolve identifies a frame that skipped the conversion draw.
SceneGpuCapabilities.async_available separately probes pixel pack buffer
readback, fences and read mapping. async_diagnostic explains unavailability;
the synchronous GPU API remains available when only async support is missing.
SceneGpuSubmit(context, scene, camera, width, height, request_id) draws at
full quality into one of exactly two retained transfer slots. Use positive,
strictly increasing IDs until release. SceneGpuAsyncResult.ok means the
operation is valid: queued accepts the request, busy accepts nothing.
Scene, shader and texture storage is borrowed only during submission and can
be mutated afterward on the owner thread.
SceneGpuPoll(context, image) tests the oldest fence with timeout zero.
An empty/unready poll has ok=true, completed=false and leaves the image
untouched. A completion returns the exact submitted ID, camera, size, original
draw timings and submission-to-completion latency_ms; it never labels pending
work as the latest camera. The image must already have the completed size.
Poll copies only a signaled buffer, validates its read mapping and then updates
the reusable Image. One CPU staging buffer is shared with synchronous readback.
Synchronous render can safely interleave while both transfer slots are pending.
Async queues add at most 2 * width * height * 4 bytes of GPU transfer storage.
On ARMv7 PowerVR Rogue GE8320, each pending opaque frame owns the resolved
framebuffer until its fence signals. The renderer reads it directly and copies
the rows into the Image in top-to-bottom order. Translucent frames still use
straight-alpha conversion. The Android Pixmap presenter takes the same CPU
Image pixels in both cases.
SceneGpuCancel discards pending IDs and releases the transfer slots. Resize,
release and context loss also discard them. Cancellation/resize/release may
drain GPU work; poll does not wait for unfinished work. Applications must keep
polling while work is pending, including after input stops, and retain the
completed camera metadata separately from current input. Queueing may add
camera latency, so measure changed presented frames and event-to-pixel latency.
The native Desktop host exposes DesktopRequestFrame() for this purpose.
Requests aggregate until the next BeginDesktopFrame, keep the active frame
budget while pending, and affect only scheduling. Continue to pass the actual
retained-paint result to DesktopFrameUnchanged; scheduling work must never
claim that unchanged image pixels changed.
Geometry, material programs, textures and render targets retain storage across
frames. Each context also keeps up to eight linked material programs from
earlier frames. Scenes with identical shader instructions and material features
reuse the linked program. Scene and binding data are borrowed during the call.
Mutate them only on the owner between calls. When only nodes move, turn or
scale between frames, the renderer sends the affected vertices. Smooth-shaded
indexed meshes keep their element buffers and refresh only changed position, normal and color
streams. Box-projected UVs update with their source positions and normals.
Topology, material and visibility changes rebuild the geometry. SceneGpuResources.geometry_uploads
counts uploads and geometry_vertices counts the vertices those uploads covered.
FreezeGeometry(scene) (in kryon/scene) promises that meshes, materials and
vertices stay as they are, so the renderer stops comparing them with its last
upload on every frame and compares only the nodes. Scene calls that add or
change geometry take the promise back; after writing into the scene's vertex
arrays directly, clear scene.geometry_frozen yourself. SceneGpuMemoryUsage reports retained CPU/GPU
storage estimates, object counts, upload counts and completed GPU frames; this
is separate from process RSS and presentation-host storage.
The resource report includes live fences/pending frames, accepted submissions
and cancelled requests. Deleting a live slot drains it before releasing storage,
so repeated navigation cannot accumulate deferred transfer allocations.
SceneGpuResize resizes the retained target. SceneGpuRelease releases owned
objects and context and can be called repeatedly; a later probe/render recreates
them. It preserves a foreign host's current graphics context and does not
terminate the process-shared EGL display.
Run the explicit native targets make shader-glsl-test and
make scene-gpu-test through build-queue --. The ordinary public-surface
local tests also compile and execute scene, material and translator imports as
a separate package consumer in native and portable forms without linking EGL.
Run build-queue -- python3 tests/scene_gpu_test.py --readback-profile to
compare the two synchronous copy paths on a 2527×1423 opaque frame and verify
their pixel hashes. The reported renderer identifies whether the run used a
hardware or software GLES driver.
Owned image pixels for scene textures
#import "kryon/image_pixels" exposes
LoadImagePixels(path: string) -> std/image.Image. Success satisfies
ImageValid(*image); missing, invalid or unsupported files return an empty image.
The caller owns image.pixels and releases it with VecFree(image.pixels).
Pixels are tightly packed, top-down, straight RGBA in the source's sRGB encoding.
On the web the page decodes the file's bytes with the browser's own codecs
(photos turned upright by Exif), so a canvas build links no image library.
Headless image-widget tests can use the ordinary kryon/pixmap provider for
image_raster's ImageWidth and ImageHeight capabilities. Import both modules
and bind image_raster:ImageWidth=pixmap:ImageWidth and
image_raster:ImageHeight=pixmap:ImageHeight with --bind when compiling source
or generating saved IR. For a package consumer, prefix both module names
with Kryon's package ID from ziran.lock and an underscore, for example
p…_image_raster:ImageWidth=p…_pixmap:ImageWidth; the ID depends on the locked
revision. Saved IR already contains those bindings. PixmapSetImage registers
fixture dimensions; absent paths return 0. This needs no window or borrowed
framebuffer. A desktop application uses the same capabilities from
kryon/Cairo, which loads its picture assets.
Android frames owned by the application
kryon/android_runtime hosts applications with their own main loop. Select it
as the Android host when generating native sources. PollAndroidHost(timeout_ms)
drains lifecycle and input events and returns false only on destruction;
a missing window, pause or lost focus does not end the loop. Query
AndroidHostPaused(), AndroidHostFocused() and AndroidHostViewport() before
composing. BeginAndroidFrame() borrows the NativeActivity surface for Pixmap;
EndAndroidFrame() presents its device-pixel damage. The app owns its widgets,
state and pacing. Resizing, density, insets, redraw and surface replacement
invalidate retained pixels; an unchanged frame skips presentation.
After polling, call SetAndroidPausedSurfaceVisible(visible) if the operating
system reports that a floating window such as picture-in-picture is visible.
This permits drawing on a live surface during an activity pause while
preserving the usual pause and focus reports.
Pixmap's RasterSetTransform(scale, offset_x, offset_y) and
RasterPointFromPixels(point) use the same camera for painting and input.
The inverse takes physical pixels, including a negative logical origin. The
held camera survives frame borrows and surface resize. Device damage is
already scaled and must not be scaled again by the presenter.
kryon/pixmap_assets_android adds owned decoded pictures. A picture the
application ships decodes from its APK assets the first time Pixmap measures
or draws its path; a missing asset is looked up once, until invalidation or
host cleanup. The Android Frame host imports it, and an application that owns
its loop imports it to show pictures.
PixmapLoadImageBytes(path, data, file_type) replaces a registered Pixmap
picture only after a successful bounded decode. Preview decoding returns owned,
upright straight RGBA through the ordinary image-preview capabilities.
Path, folder and full image invalidation share the raster-cache API; replacing
or closing owned entries releases their pixels and sampling cache. A borrowed
picture installed with PixmapSetImage remains borrowed.
kryon/pixmap_typefaces_android provides the ordinary typeface_source
capabilities: register a font file, borrowed font bytes or the system face,
then select its registered name. Bind those capabilities to this provider.
Selection installs Pixmap's optional text rasterizer; the default Pixmap font
needs no Android font service. Android Paint shapes and measures the same run
that Canvas rasterizes into coverage for Pixmap's camera, clipping, rotation
and alpha composition. The line box is the requested font size, matching the
desktop layout contract. System font lookup uses system_typeface_android,
and Android supplies script fallback for the selected face. Clearing faces
restores the built-in Pixmap font. CPU discard clears raster masks while
retaining registered faces; host teardown releases owned references and masks.
Text as pixels
#import "kryon/text_pixels" exposes TextPixels(value, font, color, width, height, pixels) -> bool: the host's own text raster letters VALUE at FONT
size in COLOR, centred on a transparent WIDTH by HEIGHT picture of straight
RGBA in PIXELS (at least WIDTH * HEIGHT * 4 bytes), shaped exactly as its text
on screen. Use it where text must become a texture, such as lettering on a 3D
surface. The desktop letters with Cairo and Pango (RasterTextPixels), the
web with the page's canvas in its text face; it is false before the desktop
raster exists and on Android.
Use the single public scene-image surface:
wood := LoadImagePixels("assets/wood.png")
options: SceneTextureOptions = .{
projection=.SceneTextureBox,
filter=.SceneTextureLinear,
wrap=.SceneTextureRepeat,
scale=.{3.0,3.0},
}
material := ImageMaterial(*scene, *wood,
LitMaterial(.{255,255,255,255}, 0.72, 0.0), options)
VecFree(wood.pixels)
unused RoundedBox(*scene, 1.8, 0.08, 0.32, 0.01, material)
ImageMaterial(scene, image, base, options) -> SceneMaterial validates and
copies a complete std/image.Image; the source can be freed immediately.
Equal images, including equal explicitly prepared mip levels, share one owned
scene texture. The scene releases logical storage in SceneClear/SceneFree.
Native GPU contexts upload the immutable copy once, reuse it without scanning
the image every frame, and release/recreate the upload with context lifecycle.
SceneTextureOptions contains projection, filter, wrap, scale, offset
and mip_level. Projection is SceneTextureUV or SceneTextureBox; box mapping
chooses a face from the dominant object-space normal, so moving, rotating or
scaling a bookshelf part does not make its grain swim. Filtering is
SceneTextureNearest or SceneTextureLinear, and wrapping is
SceneTextureClamp or SceneTextureRepeat. A zero scale component defaults to
mip_levelis an explicit nonnegative level prepared once with a box filter; its fixed selection makes native CPU and GPU results deterministic. Both renderers filter sRGB texels in linear light and use the same clamp/repeat and top-row/V-bottom rules.SceneTextureCoordinateexposes the exact object-space coordinate transform for procedural geometry and tests.
ImageMaterial attaches scene textures. Shader samplers use programmable
linear-RGBA values; convert sRGB first when using those bindings.
Light cookies
LightCookie(scene, light, texture, scale, offset) projects a scene texture
through a light's beam, like a gobo: dappled sun through leaves, window bars or
stained glass. texture is an existing scene texture index, usually
ImageMaterial(...).texture. The texel's linear RGB multiplies the light's
direct irradiance on every lit surface, receiver or not; the hemisphere light,
unlit and exact-colour materials are unaffected. The texture spans the light's
shadow box from CastLightShadow scale times, shifted by offset (in
repetitions), with bilinear filtering and repeat wrapping in linear light, so
the CPU and GPU renderers agree. A light needs a shadow box to carry a cookie;
shadow_size may be zero when no depth map is wanted. Only the first light
with a cookie projects one. Change SceneLight.cookie_offset between renders
to drift the pattern without rebuilding anything.
Scene grade: a time-of-day look for pictures
Scene.grade (SceneGrade) lights scenes made of painted pictures, whose
unlit and exact-colour materials ignore scene lights and cookies. Every
material without SceneMaterial.ungraded keeps its colour C as
(grey + (C - grey) * saturation) * tint, plus C times the light of up to
four lamps (SceneGradeLamp: position, radius, sRGB colour, strength,
falling off as 1/(1+(d/radius)²)²) and one beam (SceneGradeBeam): light
through an elliptical opening such as a round window. A surface point is in
the beam when the ray from it along direction crosses the ellipse centre
plus half axes axis_u and axis_v; softness fades the edge over that
fraction of the radius. Lit materials are graded after lighting. The grade
beam can receive real cast shadows: set beam.shadows = true and
beam.shadow_light to a directional light's index, configure its depth map
with CastLightShadow, and align the light's position/target with the beam's
direction. Nodes opt into casting and receiving with SetShadows. Only the
direct beam is occluded; ambient tint and local lamp light stay readable.
An absent shadow light leaves the beam unoccluded. This also works on unlit
painted surfaces, in both CPU and GPU rendering. Shadow maps respect material
opacity and texture alpha/cutoff, so foliage cards cast their painted
silhouettes instead of solid rectangles. SetVisible only affects the camera;
hidden nodes still cast shadows when enabled with SetShadows.
The grade applies before tone mapping. It is disabled by default; SceneGradeNeutral()
is enabled with white tint and saturation 1, leaving every colour exactly as
it was, and the renderers skip such a grade entirely, so a neutral hour costs
nothing per pixel. Change it between renders: it never rebuilds geometry and keeps
FreezeGeometry's promise. The CPU and GPU renderers prepare it identically
(PrepareGrade) and agree within the GPU tolerance (make scene-gpu-test).
Mark skies and lamp glows ungraded so they keep their own colours.
Daylight: sun, sky and grade by the hour
Import kryon/daylight. DaylightAt(hour, latitude = -25.0) (local solar
hours, wrapped to 0..24) returns DaylightState: the sun's direction for a
north-facing view (rising at 06:00 on +x/east, setting at 18:00 on -x/west,
north beyond the scene on -z), its height, day/full/golden weights,
linear sky colours, the sRGB grade tint and saturation, and 0..1 weights for
lamps (dusk to dawn), beam (sunlight throughout the day) and stars. The
path uses equinox declination and fixed 06:00/18:00 dawn/dusk, rather than
date/location-specific ephemerides. Negative latitude places the noon sun
in the northern sky; positive latitude places it south. DaylightBeam
admits light only from the outward side of the opening (the cross product
of its axes faces indoors), fading grazing rays. While
the sun is high (full == 1) the tint is exactly white and the saturation
exactly 1, so pictures keep their painted colours. DaylightGrade(state)
turns it into a SceneGrade; the app adds its lamps and beam, scaled by
state.lamps and state.beam. The app owns the clock, so it can follow the
local time or let a debug build set, fast-forward or rewind the hour.
DaylightSky is a storybook sky drawn by one material shader: a gradient from
horizon to zenith, the sun's glow and disc, two drifting cloud layers and
twinkling stars, from a 256-pixel tileable noise texture made in code at
DaylightSkyInit (no image files). Each frame call
DaylightSkyUpdate(sky, state, seconds, aspect, horizon) with the plane's
width over height and the horizon's height (0..1) on it; seconds drive the
clouds and stars. Draw it on a plane whose UV runs left to right and bottom to
top with DaylightSkyMaterial(*sky.program, sky.uniforms[:], sky.samplers[:])
(unlit, exact colour, ungraded); keep the sky at a stable address while it is
drawn and release it with DaylightSkyFree. tests/daylight_test.zi covers
the hours, the sky and the grade on native and portable builds (make daylight-test).
Linux uses the existing system image loader and packaged WebP/AVIF adapters,
copying the original straight pixels before Cairo premultiplies them. Android reads relative APK asset paths
through the current NativeActivity's asset manager, or absolute filesystem
paths. It decodes PNG, WebP and AVIF in process with the linked codecs, on every
supported API level. Other formats, such as JPEG with its orientation, need the
activity's decodeBundleImage(byte[]) method: it returns width, height and
then ARGB_8888 pixels, or null, and the droid template provides it. Without
it those formats fail empty and Kryon logs once that the method is missing.
Unsupported formats fail empty; this API does not promise WebAssembly AVIF
support.
These are CPU images and survive presentation context teardown.
make image-pixels-test verifies exact RGBA/alpha ownership and invalid inputs.
make shader-host-test, make shader-web-test and the explicit hardware target
make shader-android-test additionally execute the loader in their real hosts.
The Android console test covers absolute PNG files and the real offscreen native
window. make android-pictures-device-test decodes AVIF textures and checks the
missing bridge inside Android's VM on the USB Moto.
Custom native and Canvas hosts can import kryon/window_runtime for
BeginWindowFrame, ClearWindowFrame(color) and EndWindowFrame.
CloseNativeWindow, WindowHidden, WindowMinimized and WindowClosing
retain the backend's existing window semantics. These observations do not
poll input, change focus, pause work, or decide whether closing hides or quits.
Applications using retained frames keep their retained presentation lifecycle.
WindowWidth and WindowHeight report the custom desktop host's drawing
surface or Android's current native pixel extent. Desktop frames use the same
SDL/Cairo window opened by Desktop.OpenDesktopSized; resize takes effect at
BeginWindowFrame. Clearing replaces the whole Cairo surface, including alpha,
while preserving the caller's clip for subsequent drawing. Android frames lock,
paint and post NativeActivity pixels directly, and pause while the activity is
paused or has no window. SyncWindowSurface refreshes Android's shared surface
and touch transform. Closing requests activity shutdown, drains its lifecycle
commands, then frees its native pixels. Canvas keeps its page lifecycle.
Custom hosts import kryon/window_icon for
SetWindowIcon(encoded: string, file_type: string) -> bool. Encoded bytes
are borrowed for the call; native hosts decode through their shared image
codecs, apply JPEG orientation, and preserve full dimensions and straight
alpha. The native window must already exist. False means invalid or
unsupported data, a missing SDL window, or a browser/Android host where the
application icon belongs to the page or package manifest. Native AVIF uses the shared codec libraries.
Desktop image services include RasterInvalidateImage(path) -> bool,
RasterInvalidateImagesIn(folder) -> s32, and RasterInvalidateImages() -> s32.
They remove cached file pictures and their pending smooth copies; folder matching
respects path boundaries. Counts report entries removed. ImagePreviewDecode
uses the desktop image decoder's bounded, oriented RGBA output; release its
pixels with ImagePreviewRelease.
FramePreviousSnapshot() -> FrameSurface captures an owned copy of the previous
frame on desktop and Android. Call it after composing a new route and before
painting, draw it with FrameTransition using the full logical frame bounds
(including a negative camera origin), and call FrameSurfaceRelease when the
transition ends or is canceled. FrameSurfaceCopy owns an independent copy.
The Web host returns an invalid surface, so callers skip the fade there.
Indexed animated surfaces and watercolor
Import kryon/scene_skin for SceneIndexedMesh, SceneSkinCreate,
SceneSkinDeform and SceneSkinRelease. Indexed surfaces copy positions,
normals, UVs and triangle indices into their owning Scene. A SceneSkin
retains bind positions and four normalized joint weights per vertex. Supply
final bind-to-pose SkinAffine transforms; deformation always starts from
bind data and uses inverse-transpose normal transforms, including nonuniform
scale. Invalid indices, weights and singular transforms are rejected before
changing visible geometry. Release the skin before reusing or freeing its
scene. Bone animation and inverse kinematics belong to the caller.
Import kryon/watercolor for WatercolorMaterialCompile and
WatercolorFinish. The portable material samples real paper and pigment
RGBA bitmaps and supplies soft directional light and a Fresnel rim. Uniform
0 is UV repetition, 1 light direction, 2 view direction, and 3 rim RGB with
zero W; samplers 0 and 1 are repeated linear paper and pigment images. Keep
the program, uniforms and images alive while rendering. Use an unlit scene
material when this program supplies the final lighting. The finishing pass
uses caller-owned retained scratch, brush radius 0–2, and brush, grain,
edge, pooling and contour strengths 0–1. Pooling darkens pigment within two
pixels of the silhouette; contour draws a graphite pencil line on the
silhouette and where neighbouring washes differ. It preserves source alpha
and excludes transparent samples from pigment filtering. CPU and translated GLSL share the material;
no window or platform graphics dependency is required.
Desktop LoadImagePixels accepts the host's optional
ImagePixelsUsePathResolver callback, so the same loader can read bundled
assets and disk files. A resolver borrows its input path and an output buffer
and returns a retained file path (or empty to keep the original). Loading and
resolver registration belong to one owner thread; the host retains resolved
files until decoding finishes. ImagePixelsClearPathResolver restores disk loading.
The image loader does not import a raster backend or open a window.
glTF 2.0 models
Import kryon/scene_gltf to load .gltf (JSON with .bin or data: URI
buffers) and .glb files without any platform graphics dependency:
#import "kryon/scene"
#import "kryon/scene_gltf"
#import "kryon/scene_skin"
#import "kryon/scene_render"
model := GltfReadFile("models/character.glb")
defer GltfModelRelease(*model)
if !model.valid { return }
scene: Scene
SceneInit(*scene)
instance: GltfSceneInstance
defer { GltfInstanceRelease(*instance); SceneFree(*scene) }
if !GltfSceneCreate(*scene, *model, *instance) { return }
if model.animations.count > 0 {
unused GltfAnimateScene(*model, *instance, *scene, 0, seconds)
}
camera := PerspectiveCamera(0.9, 16.0 / 9.0, 0.1, 100.0)
picture := NewImage(width, height)
defer VecFree(picture.pixels)
unused RenderScene(*scene, camera, *picture)
GltfReadBytes(bytes, base_dir) reads the same formats from memory;
base_dir resolves relative buffer and image URIs, and stays empty for a GLB
whose binary chunk holds everything. A loaded GltfModel owns its buffers,
decoded images, materials, meshes, nodes, skins and animation samplers;
GltfModelRelease frees them.
The reader covers buffers, bufferViews and accessors for every component type,
normalized integers and sparse overrides. Primitives read POSITION, NORMAL
(averaged flat normals when absent), TANGENT, TEXCOORD_0, TEXCOORD_1,
COLOR_0, JOINTS_0, WEIGHTS_0 and indices; triangle lists, strips and fans
are supported. Meshes read morph targets and default weights. Nodes read TRS or
a column-major matrix, children, meshes, skins and per-node morph weights.
Skins read joints and inverse bind matrices. Animations read translation,
rotation, scale and weights channels with LINEAR, STEP and CUBICSPLINE
interpolation and report their duration. Materials read
metallic-roughness factors, base colour, metallic-roughness, normal, occlusion
and emissive texture info, alpha modes, double-sided, KHR_materials_unlit,
samplers, textures and PNG/JPEG images from a URI, a data: URI or a
bufferView.
Malformed input never crashes: every accessor and sparse range is
bounds-checked, required arrays are type-checked, node hierarchies reject
cycles and multiple parents, and relative URIs must stay inside the model's
directory. A rejected document leaves model.valid false and GltfError
describes the first problem. Documents above 256 MiB, accessor counts above
16 million, non-triangle primitive modes, non-finite floats and required
extensions other than KHR_materials_unlit are rejected.
GltfSceneCreate(scene, model, instance, scene_index = -1) builds one
SceneIndexedMesh per primitive under group nodes for the document's node
hierarchy and creates a SceneSkin for every skinned primitive; skinned
primitives draw through the same retained indexed path as other scene meshes.
GltfUpdateScene recomputes node world transforms, morph blending and skin
poses. GltfAnimateScene(model, instance, scene, animation, time, loop = true)
samples an animation and updates the scene in one call; loop wraps time
modulo the animation duration, and a non-looping sample clamps to the last
keyframe. GltfSampleAnimation changes only the instance, GltfSampleSkinPose
returns the current bind-to-pose SkinAffine array for one skin, and
GltfSetDualQuaternion switches skinned primitives to volume-preserving dual
quaternion skinning. GltfPoseReset returns to the document's rest pose.
Material conversion maps base colour, metallic, roughness, emissive, alpha
mask/blend, double-sided and unlit into SceneMaterial, uploads the base
colour texture with its sampler, and flips V so glTF's top-down UVs match the
scene's bottom-up UVs. Metallic-roughness, normal, occlusion and emissive maps
stay available on GltfMaterial for callers that supply a custom shader
material; the standard material uses the base colour map. Use
GltfMaterialToScene to convert a material yourself.
make scene-gltf-test checks the reader and adapter against small fixtures
(GLTF and GLB, sparse and normalized accessors, morph targets, all
interpolation modes and malformed files), and make scene-gltf-gpu-test
renders an animated two-bone skin headless through the GLES scene path and
compares it with tests/fixtures/gltf/skinned_reference.png. Both run through
build-queue --. The committed Khronos sample models under
tests/fixtures/gltf/khronos/ are CC-BY-4.0 or CC0-1.0 and keep their
upstream README files; models carrying a non-Khronos trademark are never
committed and run only from a local sample-assets checkout named by
KRYON_GLTF_SAMPLE_ASSETS.
VRM avatars
Import kryon/scene_vrm for VRM 0.x avatars (.vrm files such as VRoid
exports) loaded through scene_gltf: the humanoid bone map, expressions,
eye lookAt and spring-bone physics for hair and clothes.
#import "kryon/scene_gltf"
#import "kryon/scene_vrm"
model := GltfReadFile("models/avatar.vrm")
instance: GltfSceneInstance
unused GltfSceneCreate(*scene, *model, *instance)
avatar: VrmAvatar
defer VrmAvatarRelease(*avatar)
if VrmReadFile(*avatar, "models/avatar.vrm") {
unused VrmSpringsReset(*avatar, *model, *instance)
}
// Each frame: pose the bones in instance.rotations, then
VrmSetFrame(*avatar, turn, position, scale)
VrmSpringsUpdate(*avatar, *model, *instance, seconds_since_last_frame)
unused VrmSetExpression(*avatar, *model, *instance, "blink", closed)
VrmLookAtSet(*avatar, *model, *instance, yaw_degrees, pitch_degrees)
unused GltfUpdateScene(*model, *instance, *scene)
VrmReadFile(avatar, path) and VrmReadBytes(avatar, bytes) read the VRM
extension of a GLB or glTF JSON document and return false when there is
none. VrmBoneNode(avatar, "leftUpperArm") gives the glTF node of a VRM
humanoid bone or -1; avatar.bones holds all of them in VrmBoneName
order. VrmSetExpression sets a blend shape group, found by its preset
(blink, joy, a, ...) or its name, to a weight from 0 to 1 in the
instance's morph weights; binary groups snap at one half.
VrmLookAtSet turns the eye bones of a Bone lookAt avatar by degrees to
the avatar's left and up, mapped through its lookAt range curves.
Spring bones follow the VRM 0.x reference: each joint's tail moves by Verlet
inertia less drag, a stiffness pull back to its rest direction and gravity,
keeps its length and is pushed out of the sphere colliders of the collider
groups its bone group names. Physics runs at a fixed 60 steps a second in
the world placed by VrmSetFrame(avatar, turn, at, scale), so moving or
turning the whole model swings the hair as well. A step backwards or of more
than a quarter second, as after a seek, puts the springs back at rest, as
VrmSpringsSettle does. Node positions come from the instance's
translations, rotations and scales, so one GltfUpdateScene after posing
and springs is enough. VRM 1.0 (VRMC_vrm) files are not read.
make scene-gltf-test also checks the VRM layer against
tests/fixtures/gltf/vrm_avatar.gltf: the bone map, expressions, lookAt
curves, gravity, colliders, stability while the body moves at uneven frame
steps, and settling after a seek.