38 KiB
Kryon hosts
Kryon's reusable widget, layout, input, and composition code is written in
Ziran under src/ui/. An application imports the widget packages it uses,
such as Text :: #import "kryon/text";, and exports Frame(session: Session, viewport: Rectangle) -> s32. A selected host under src/backend/ owns the process entry point,
window or terminal, platform input, rasterization, and presentation. Ziran has
no special knowledge of Kryon widgets.
Select a host with a profile in the application's ziran.toml:
[tool.kryon]
default_profile = "desktop"
[tool.kryon.profiles.desktop]
backend = "desktop"
Run ziran tool kryon build or ziran tool kryon run from the application.
See Ziran projects for the complete package manifest.
Renderer artifacts in build scripts
The package exports renderer-desktop, renderer-desktop-windows and renderer-web
artifacts for the supported native and browser targets. Request them through
ziran pkg artifact kryon:NAME --platform OS-ARCH-ABI, using the application's
package wrapper and locked graph. Ziran's scripts/ziran_artifacts.py verifies
the descriptor and its declared outputs; see its package guide for the Python
Artifact and request API.
Kryon's scripts/renderer_artifact.py provides the renderer-specific consumer
functions alongside its provider. Load it from the resolved pkg path kryon
directory and call renderer_metadata(artifact) with that verified artifact.
It validates the renderer/platform combination, compile/link argument types,
resources, include directories and virtual preload mounts, then returns
metadata with absolute paths. Every archive, resource, JavaScript library and
preload must be a declared artifact output. Paths resolve beside that
artifact, regardless of the build script's working directory.
renderer_link(metadata, preloads=True) returns ordered linker arguments,
including JavaScript libraries and browser preloads. Set preloads=False
when a host supplies those files separately. compile_flags, defines and
include_directories remain separate metadata fields for the host compiler
or CMake invocation. Application editions, asset lists and output names stay
in the application.
Available hosts
| Profile backend | Ziran entry | Presentation |
|---|---|---|
terminal |
src/backend/terminal_run.zi |
80 × 24 terminal cells via terminal.zi |
desktop |
src/backend/desktop_run.zi |
SDL2 window with Cairo raster |
canvas |
src/backend/canvas_run.zi |
Canvas2D page with Emscripten and Asyncify |
dom |
src/backend/dom_run.zi |
HTML elements with browser layout and CSS |
android |
app src/main.zi → android_run.zi |
Android NativeActivity package with direct ANativeWindow pixel presentation |
The small application surface selects the host from the compile-time target.
Import kryon/app and call App.Run(window, draw): C/Linux uses
kryon/host/desktop, while C/Web uses kryon/host/web. Advanced hosts can
import those named host packages directly. The desktop implementation uses
cairo_raster.zi and desktop_loop.zi.
After PollDesktop(), custom loops call DesktopInputTake(session) to transfer
the next ordered editing action or printable-key/text run into that session.
The returned key uses shared codes, including 320–329 for numeric-keypad
digits, and carries the modifiers held when that key arrived.
Standalone AppContext applications use the compiled host
canvas_app_run.zi.
Polygon-clipped images use native Cairo/Canvas path clips. Complex polygons and pixel hosts use
clipped spans while preserving the original source mapping.
SDL pixel hosts use software presentation by default. SDL_RENDER_DRIVER
retains explicit driver selection; KRYON_PIXMAP_GPU=1 requests accelerated
presentation. Pixel rasterization remains on CPU workers unless the host
explicitly enables a GPU painter.
Desktop windows become visible only after their first complete frame has
been uploaded and presented. A failed initial upload or copy leaves the
window hidden until presentation succeeds.
The image_preview module also supplies ImageCompress for smaller upright
JPEG copies. It keeps transparent and animated originals intact and returns
no replacement when encoding would increase file size.
HTML DOM profile
[tool.kryon.profiles.web]
backend = "dom"
Run ziran tool kryon build --profile web. The C99 profile produces a
self-contained build/<package>-web.html. It calls the app's exported
Frame(session: Session, viewport: Rectangle) -> s32 with the viewport in
CSS pixels. Submit the retained widgets with their ordinary package APIs.
Give widgets stable key values to retain their HTML elements as labels and
sibling order change. Changing a node's parent, widget kind or tag creates a
new element. Close widget scopes with kryon/tree's End(session).
| Ziran API | HTML |
|---|---|
kryon/page Draw and Section |
main and section with the supplied accessible name |
kryon/page Heading or kryon/text Draw with heading semantics |
h1–h6 |
kryon/text Draw |
span, or p with paragraph semantics |
kryon/button Draw |
button type="button", with browser tab focus and click, Enter and Space activation delivered through the shared widget result |
| Retained row, column, grid, stack and scroll scopes | div with basic flex, grid or overflow rules |
| Retained separator | hr |
The root is #kryon-dom-root. data-kryon-widget holds the committed widget
kind. data-kryon-id and data-kryon-class hold nonzero decimal style tokens
when the widget publishes them. data-kryon-selected="true" marks selected
nodes for CSS. Selected buttons expose aria-pressed="true". Disabled and
loading buttons are disabled in the browser and publish aria-disabled or
aria-busy respectively.
Import Dom :: #import "kryon/dom"; in a DOM frame app and call
Dom.SetStyleSheet(css) to replace the author stylesheet with CSS text.
An app with multiple host profiles can guard DOM imports and setup with
#if #defined(KRYON_DOM) while sharing its widget submissions.
Passing an empty string clears the sheet. Scope rules to #kryon-dom-root as
needed. The browser handles selectors, document flow, variables,
prefers-color-scheme, and prefers-reduced-motion. Native style sheets
continue to drive shared widget calculations and other hosts. Supply browser
CSS separately, for example with the CSS package's ExportCSS.
Dom.RequestClose() stops frame delivery after the current frame and leaves
the final document visible.
CSS controls the browser's geometry. The DOM profile uses the retained
hierarchy and semantics and discards the raster paint queue. Other retained
node kinds appear as generic containers. Use the Canvas profile for pixel
painting, image rendering, and widgets requiring editing, dragging or custom
pointer coordinates. make dom-profile-test builds the normal consumer
profile and exercises it in private headless Chromium.
Hosted ZX software surface
Import kryon/host/surface in a portable app and call Run(window, draw)
with the same Window and Draw types as kryon/app. A Frame identifies
the current session by slot and epoch. The bundle runs the widget tree,
layout, hit testing, paint queue and pixmap raster, including text measurement
and rasterization with Kryon's bundled fonts. Compile ordinary widget imports
and bind their raster calls to pixmap inside the bundle.
From the Kryon checkout, using canonical Ziran:
mkdir -p build/scratch/zx-surface
ziran bundle --project --bind-host pixmap --entry hosted_surface:main \
-o build/scratch/zx-surface/hosted_surface.zx examples/hosted_surface.zi
A host supplies typed HostBinding callbacks for the four capabilities in
zx_surface.zi. Bind the exact module name
from the bundle's capability metadata. The module is zx_surface in the
in-tree build and may be package-qualified in a consumer build.
For a consumer project, use --bind-host <kryon-package-id>_pixmap, where
<kryon-package-id> is the Kryon package's id in the project's ziran.lock.
| Function | Signature | Host behavior |
|---|---|---|
Open |
(title: string, width: s32, height: s32) -> bool |
Create one hidden window per instance. The dimensions establish the initial pixel viewport. |
Event |
(wait_ms: s32) -> SurfaceEvent |
Return one event in FIFO order. Wait at most wait_ms when the queue is empty. Zero polls immediately. |
Present |
(width: s32, height: s32, rgba: string) -> bool |
Consume or copy exactly width * height * 4 bytes during the call. A successful first frame shows the window. |
Close |
() |
Release the window and its input queue. Closing is idempotent. The host also releases them when the instance exits or traps. |
Present uses tightly packed top-down RGBA8 with alpha 255. Its string
is a byte span and can contain zeros. If a resize arrives during painting, the
host can discard the stale frame and return success while delivering the resize
event for the next frame. The app exits with status 1 if Open or Present
fails or a resize provides unsupported dimensions. A close request exits
with status 0. The bundle accepts up to 4,194,304 pixels per surface and up to
16,384 pixels per dimension.
SurfaceEvent has signed 32-bit fields kind, x, y, button, key,
modifiers, width and height, plus text: string. Set unused fields to
zero or the empty string. Return the event's declared record type from the
capability metadata.
kind |
Meaning | Payload |
|---|---|---|
| 0 | Idle or timeout | |
| 1 | Close requested or window lost | |
| 2 | Redraw | |
| 3 | Resize | Positive width, height in pixels |
| 4 | Pointer move | Window-local x, y in pixels |
| 5, 6 | Button down, up | x, y, button (1 left, 2 middle, 3 right) |
| 7, 8 | Key down or repeat, up | key, modifiers |
| 9 | Committed text | UTF-8 text |
Use the portable key codes, including uppercase
ASCII for letters and modifier bits 1 Shift, 2 Control and 4 Alt. Deliver text
as a commit independently of the key press. Kryon routes left and right
buttons through its primary and secondary widget input. Frames run on input,
expose and resize. Pass a positive idle_ms to also redraw on timeouts at an
interval of up to one second. For example, a stopwatch can redraw every 250 ms
and read elapsed time from its host clock. Platform services such as clocks,
clipboard and live IME composition require additional capabilities.
make zx-surface-test builds and runs the example in the Ziran instruction
engine with a typed host. It verifies the RGBA bytes, rendered count changing
after a click, UTF-8 editing, resize, close and opt-in timeout redraw. An
emulator can launch the same bundle by registering the four capabilities. In
a TaijiOS window-manager context with the surface provider installed, run
zxrun -w /path/to/hosted_surface.zx with the bundle under the guest root.
Experimental SDL3 GPU renderer
Custom Linux x86_64 GNU hosts can import kryon/pixmap_sdl3 and
kryon/pixmap_sdl3_gpu. This is an opt-in rendering prototype, rather than a
new project profile: the host supplies an SDL3 window, input loop and
presentation. Desktop profiles keep their behavior.
The handwritten renderer is Ziran; SDL3 supplies the GPU API and shaders.
Kryon's native-sdl3 artifact builds static SDL 3.4.18 from its pinned official
source package. No Git submodule or global SDL3 installation is needed. Build
prerequisites are a GNU C toolchain, CMake, pkg-config, Python 3.11+, X11
development headers and Vulkan headers/loader. Running requires an SDL3 GPU
device, which may be software. On Debian/Ubuntu the additional test packages
are libvulkan-dev mesa-vulkan-drivers libx11-dev libxext-dev libxtst-dev xvfb xauth.
From the Kryon checkout, with Ziran available:
build-queue -- env -u DISPLAY -u WAYLAND_DISPLAY -u XAUTHORITY \
-u DBUS_SESSION_BUS_ADDRESS make sdl3-test
This resolves and builds the locked SDK through Ziran, verifies its declared
outputs, and runs shared scene, geometry adapter and real private-Xvfb renderer
tests. Package metadata and the generated import smoke test stay under ignored
work/sdl3-integration; there is
no copied source checkout or hard-coded SDK cache key. The Linux CI hosts job
runs the same target with Mesa's software Vulkan device. Missing GPU support
fails the test instead of skipping it.
A host's minimal rendering sequence uses the ordinary package exports:
Sdl3 :: #import "kryon/pixmap_sdl3";
Sink :: #import "kryon/pixmap_sdl3_gpu";
// After SDL3 initialization and window creation, on the window's thread:
renderer := Sdl3.CreatePixmapSdl3Renderer(window)
// Check renderer != null, then Sink.PixmapSdl3Open(renderer).
// Create and retain a target with Sink.PixmapSdl3CreateTarget(width, height).
// Record normal pixmap painting, then check Sink.PixmapSdl3Draw().
// Copy the target to the window with SDL_RenderTexture and SDL_RenderPresent.
// Close the sink before destroying host-owned targets, renderer and window.
CreatePixmapSdl3Renderer explicitly requests SDL's gpu renderer and returns
null on failure, without trying another renderer. Inspect
PixmapSdl3DescribeRenderer(renderer) for the renderer name, API, device name
and driver information; its strings are borrowed until renderer destruction.
A gpu renderer using vulkan does not establish hardware acceleration.
The verified local device was llvmpipe LLVM 19.1.7 / Mesa 25.0.7, a software
Vulkan implementation. These tests establish rendering behavior, not hardware
performance.
The sink shares pixmap_gpu's clipped geometry, glyph atlas, paint order and
single active recorder. Image publications and sink calls must use the renderer
thread. After a failed draw, close/open and repaint fully; after an SDL render
device reset, call PixmapSdl3DeviceLost, recreate the host-owned target and
repaint fully. The sink does not destroy host-owned render targets.
The CPU parity tests cover five scenes and three frames each. Blending has small
rounding differences (observed maximum channel difference 3). Exact nearest
texel ties in the 1.25× zoom scene can choose the adjacent texel, as in the SDL2
reference; the test accepts only analytically identified checker boundaries
within the image and clip. The shared sampler is therefore not byte-exact at
those ties. SDL3 also converts byte colors to float colors in 1536-vertex chunks,
which can add draw calls; this does not establish a speedup over SDL2.
See the executable lifecycle example in
tests/sdl3_renderer_host_test.zi.
For SDL2 versus SDL3 on a physical AMD GPU under Linux, use the explicit
hardware mode (choose the render node from /sys/class/drm/renderD*/device):
build-queue -- env -u DISPLAY -u WAYLAND_DISPLAY -u XAUTHORITY \
-u DBUS_SESSION_BUS_ADDRESS -u SESSION_MANAGER YUE_DESKTOP_RECOVERY=0 \
python3 tests/backend_render_benchmark.py --mode hardware \
--device /dev/dri/renderD129 --trials 5 --frames 1200 --warmup 240 \
--output work/backend-render-benchmark/hardware.json
Hardware mode uses SDL2 offscreen EGL/OpenGL and SDL3 offscreen Vulkan with
a headless surface, without the desktop compositor. It removes inherited
software-driver overrides and selects Mesa's Vulkan device by vendor/device
ID. Selection is only a request: both hosts must report a physical renderer
and nonzero Linux DRM graphics-engine execution on the requested PCI device.
The report records that device's render node, PCI address, vendor/device IDs,
kernel driver, renderer/API and Mesa versions. A mismatched device, software
renderer, missing execution evidence or failed pixel oracle blocks hardware
timing. This qualification currently requires AMD's Linux DRM counters; it
does not infer acceleration from the Vulkan API name. The default software mode still forces
llvmpipe on private Xvfb; --backends sdl2 sdl3 restricts its smoke test.
Every selected backend must pass all 120 frames of all five 480×320 scenes before hardware timing starts, using the same channel tolerance and narrow checker-boundary rule described above. Parity exercises presentation as well as target readback. Repeated trials randomize backend order per scene and record CPU compose/submit/present p50/p95, individual frame samples, per-trial drained wall throughput and load averages. Drained wall throughput includes the final synchronous readback and CPU conversion; it is not a GPU timestamp measurement. Offscreen results do not measure visible-window/compositor performance, and other running workloads and GPU clock changes remain uncontrolled. No backend default or SDL2 software fallback is changed.
AVIF images
Native AVIF and WebP decoding is supplied by the standalone Ziran avif,
webp and image_codec packages. Kryon selects the platform engine and adapts
caller-owned straight RGBA8 into host pixels, surfaces and textures. Codec
parsing, native ABI and frame composition belong to those packages. The current
native engines explicitly bridge pinned external libraries; this integration
makes no authored AV1 decoder or performance claim.
Content routing uses the packages' bounded prefix predicates; their decoders
perform complete container validation. Kryon's CMake entry points consume the
packages' shared native build recipes and retain the existing target names and
archive locations. Package directories come from ziran pkg path; renderer
artifacts pass their resolved dependency paths explicitly. Custom CMake hosts
can set KRYON_AVIF_PACKAGE_DIR and KRYON_WEBP_PACKAGE_DIR to those paths.
The adapters allocate the final host buffer once. AVIF probes metadata, then revalidates and decodes the same immutable encoded buffer into that storage; this repeats bounded metadata parsing without copying a full owned output. Failed decode, cancellation and changed output dimensions release the buffer before publishing any pixels. Browser codecs and pixel-renderer inputs retain their existing paths.
Image.Draw(Image.Props) accepts AVIF assets through the same path as PNG/JPEG/WebP,
including extensionless names and packaged bundle/APK assets. Native hosts
decode with the locked libavif 1.3 and dav1d, its assembly selected at run time
for the CPU (x86 SSE2 to AVX-512, ARMv7 and AArch64 NEON); Android 9 requires
no OS AVIF support. libaom is linked as the explicit comparison oracle, never
as a fallback. The still-image API shows the first complete frame of a
sequence. The ARMv7 oracle keeps libaom's portable kernels, because the locked
AOM/NDK combination emits unaligned NEON loads which fault on real Android
hardware; dav1d's own NEON runs there. The ARMv7 device suite covers both Debug
and Release, including the original large YUV420 crash input and background
image loading.
Desktop hosts load the AVIF bridge (libkryonavif.so, kryonavif.dll) on
first use, from KRYON_AVIF_LIBRARY, the library search path or beside the
executable, and WebP from the system libwebp. A program that links the codecs
itself builds with --define KRYON_AVIF_LINKED (libavif and its AV1 codec)
and --define KRYON_WEBP_LINKED (libwebp and libwebpdemux), and loads
neither; make avif-decode-test runs such a build, linked with the static
archives, where no libkryonavif exists.
8/10/12-bit color and monochrome decode to straight 8-bit RGBA; alpha and
container clean aperture, rotation and mirroring are preserved. The renderer
then premultiplies for Cairo. HDR tone mapping
and ICC display color management are outside the existing 8-bit image surface.
Encoded files are limited to 256 MiB, dimensions to 32768 per axis and pixel count to 67,108,864 (a 256 MiB RGBA buffer). These are independent axis/count limits, permitting wide images below the pixel budget. Invalid/truncated containers, invalid crops and oversized images return no image. 4:2:0 frames of at least 8 MiP and other frames of at least 2 MiP decode on the process's usable cores, capped at 4 threads; smaller frames use one, because threading slowed them by up to 2.7x on the Moto. Thread count never changes output bytes. Only the first decoded frame is retained.
| target | engine | proof |
|---|---|---|
| Linux x86-64 | dav1d, SSE2..AVX-512 | executed: strict parity, benchmark |
| Android armeabi-v7a | dav1d NEON | executed on the USB Moto (MT6765, Android 9): parity, benchmark |
| Android arm64-v8a | dav1d NEON, dotprod, i8mm | static build under qemu-user: strict parity |
| Android x86, x86_64 | dav1d SSSE3..AVX-512 | static build on the x86-64 host: strict parity |
| Linux AArch64 | dav1d NEON, dotprod, i8mm | qemu-user: strict parity |
| Windows, macOS | dav1d via the same recipe | unverified here |
Canvas uses the browser AVIF decoder through PageImageDecode; supported
browsers (Firefox 93+, Chromium 85+, Safari 16.4+) supply their native AVIF
implementation. In a browser without AVIF, every AVIF decode fails cleanly:
no pixels and zero size, so the image is treated like any undecodable file,
while PNG, JPEG and WebP keep working. Ship a fallback format for such
browsers. The pure pixel renderer accepts decoded pixel buffers through
PixmapSetImage, as for other formats.
make avif-decode-test runs independent RGBA goldens from source and saved IR,
and checks dav1d (automatic, 1 and 8 threads) and the libaom oracle against the
strict libavif digests in tests/avif_strict_digests.zi, tolerance 0. The
independent goldens keep small documented tolerances: ±1 for 10/12-bit and
grayscale (8-bit rounding of the source pattern), ±4 premultiplied (unpremultiply
rounding) and ±3 for Jungle title samples (YUV420 conversion versus Pillow).
make avif-render-test checks native rendering,
including a portable bundle using the public Image widget. make android-avif-test ANDROID_NDK=... ANDROID_SERIAL=ZE2223BQZT builds all four ABIs and runs the
ARMv7 strict-parity/golden-pixel tests on the Android 9 USB Moto, asserting each
ABI's dav1d assembly. make avif-cross-test [AVIF_CROSS_ROOT=...] [ANDROID_NDK=...]
runs the strict parity test for Linux AArch64 and static Android arm64-v8a
under qemu-user (Cortex-A53 and every emulated feature) and Android x86/x86_64
on the host; AVIF_CROSS_ROOT is a prefix holding the AArch64 GCC and
qemu-aarch64. make avif-browser-test exercises the Canvas image
boundary in private headless Firefox, reporting the AVIF capability, and repeats
it as a browser without AVIF. make avif-benchmark [ANDROID_SERIAL=ZE2223BQZT] [AVIF_BENCHMARK_BROWSER=1] records ms/image, MP/s and peak RSS for libaom,
dav1d threads and SIMD tiers, and Firefox, in build/scratch/avif-benchmark.
The headless package suite, build-queue -- sh tests/image_integration.sh,
resolves real native artifacts and tests source and saved IR under ASan, UBSan
and leak detection, including adapter failure cleanup. With development-only
package overrides, set ZIRAN_ROOT and ZIRAN_BIN to the rebuilt toolchain.
WebP images
Images, image previews and app media files accept WebP wherever they accept
PNG or JPEG, recognized by the file's RIFF/WEBP signature rather than
its name. Lossy, lossless and alpha pictures decode to straight RGBA. An
animated WebP decodes to its first complete frame, since Kryon images are
still; ImageCompress keeps animated originals unchanged.
- The desktop (Cairo) host loads the system libwebp demuxer
(
libwebpdemux.so.2) on first use, like its other optional codecs. - The canvas host uses the browser's own WebP decoder.
make test-focus TEST=ziran_image_decode_linux_test decode the
tests/fixtures/webp pictures natively, tests/webp_browser_test.py does the
same in headless Chromium, and make android-webp-link-test links the
decoder for every Android ABI.
The PNG byte and pixel rules are Ziran in png.zi. PNG supports all standard
color types and depths, transparency, all five filters, and Adam7 interlace.
Sixteen-bit samples use their high byte; ancillary color profiles and gamma
are ignored. tests/ziran_png_test.sh compares independent reference pixels
for 33 fixtures through source and saved IR in bundles, C and Go, including
malformed streams and bounded decoder output.
Browser projects save the selected _run host and canvas_raster.zi as
generation roots without entry pruning. This keeps both the host main and
the raster adapters available to the paint queue. Native projects continue
through the ordinary package entry route.
Smooth images (Lanczos)
A smooth picture (.smooth = true) is shown at the device pixels it
covers through one shared cache, src/backend/lanczos_cache.zi. The copy is
std/resample's Lanczos-3, which gives the same bytes as Pillow's
Image.resize(size, LANCZOS, box). It is computed over premultiplied
pixels and drawn pixel for pixel. The key is the picture's content, its
revision, the source rectangle, the device-pixel size and the session.
Until a copy is ready, the backend draws the previous copy of the same
picture stretched, or uses its own filter if there is none. The finished
copy replaces it in one step. A changed or released picture forgets its
copies. Distinct sizes of the same source and revision coexist within the
LRU budgets, so a large cover and its small marker do not evict each other.
- Only axis-aligned draws under a plain translation are cached. Rotation, scaled transforms, meshes, polygon strips and render targets keep the backend's own filter. A whole-pixel draw at the source's own size needs no copy.
- Limits: a copy is at most 4096 pixels per side and 4,194,304 pixels; all copies together take at most 64 MiB, and one session at most 32 MiB.
- Like Pillow, filtering works on the stored sRGB bytes, not in linear light.
- Copies are made on a worker thread with a std/parallel pool in builds
with
POSIX_THREADS,ANDROID_BUILDorKRYON_FRAME_THREADS. A browser build without threads makes a slice of rows each frame instead (about two million filter taps). Other builds keep the backend's filter.
| Backend | Lanczos copy |
|---|---|
| Desktop/Cairo | Cached surface, drawn 1:1 |
| pixmap and SDL3 GPU | A copy slot drawn 1:1 (threaded builds only, PIXMAP_LANCZOS), so the CPU rows and GPU hosts show the same bytes |
| Canvas | Ziran resampler in slices, from the texture's pixels read back, then uploaded |
Firefox has no imageSmoothingQuality. Canvas therefore does not rely on
it, and still sets it to high for upright smooth draws that it does not
cache; meshes and images that the draw or a camera turns keep the browser's
default.
The cached Canvas copy matches Pillow for opaque pictures. Translucent
pictures differ by the browser's 8-bit premultiplied blend, up to about
3.5 levels on average.
A web profile's page carries two builds of the program: one compiled with
-msimd128 and a baseline one. A small script in the page starts the
SIMD128 build where WebAssembly.validate accepts a SIMD probe module, so
Canvas copies use std/resample's SIMD128 kernels, and the baseline build
elsewhere. Both builds give the same bytes. The page stays one file, and the
font is carried once for both builds (mk/web-page.sh).
tests/web_simd_page_test.py, part of make canvas-project-test, checks
this in headless Firefox and Chromium.
A host that sleeps between events calls PixmapLanczosPending or
LanczosSetWake so it draws again when a copy finishes. The desktop loop
already does this by pushing a wake event. PixmapLanczosWait and
LanczosWait finish the current copy; captures use them so every
smooth picture is final.
make lanczos-goldens-test (part of make test) compares Cairo, pixmap,
Canvas in a private headless browser against
Pillow goldens. make lanczos-benchmark times Kryon against Pillow,
Pillow-SIMD, libvips and stb_image_resize2. It reports ms per output
megapixel, extra peak memory and PSNR against a float64 reference, on
x86-64 and over ADB on an ARMv7 phone. It writes
build/scratch/lanczos-bench/receipt.md. The comparison libraries are
test-only oracles.
Android host
backend = "android" builds an installable APK instead of a native binary.
Add the profile and the application id to ziran.toml:
[tool.kryon.profiles.android]
backend = "android"
[tool.kryon.android]
package = "com.example.app"
min_sdk = "21" # optional, 21 by default
abis = "arm64-v8a" # optional, arm64-v8a by default
kryon build --profile android generates a droid/ Gradle project beside
the application sources on the first build (never overwriting existing
files), then assembles a debug APK through the Android Gradle plugin, the
NDK, and CMake. kryon run --profile android additionally installs and
launches it on a connected device through adb, and kryon check --profile android checks the whole Zi graph with the Android defines. The build needs
a JDK, the Android SDK with NDK 28.2.13676358 and CMake 3.22.1
(ANDROID_HOME, default $HOME/Android/Sdk), and the locked libwebp,
libavif and libaom source packages. Scaffolds pass their source roots to
kryon_android_codecs; the packaged host links no renderer or audio library.
At runtime a NativeActivity subclass owns the Java side: it reports window
insets, display cutouts, IME state, density, dark mode and orientation
through JNI natives registered by the generated src/android_glue.zi, and
forwards soft-keyboard text as codepoint, backspace and enter events. The
generated src/main.zi delegates to AndroidRunMain, which owns Android's
looper and lifecycle, drives the session with the current Ziran VM and Pixmap
runtime, and applies Kryon's Android viewport policies to the session-owned
text input queue. Frame always receives the safe area, clear
of the system bars and cutouts; a backdrop meant to run behind them draws into
AndroidWindowBounds(). Applications with their own JNI surface
keep their own JNI_OnLoad and call AndroidJniOnLoad with their activity
class to add the canonical natives. An application without Java code, a plain
NativeActivity, calls PollAndroidWindowInsets once per frame instead: it
reads the system bar, keyboard and cutout insets from the window through JNI
a few times a second, and stops once Java reports them.
The generation runs ziran ir --project for the whole graph, so application
module names may repeat Kryon module names; every package is prefixed in the
emitted C. tests/ziran_android_device_test.sh checks the device protocol
headlessly with the Java side stubbed.
android_device.AndroidRequestOrientation(policy) queues an ActivityInfo
screen-orientation policy through requestOrientation(int) in the scaffold
activity, which calls setRequestedOrientation on the UI thread. Custom
activities must provide that method. AndroidOrientationSensor (4) permits
sensor portrait and landscape; AndroidOrientationSensorLandscape (6) keeps
landscape. The caller owns route policy and deduplication. A true result means
the Java call succeeded, not that the OS has applied a rotation. Configuration
observations still use AndroidOrientation() and are independent of requests.
Android runs the native host loop on NativeActivity's app thread. Each poll
drains lifecycle and input events, snapshots the current touch/key state,
runs one VM frame through Pixmap, and presents the damaged viewport by locking
and unlocking ANativeWindow; there is no EGL, OpenGL ES or second render
thread. Rotation, surface destruction and redraw requests invalidate the
retained bitmap, while consecutive quiet frames can pace at 100 ms instead of
16 ms until the next event. Pausing stops presentation and platform media;
resuming restores the existing guest state.
Touch, pointer, soft-keyboard and hardware-key events are consumed only inside that frame boundary, so guest code receives a stable input snapshot and no platform callback reenters the VM. The same viewport transform maps single and secondary pointers into guest coordinates.
Portable ZX images are decoded before a guest is activated and retained in two bounded host slots. PNG, WebP and AVIF use native codecs; JPEG can use the platform decoder and all camera images apply EXIF orientation. A valid replacement promotes candidate pixels only after its services and images load; an invalid document leaves the previous guest, pixels and private data intact. MediaPlayer reads a private file written from bundle bytes and supports the portable play, pause, resume, stop, gain and completion surface.
Frame and input ownership
A host polls platform input and submits it to the session before calling the
application's Frame. The application and widgets consume generic session
input such as KeyboardTake, TypedCodepointTake,
PointerWheelTake, and pointer state. KeyboardModifiers reports
Shift, Control, and Alt keys as KeyModifierShift, KeyModifierControl, and
KeyModifierAlt bits, so a shortcut such as Ctrl+S is a key press read with
the modifiers that were down. Desktop and Canvas custom loops call
DesktopInputTake(session) or CanvasInputTake(session) before each frame. Each take transfers ordered text
to that session and returns the next key with the modifiers retained when the
press or repeat arrived, so shortcuts remain intact even when every physical
key is released before a frame. CanvasModifiers() and the immutable frame
snapshot keep their held-state semantics. Other hosts report none.
The host calls BeginFrame and
EndFrame around application composition, then presents the resulting
paint operations. Widget behavior stays in src/ui/.
The terminal host renders one frame when input or output is redirected. With
a TTY, it submits ASCII and UTF-8 text to the same session input API as the
window hosts and ignores terminal escape sequences. The project test drives
this through a private PTY. The other hosts can capture a frame with
KRYON_CAPTURE_PATH; the graphical integration tests run on private Xvfb
displays. Run make test for the library, browser, and typeface gates, plus
make desktop-project-test for graphical
capture and input.
Never run graphical tests against the developer's live display.
The SDL/Cairo desktop host also exposes DesktopSetTitle(title) and
DesktopTakeDroppedFile(output) through Desktop. A file-manager drop queues
up to sixteen complete UTF-8 paths (4095 bytes each), only for the host's own
window. The application consumes and opens them during Frame; an output
buffer that is too small leaves the next path queued. Text drops are ignored.
Portable programmable scene rendering
scene_render executes shader material programs in Ziran on CPU before
presentation. Cairo and Android's
ANativeWindow/Pixmap host consume the resulting managed bitmap through the
standard Image surface. These hosts do not need a shader-language bridge.
This interface does not claim GPU execution, GLSL compilation, vertex-shader
execution or GPU performance. See programmable scene materials
for binding ownership, colour space, clipping, alpha and explicit scratch release.
Programs and pictures contain no context-bound handles. Recreate the host
presentation context as usual; keep or re-upload the owned bitmap and render
again as needed. Shader discard affects colour rendering, not depth-map shadows.
Host lifecycle tests must verify bitmap re-upload after teardown; checking a
shader declaration alone does not establish host execution.
The physical-device regression make shader-android-test executes Ziran shader
materials and the Pixmap-to-ANativeWindow presentation path on the USB Moto. It
uses a private offscreen AImageReader window, verifies posted RGBA pixels,
clipping, alpha and binding changes, and destroys/recreates that window while
keeping the CPU program and bitmap alive. It does not launch or alter an owner
app. These targets also load a real PNG through
kryon/image_pixels; activity-bound Android asset/JNI decoding is a separate
application integration responsibility.
Native scene frames can render on the shared Ziran range-worker capability
when source generation enables POSIX_THREADS. Immutable transformed geometry
and ordered triangle commands are prepared once; each lane clears, draws and
resolves disjoint rows, joining once per frame. The scene owns its pool
separately from the presentation raster; RenderSceneRelease joins and
closes it. This is CPU row parallelism and does not change texture resolution,
four-sample coverage, shader operations or draw ordering. WebAssembly without
pthread support retains the same serial implementation. Application code must
keep all borrowed material inputs unchanged through the render call.
Optional native GPU scene rendering
kryon/scene_gpu is an explicit native EGL/GLES3 host for the same Scene and
material APIs. It renders offscreen with four MSAA samples, depth-map shadows,
retained geometry/programs/textures and an Image readback bridge. It creates no
window and preserves the caller's current graphics context. Link only consumers
of this module with -lEGL -lGLESv2 -lGLX -lm; core UI and scene_render imports retain
their existing portable and WebAssembly dependencies.
kryon/shader_glsl supplies portable material translation used by this host.
The translator alone has no EGL dependency. GPU execution uses highp floats
and hardware coverage, so it has pixel tolerances relative to the binary64 CPU
oracle. Capability failures are explicit; the separate SceneGpuRenderOrCPU
call permits a full-quality CPU frame and reports accelerated=false.
Probe/render/resource counters must establish acceleration and retained upload
behavior before reporting GPU timing. A module export or successful link alone
does not establish application integration or deployment.
See GPU scene APIs for ownership, lifecycle, capability requirements and local test targets.
Custom application entry
Applications that own their frame lifecycle import kryon/application_entry
and export KryonApplicationMain(argc: s32, argv: **u8) -> s32 with
#program_export "KryonApplicationMain". The adapter owns main: native
hosts forward their exact command line and browser hosts pass (0, null).
The callback retains initialization, frame scheduling and shutdown policy;
Android's NativeActivity host can call the same native entry. Do not define
an additional application main when importing this adapter.