Files
waozi 216c190c43 Document only current Kryon APIs and website pages
Remove raylib paths, obsolete import and preview guidance, migration prose,
and orphaned documents/pages. Align widget imports, native ZX windows and
host contracts with the current implementation, and enforce current site routes.
2026-11-16 21:43:18 -03:00

7.5 KiB

Canvas2D browser host

A browser integration roots src/backend/canvas_raster.zi with the selected host and defines PLATFORM_WEB. Generate native sources with Ziran, then link them with Emscripten, and Ziran's Web bridge:

--js-library $ZIRAN_DIR/web/ziran_web.js
-sEXPORTED_RUNTIME_METHODS=FS
-sASYNCIFY -sSINGLE_FILE=1 -sEXIT_RUNTIME=1 -sENVIRONMENT=web

The browser hosts (page_core.zi, page_paint.zi, page_texture.zi, page_font.zi, page_events.zi, page_files.zi, page_input.zi, page_mesh.zi, canvas_audio_host.zi, dom_host.zi) are written in Ziran and reach the page through std/web.zi; the one JavaScript file is the generic, Kryon-agnostic bridge in the Ziran repository.

The page uses a Canvas2D context with a drawing preference that survives occasional pixel reads. When WebGL is available, Image meshes share a private surface around their visible bounds and transfer to the page together. Indexed grids reuse shared vertices, and small size changes reuse the drawing buffer. Texture changes retain their painter order within the batch. Other paint, clipping, target changes, readback and presentation flush that batch in order. Without WebGL, the same API uses the Canvas2D triangle painter. Ordinary sprites without local rotation or mirroring draw directly in the current camera coordinates. They preserve the caller's opacity and sampling without copying the complete canvas state for each tile. Opacity alone does not allocate a tinted texture. The UI host retains its existing back buffer. It compares checked paint plans, keeps unchanged pixels and clears/replays only the damaged region. Session, viewport, display-density, background and raster-resource changes repaint as needed. Ordinary host paint and custom emitters use complete painting. Text measurement leaves retained pixels intact. This adds no extra full-size surface. The dedicated canvas_raster.zi provider calls the Canvas modules directly, so retained widgets use the same paint queue, font selection, and clipping path as the native host. Frame-profile builds retain the selected _run host and canvas_raster.zi as generation roots for raster and typeface adapters. A program entry owns its own main.

RequestWindowClose is currently a raw browser host capability. An application may declare it against host_api; the host records the request and observes it on the next poll so the current frame can finish committing.

Ziran owns frame timing, image memory, font atlas packing, text layout, file callbacks, audio decoding and conversion, resource APIs, and every call into the browser's events, Canvas2D, FontFace, WebAudio, clipboard, and Emscripten filesystem. Asynchronous browser calls carry Emscripten async metadata and require Asyncify.

EndDrawing yields to the next browser frame for ordinary canvas loops. An application using emscripten_set_main_loop must call SetExternalFramePacing(true) before starting that loop, so only the callback scheduler waits for frames. SetTargetFPS then adjusts that scheduler's RAF interval; it does not suspend EndDrawing. Opening a window resets this mode.

The host finds #canvas and fills its #canvas-frame container when one is present, otherwise the canvas parent. It draws at the canvas's own CSS size, so a frame padded for safe-area insets still matches where touches land, and maps pointer positions through the canvas's shown box. Include UTF-8 metadata in HTML shells, including shells using Emscripten's single-file Wasm output. Only this host's event listeners and resize observer are removed on close. A subsequent open creates new input and texture state; cached default font memory is released before closing the canvas.

A #canvas that carries the data-transparent attribute has no background: the host clears the window and each frame to alpha 0 instead of Kryon's frame colour, so the page behind it shows wherever the program draws nothing, and widgets draw over it as usual. The editor preview sets it; without it every pixel is opaque.

Applications that handle Escape as navigation can call CanvasSetExitKey(0) through kryon/Canvas to disable the host's default Escape-to-exit behavior. Ordered keys and text remain available through CanvasInputTake(session).

Custom Canvas hosts can use BeginRasterClip(bounds) and EndRasterClip(saved) through kryon/Canvas to intersect a rendering scope with an outer viewport, restoring the previous clip afterward.

Images are RGBA8 (format = 7). Individual pixel allocations are limited to 64 MiB and 16384 pixels per dimension. Tint caching retains at most 32 entries and 16 MiB of pixels; releasing or updating a texture invalidates its cached copies. Frame input queues hold at most 1024 events. Audio streams enqueue at most two pending buffers and report their actual readiness.

Mesh acceleration retains at most 32 source textures and 16 MiB of source pixels; its drawing surface is limited to four million pixels and the device's own limits. Texture updates refresh cached pixels. A lost context releases its resources and invalidates retained paint before the next frame.

Browser window position, monitor selection, and native window icons have no corresponding operation on the embedded canvas. Fullscreen and pointer lock requests remain subject to browser gesture permissions.

Focused checks

tests/canvas_backend_test.sh
python3 tests/canvas_audio_test.py
sh tests/canvas_text_os_wasm_test.sh
python3 tests/canvas_project_test.py

The first command compiles the complete host and checks real pixels in a new headless Chromium process. It covers camera and nested clipping, UTF-8 input, texture updates and render targets, asynchronous PNG round trips, a real TTF font, frame yielding, and close/reopen ownership. Mesh pixels, sampling, opacity and texture updates run at three display densities with acceleration both available and unavailable; the accelerated runs also lose and recreate their graphics context. It scrubs desktop display variables and controls only its own browser process. The other tests verify WebAudio and text/file behavior with deterministic browser-effect fixtures. The project test builds a real application manifest through Ziran, loads the resulting single-file page in private headless Chromium, and checks its exit. EMCC, CHROMIUM, ZIRAN_DIR, and ZIRAN_BUILD_DIR can select installed tools. ZIRAN_RUNNER optionally wraps focused compiler calls in a caller's serialization script; do not set it when that script already holds its lock around the entire test.

Canvas host performance

Before changing the host or Ziran browser bridge, preserve a compiled baseline:

python3 tests/canvas_performance.py build/scratch/canvas-performance/before
# Apply the change, then compile the same workload again.
python3 tests/canvas_performance.py build/scratch/canvas-performance/after
node tests/canvas_performance.mjs build/scratch/canvas-performance/before \
  build/scratch/canvas-performance/after build/scratch/canvas-performance/result.json

The runner uses private headless Chromium profiles and interleaves nine samples per version after warmup. Each sample draws fifty frames of a 512-sprite tile board, followed by pixel readback. An independent pixel oracle checks the ordinary board; rotated sprites must match the baseline. Receipts preserve raw timings and artifact hashes. This measures warm Canvas host throughput on one shared machine; it does not establish a whole-game frame rate or a speedup on other devices. The builder refuses to replace an existing compiled artifact.