summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-16 18:04:21 -0300
committerGabriel Schneider <[email protected]>2026-11-16 18:04:21 -0300
commite77b01d4b5504cea08a3f88cf8502897d868a1d3 (patch)
treec8e643d234dd26d920cbc563bfa7f740febf1fc7 /README.md
parentd3074636fff0fbcd5fd9b71c0c3b1c1f5c0c1285 (diff)
downloadsketchbook-e77b01d4b5504cea08a3f88cf8502897d868a1d3.tar.gz
sketchbook-e77b01d4b5504cea08a3f88cf8502897d868a1d3.zip
Add glTF scene rendering, resource setup and 9P controls
Diffstat (limited to 'README.md')
-rw-r--r--README.md192
1 files changed, 191 insertions, 1 deletions
diff --git a/README.md b/README.md
index d07a559..eb82bda 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,8 @@ An app is an ordinary module. Every declaration is optional:
| `State` | Saved to a file, snapshotted, replayed: what `update` changes. No pointers and no host handles (compile errors). |
| `Session` | This process: survives reloads, never saved. Caches, image and buffer handles, playback cursors. |
| `Store` | On disk, at the same address in every run: survives reloads and restarts. Big data that is not replayed (a recording, a document). May point into itself; no host handles. |
-| `init(state, host)` | Setup for brand-new state, after the declared defaults |
+| `init(state, host)` | Seed brand-new state, after the declared defaults |
+| `setup(session, init) !void` | Initialize resources once per fresh Session, including startup with restored State |
| `update(state, input)` | **Deterministic**: the host replays recorded input through it |
| `draw(state, session, store, frame)` | Pictures and sound, as commands; may change Session and Store |
| `command(state, session, store, console, line) !bool` | Console lines the host does not know |
@@ -44,6 +45,22 @@ Functions take the parameters they name, matched by type and in any order:
`State` and `Input`; asking for more is a compile error, since a replay could
not reproduce it.
+`setup` receives `*sk.Init` with `host`, `session`, and `store` allocators;
+it may also request Session, Store, or Host directly. It gets no State, Input,
+or Frame. Load assets and create/upload GPU buffers there, then use those
+resources in `draw`. `try init.host.writeBuffer(buffer, offset, bytes)` submits
+a copy immediately; the source bytes may be released when it returns. WebGPU
+uploads require four-byte-aligned offsets and sizes.
+
+Resource setup runs after Session defaults, once on startup even when State was
+restored from disk, and again if a reload changes Session's layout. Compatible
+reloads and ordinary state resets preserve the Session and do not rerun setup.
+The browser invokes it during its initial setup too. A hook may return `void` or
+`!void`; uncaught errors are logged and disable app callbacks, while the native
+host console and 9P controls remain available. Restart after fixing a failed setup.
+Use a Session error field and handle the error inside setup when the app needs
+to display an initialization failure. `zig build test-setup` checks this lifecycle.
+
Memory comes by lifetime, one allocator each:
| Allocator | Lifetime | Released |
@@ -828,6 +845,10 @@ Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
decoded, multisampling is 4× at most, and mixing runs on the main thread
(a ScriptProcessor), so a busy page can crackle.
+The reusable GPU executor and the pardes integration are described in
+[docs/pardes-rendering.md](docs/pardes-rendering.md), including the remaining
+renderer migration work and the optional addon boundary.
+
## Designs
- [Regions in source](docs/regions-in-source.md): editing layout from the
@@ -907,3 +928,172 @@ initialize Sketchbook so the build shares one host/client module.
ASCII text caches coverage independently of animated ink. The pinned SDL Vulkan
patch keeps memory relocation disabled and lets small transfer buffers share
allocations, avoiding hundreds of dedicated allocation frees during presentation.
+
+## glTF / GLB assets
+
+The optional `gltf` module wraps the vendored C99 `cgltf` loader. It loads scene
+hierarchies, mesh accessors, materials, cameras, animation tracks and arbitrary
+`extras` metadata without depending on the window or renderer. Import it into a
+native executable or sketch with `.imports = &.{.{ .name = "gltf", .module = sb.modules.gltf }}`.
+It currently requires libc; it is not wired into the freestanding browser host.
+
+```zig
+const gltf = @import("gltf");
+const document = try gltf.Document.parse(bytes);
+defer document.deinit();
+try document.loadBuffers(null); // embedded GLB / data-URI buffers, no file reads
+const node = document.findNode("CAM_StreetTour") orelse return error.MissingCamera;
+const json = gltf.extrasJson(&node.extras) orelse return error.MissingMetadata;
+// Parse json with std.json using the application's own metadata schema.
+```
+
+Keep `bytes` alive until `deinit`: GLB buffers may borrow it. Parsing validates
+structure and uses cgltf's C allocator, released by `deinit`. `loadBuffers`
+validates again with loaded data. Only passing a non-null, zero-terminated glTF
+source path enables relative external buffer-file reads; use that for trusted
+assets. Images and compressed geometry still need their own decoders.
+
+`document.data` and `gltf.c` expose cgltf directly; `gltf.readFloats(accessor,
+index, out)` adds bounds/component checks and supports strided, normalized and
+sparse accessors. The raw animation channels remain available to the caller;
+this module does not create GPU resources or implement an animation player.
+Run `zig build test-gltf` for focused loader tests; they are also part of
+`zig build test`.
+
+### Generated scene bindings
+
+`sb.addGltf` runs a native host executable in a separate build step, then supplies
+its generated `.zig` file as a module. The glTF file is a tracked build input;
+changing it regenerates the bindings before compiling their consumers.
+
+```zig
+// build.zig: add this import to the consuming module's .imports.
+.{ .name = "street_scene", .module = sb.addGltf(b.path("street.glb")) }
+```
+
+```zig
+const scene = @import("street_scene");
+const camera = scene.nodes.CAM_StreetTour;
+comptime {
+ if (!@import("std").mem.eql(u8, camera.extras.drat_role, "camera"))
+ @compileError("expected a camera role");
+}
+// camera.index locates the node; @TypeOf(camera.extras) exposes metadata fields.
+```
+
+The generated `nodes`, `animations`, `cameras`, `meshes`, and `materials`
+namespaces expose named entries with indices and typed `extras`; nodes also
+include optional camera and mesh indices. Labels with spaces use Zig's quoted
+identifier syntax, e.g. `scene.nodes.@"Camera - At the corner"`. Unnamed entries
+are omitted; duplicate labels within one namespace fail generation. JSON objects
+become struct values, arrays become tuples, and strings/numbers retain explicit
+Zig types. Comptime can reflect on these types or assert expected values; it never
+parses the asset. Missing referenced labels/fields and incompatible types fail
+compilation; application assertions define which metadata values must match.
+
+The module contains no libc dependency. `source_path` is the build input filename;
+`source_sha256` lets runtime consumers
+reject a replaced asset before using generated indices. Code generation reads
+metadata, not external buffers; geometry and animation sample checks still use
+the runtime loader. The game repo's `scripts/check_scene.zig` demonstrates both.
+
+### Local 9P controls
+
+Native hosts accept `--9p /absolute/path/game.sock`. The opt-in Unix socket uses
+cloud9, is owner-only (`0600`), refuses existing paths, and is removed on clean
+exit. Four clients can connect; requests run between frames on the host thread.
+The build uses the sibling `../cloud9` checkout.
+
+```sh
+./zig-out/bin/drat-meout --9p /tmp/drat.sock
+printf 'scene street\nget scene\n' | 9p -a unix!/tmp/drat.sock write ctl
+9p -a unix!/tmp/drat.sock read log
+printf 'screenshot\n' | 9p -a unix!/tmp/drat.sock write ctl
+9p -a unix!/tmp/drat.sock read status
+# Once screenshot_pending is false and screenshot_generation has advanced:
+9p -a unix!/tmp/drat.sock read screen.png > /tmp/street.png
+printf 'quit\n' | 9p -a unix!/tmp/drat.sock write ctl
+```
+
+`ctl` accepts complete console command lines (up to 4096 bytes per write),
+including game commands and host `set`, `get`, `pause`, `step`, `seek`, and `quit`.
+Errors return as 9P errors. `log` exposes the console's latest five lines;
+`status` reports canvas size, playback mode, GPU availability and capture state.
+`screenshot` captures the next rendered canvas as PNG; `screen.png` opens fail
+while capture is pending or failed. Each successful open pins its own snapshot,
+so a later capture cannot change a partially read image. Screenshots include
+visible overlays. `zig build test-control` checks the control boundary and
+snapshot lifetime; the same tests belong to the full host suite.
+
+With `--profile-gpu`, `profile` reports tab-separated `label`, `count`, `mean_ms`,
+and `worst_ms`, plus a `# frames N` line. `profile-reset` written to `ctl` resets
+counters and the frame denominator without discarding label allocations. Warm up
+first, reset, then wait for the desired number of frames before reading. These
+measure CPU wall time from GPU command recording through submission and fence
+wait, including synchronization overhead; they are not hardware GPU timestamps.
+Both operations return `ProfilingDisabled` when profiling is off.
+
+### Imperative glTF drawing
+
+Add an import with `.module = sb.addGltfRenderer()` (e.g. named `gltf_render`).
+Its `Model` copies a GLB's meshes and animation tracks into the caller's session
+arena. The cgltf document is released after loading; geometry uploads once to
+host-owned GPU buffers. Opaque primitives in each mesh are batched into one draw
+with per-vertex material colors. Only transforms and draw commands change each frame.
+
+```zig
+const render = @import("gltf_render");
+const street_scene = @import("street_scene");
+pub const Session = struct { model: render.Model = undefined, image: sk.Image = .none };
+
+pub fn setup(ss: *Session, init: *sk.Init) !void {
+ // Filename + hash come from the generated bindings. Parses and uploads once.
+ ss.model = try render.Model.load(init, street_scene);
+ ss.image = init.host.newImage(960, 600);
+}
+
+pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void {
+ renderFrame(s, ss, f) catch |err| f.host.print("scene: {t}", .{err});
+}
+fn renderFrame(s: *const State, ss: *Session, f: *sk.Frame) !void {
+ try ss.model.scene.sample(street_scene.animations.CAM_StreetTour.index, s.time);
+ const camera = try render.sceneCamera(&ss.model.scene, street_scene.nodes.CAM_StreetTour.index);
+ var view = render.View.init(f, ss.image, 960, 600, camera);
+ try view.scene(&ss.model);
+ // Or: try view.mesh(&ss.model, street_scene.meshes.MyMesh.index, transform);
+ // Or: try view.triangles(&geometry, transform, color); // upload in setup first
+ view.end();
+ f.image(ss.image, .{ .x = 0, .y = 0, .w = 960, .h = 600 }, .{});
+}
+```
+
+`model.scene.nodes[index].world` is a column-major transform; `meshes[index]`
+exposes indexed vertices, normals and material colors. Animation sampling is
+allocation-free, supports STEP, LINEAR (slerp for rotations), and CUBICSPLINE TRS,
+and clamps to the clip range; the application decides how to loop. The separate
+CPU API is `gltf.Scene.init(allocator, document)`, `sample`, `reset`, and `deinit`.
+It copies loaded data, so the document can be destroyed after initialization.
+
+`render.sceneCamera(scene, node_index)` derives perspective or orthographic
+projection and view from the sampled camera node. Alternatively pass a plain
+`render.Camera` with your own eye/target to `View.init`. `Model.init` remains
+available for CPU loading, and `Geometry.upload(host)` uploads custom triangles
+explicitly during setup. No resource loading happens inside `View.scene/mesh`.
+
+This initial renderer uses opaque material base colors, directional light and a
+depth buffer. It has no texture sampling, alpha blending, shadows, skinning or
+morph animation. Unsupported mesh/animation features fail loading explicitly;
+material textures are ignored. The renderer currently supports native hosts;
+`render.supported` is false in the browser replacement module. GPU handles are
+released by the host on session reset; call `model.release(host)` to release them
+earlier. Vertex storage layout and shader uniform layout are checked at comptime;
+GLSL uniform declarations are generated from the Zig types.
+
+`profile` also includes `p95_ms` and `p99_ms`: nearest-rank percentiles of the
+latest 2048 measured commands per label. Mean and worst cover every command since
+reset. `profile-trace` exposes those retained samples as CSV (`label,sample,ns`),
+ordered oldest to newest within each label; sample numbers start at 1 after
+reset. Each open pins the trace even if profiling continues or counters reset.
+The render path writes a fixed ring; sorting and CSV generation happen only on
+inspection. A trace snapshot is limited to 256 KiB and fails if it exceeds that
+limit. Capture it with `9p -a unix!/tmp/drat.sock read profile-trace > trace.csv`.