summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md356
1 files changed, 335 insertions, 21 deletions
diff --git a/README.md b/README.md
index ff9e538..e364c30 100644
--- a/README.md
+++ b/README.md
@@ -73,13 +73,24 @@ console) and one `tick` per frame carrying `dt`. Pointer and wheel events
carry the modifier keys held as they happened (`e.modifiers()`, `Key.Mod`
bits): read those, not `input.held`, for ctrl+wheel and the like, since a
trackpad's or a touch screen's pinch arrives as ctrl+wheel with no key
-events at all. Recorded ticks make
-time-driven sketches replay exactly. `input.started` is true on the first update after
+events at all. `update` is called once per frame, with that frame's events
+ending in its tick, live and replayed alike; in `update`, `input.now` and
+`input.dt` come from that tick (`dt` read back from the tick's f32
+seconds, so a replay sees the same bits). `input.mouse_x`/`buttons`/`held`
+follow the events fed so far. So time-driven and pointer-driven sketches
+replay exactly. Fields no event carries (`width`, `window_width`,
+`console`, `frame`) are not replayed: a sketch that reads them in `update`
+can replay differently. `input.started` is true on the first update after
the program starts, never after a reload: state is saved, so this is where
-to stop what should not resume on its own.
+to stop what should not resume on its own. In `draw`, `input.jumped` says
+State got where it is other than by `update` from what the last `draw`
+saw: the first frame, a seek, step, snapshot load, `set`, `reset`, play or
+record start, a sketch command, a reload. Anything `draw` piles up in
+Session (a trail in an offscreen image) is stale then; repaint it from
+State.
-`draw` gets a `Frame`: `clear`, `fill`, `image`, `text`, `print`, `clip`,
-`canvas`, `cursor`, `voice`, `audio`, `microphone`, `pixels`, `gpu`,
+`draw` gets a `Frame`: `clear`, `fill`, `shape`, `shapeColors`, `image`,
+`imageAt`, `target`, `blend`, `text`, `print`, `clip`, `canvas`, `cursor`, `voice`, `audio`, `microphone`, `pixels`, `gpu`,
`compute`, `upload`, `download`, `openFile`, `run`, `quit`, plus the three allocators and
`f.host` (`loadImage`, `decodeImage`, `newImage`, `newBuffer`, `loadSound`,
`decodeSound`, `samples`, `readFile`, `env`, `log`). Commands may be built
@@ -102,12 +113,212 @@ not for pixels.
Geometry and colors are duck-typed. Anything with `x`/`y` is a point, anything
that also has `w`/`h` (or `width`/`height`) is a rect, in any number type, and
`@Vector`s or arrays work too. Colors are `r`/`g`/`b`[/`a`] or `0xRRGGBB`. The
-helpers return the caller's own type:
+`Color`'s constants also go by name (`f.clear(.white)`); its functions
+need the type (`sk.Color.gray(220)`), since an `anytype` parameter gives a
+decl literal nothing to resolve against. The helpers return the caller's
+own type:
- `sk.shape`: `isPoint`/`isRect`/`isColor`, `contains`, `inset`, `offset`
- `sk.Camera`: `toScreen`, `toWorld`, `pan`, `zoomAt`
- `sk.tween`: `lerp` over any plain data, `lerpFields(a, b, t, .{ .x, .zoom })`, `toward(a, .{ .x = 100 }, t)`, and `ease`
+The drawing layer below is the exception: new, and typed (`sk.math.Vec`,
+`sk.Color`), so decl literals and completion work.
+
+## Drawing shapes
+
+Circles, lines and polygons are one host command, `Command.shape`: a
+region in one colour, given as points, subpath ends and triangle
+indices into the points. The web fills the subpaths (nonzero, one fill
+per outline and the holes after it); native draws the triangles with
+`SDL_RenderGeometry`. Both describe the same region, so translucent
+shapes blend alike, and shapes keep their order among `fill`, `image`,
+`text` and the clip. Both antialias: the canvas does, and native draws
+4x4 samples a pixel (with a GPU renderer: runs of consecutive shapes go
+into a supersampled layer, composited when another command comes) and
+averages them. Edges come out within a few levels of the web's, and a
+1 px line on a pixel row stays full black on both.
+
+`sk.draw` makes them, at two levels, neither with state of its own:
+
+```zig
+const ball: sk.draw.Pen = .{ .fill = .gray(127), .stroke = .black, .width = 2 };
+
+pub fn draw(s: *const State, f: *sk.Frame) void {
+ f.clear(0xffffff);
+ sk.draw.circle(f, s.position, 24, ball); // radius, not diameter
+ const pen = ball.transformed(.place(s.position, s.angle)); // push, translate, rotate
+ sk.draw.line(f, .{ 0, 0 }, .{ 24, 0 }, pen); // round ends
+ sk.draw.polygon(f, &.{ .{ 30, 0 }, .{ 26, -4 }, .{ 26, 4 } }, pen);
+}
+```
+
+A `Pen` is plain data (`fill: ?Color`, `stroke: ?Color`, `width`, `join`,
+`cap`, `xf: Affine`), so it can be a `const`, a State field, or a copy
+changed for one call. A null fill is `noFill()`, a null stroke
+`noStroke()`. `circle`, `line`, `polyline` (Processing's `beginShape()` /
+`endShape()`, open), `polygon` (`endShape(CLOSE)`), `rect` and `point` (a
+dot `width` across, Processing's `point`) tessellate into `f.scratch` and
+emit a shape for the fill and one for the stroke; out of memory, they log
+and drop it, as `emit` does. Joins are `.miter` (bevelled past 4
+half-widths), `.round` or `.bevel`, caps `.butt`, `.round` or `.square`;
+the defaults are Processing's (miter, round).
+
+```zig
+// A translucent road with round joins: each pixel blended once, joins included.
+const road: sk.draw.Pen = .{ .stroke = sk.Color.black.alpha(55), .width = 40, .join = .round };
+sk.draw.polyline(f, &s.path, road);
+```
+
+Underneath, an `sk.draw.Tessellation` is the shape as a value the caller
+owns: `fillCircle`, `strokeCircle`, `fillPolygon` (simple polygons,
+concave too), `strokePolygon`, `strokePolyline` (mitered, bevelled past 4
+half-widths), `strokeLine` (round ends), `fillRect`, `strokeRect`, and
+`strokePath(t, gpa, points, .{ .width, .join, .cap, .closed, .miter_limit
+}, xf)`, which the other strokes are, append to it with an allocator and
+an `Affine`. A round join is the circular segment beyond the bevel, a
+round cap the half disc beyond the end, so they stay disjoint like the
+rest; a square cap is a butt cap half a width further out. Emit it with `f.shape(&t, color)` or as
+`.{ .shape = ... }` yourself, put many shapes in one (1000 boids in two
+commands; a quadtree's 700 outlines and 2000 points in one), or hand
+`t.triangles(gpa)` to a GPU pass. Shapes of many
+colours share one command through `f.shapeColors(&t, colors)`, a colour
+per subpath (`t.ends`): fading particles batch too. A stroked circle is
+two subpaths, its outline and its hole, which take the same colour. `appendPoint`,
+`endSubpath` and `appendTriangle` build shapes of your own.
+
+What the functions guarantee: triangles that do not overlap, wound
+clockwise on screen (mirroring transforms included), covering exactly
+what the subpaths do. One case cannot keep it: a stroke that overlaps
+itself (a self-crossing polyline, or segments shorter than the stroke is
+wide at an acute turn) blends twice natively where it overlaps and once
+on the web. Circles get as many segments as keep them within a quarter
+pixel of round, after the transform. `tools/shapes_web.mjs` (`zig build
+test-web`) draws the same frame in headless Chrome and compares it with
+the native screenshot, pixel for pixel away from edges.
+
+## Offscreen images, blending, placed images
+
+Processing's canvas that is never cleared is an image you draw into.
+`host.newImage(w, h)` makes one, transparent; `f.target(img)` sends the 2D
+commands after it there (any of them: `sk.draw`, `fill`, `image`, `text`),
+`f.target(.none)` back to the canvas, and the image keeps what was drawn,
+frame to frame, until `f.image` shows it:
+
+```zig
+pub const Session = struct { trail: sk.Image = .none, drawn: u64 = 0 };
+
+pub fn draw(s: *const State, ss: *Session, f: *sk.Frame) void {
+ if (ss.trail == .none or f.in.jumped) {
+ if (ss.trail == .none) ss.trail = f.host.newImage(width, height);
+ ss.drawn = 0;
+ f.target(ss.trail);
+ f.clear(.white);
+ } else f.target(ss.trail);
+ while (ss.drawn < s.steps) : (ss.drawn += 1) sk.draw.circle(f, at(ss.drawn), 24, pen);
+ f.target(.none);
+ f.image(ss.trail, .{ .x = 0, .y = 0, .w = width, .h = height }, .{});
+}
+```
+
+The image is a cache in Session, never truth: after a seek or a load
+(`in.jumped`) it is repainted from State, so what a seek shows is what
+playing showed. Natively a target is supersampled whole and holds
+premultiplied colour, so it looks the same whether its steps were painted
+one a frame or all at once, and translucent edges are not darkened when
+it is drawn. A frame starts on the canvas.
+
+`f.blend(.add)` adds what follows (colour times alpha, and alpha: canvas
+`lighter`; natively a custom SDL blend, since SDL's `ADD` keeps a
+transparent target's alpha), `f.blend(.alpha)` goes back. It applies to
+`fill`, shapes and images; `clear` and `text` ignore it. Each frame starts
+with `.alpha`. There is no `multiply`: SDL's differs from the canvas's for
+translucent colours, and images have no fixed-function equivalent.
+
+`f.imageAt(img, xf, .{})` is `imageMode(CENTER)` under a transform: the
+image centred on `xf`'s origin, along its axes (`.translate(x, y)`,
+`.place(at, radians)`), at its own size or `.size`. Underneath,
+`Command.image.corners` places an image anywhere an affine can. A tint
+multiplies colour per channel and alpha as a whole, alike on both hosts
+(the web multiplies the pixels itself, cached per tint, as canvas
+compositing cannot where an image is translucent). Natively images sample
+nearest; the web antialiases a turned image's edges.
+
+## Math, time and lists
+
+`sk.math` is the geometry the `vector` module uses too (`vector.geom`):
+`Vec = @Vector(2, f32)`, so `+`, `-`, `*` and `+=` work on points as on a
+shader's `vec2`; free functions; `Affine` transforms; cubic Béziers; and
+noise. Processing's PVector, by name:
+
+| PVector | `sk.math` |
+| --- | --- |
+| `add`, `sub`, `mult` by a vector | `a + b`, `a - b`, `a * b` |
+| `mult(k)`, `div(k)` | `scale(a, k)`, `scale(a, 1 / k)` |
+| `mag()` | `length(a)` |
+| `normalize()` | `normalize(a)` (zero stays zero) |
+| `setMag(m)` | `withLength(a, m)` |
+| `limit(m)` | `clampLength(a, m)` |
+| `heading()` | `angle(a)` (radians; not in shader code, `atan2` uses tables) |
+| `PVector.fromAngle(r)` | `unit(r)` |
+| `dist(b)` | `distance(a, b)` |
+| `dot(b)`, `cross(b)` | `dot(a, b)`, `cross(a, b)` (the z of the 3D cross) |
+| `lerp(b, t)` | `mix(a, b, t)` |
+| `translate(p); rotate(r)` | `Affine.place(p, r)`, or `.translate(x, y).mul(.rotate(r))` |
+| `random(lo, hi)` | `uniform(rng, lo, hi)` |
+| `PVector.random2D()` | `randomUnit(rng)` |
+
+`sk.math.noise(seed, x, y, z)` is smooth noise in 0..1 like Processing's
+`noise()` (four octaves, each half the last): gradient noise on a hashed
+lattice, no table, so the seed can live in State. Unused axes are 0. Its
+spread is Processing's (a deviation of about 0.11, nearly all of it in
+0.1..0.9, so `noise → angle` turns all the way round), and integer
+inputs are not special: each octave is offset off the lattice. It gives
+the same bits natively and on wasm32 (a golden-value test runs on both).
+For random numbers keep a concrete `std.Random.Xoshiro256` in State (not
+`DefaultPrng`, an alias that may change) and pass `s.rng.random()`;
+`uniform(rng, lo, hi)` is `std.math.lerp(lo, hi, rng.float(f32))` by
+another name, and `std.Random` has the rest (`floatNorm`,
+`uintLessThan`).
+
+`sk.Clock` steps a simulation at a fixed rate from the recorded ticks:
+`clock: sk.Clock = .{ .hz = 60 }` in State, `for (0..s.clock.steps(in)) |_|
+step(s);` in `update`. It owes at most 8 steps per tick and drops the rest
+after a stall; `count` is the steps taken; `set clock.hz 30` is slow
+motion. A frame of N ticks steps exactly as N frames of one. It counts
+integer nanoseconds and allows an eighth of a step either way, so at the
+display's rate it steps once a frame, jitter and all: a 60 Hz frame is
+16 666 666 ns, a 60 Hz step 16 666 667, and 60 frames are 60 steps.
+
+`sk.List(T, capacity)` is a list for State: `buffer` and `len` (public, so
+`boids.buffer[3].pos[0]` works in the console), `slice`, `constSlice`,
+`appendBounded` (`error.OutOfMemory` when full), `orderedRemove`,
+`swapRemove`. Every method clamps `len` to the capacity, which matters
+after a reload that shrinks it. The default buffer is the element's own
+defaults, never `std.mem.zeroes` (an enum may have no 0).
+
+**Data that grows.** State is snapshotted, replayed and migrated, so it
+holds what `update` changes, at a size fixed in its type. Store is not
+snapshotted or replayed, so what is in it does not follow a seek. Three
+cases, by who needs the data:
+
+- `update` needs it: a `List` in State, sized for the worst case (the
+ quadtree's 4096 points, 32 KiB; flocking's 2048 boids).
+- Only `draw` needs it, and it follows from a few State fields: keep
+ those fields in State and the data in Session, rebuilt when they
+ change. A Koch curve's 65536 segments are a function of its
+ generation, one byte; an L-system's 89 000-character sentence of its
+ generation too. `sk.Derived(T)` is that: `if (ss.curve.stale(s.generation,
+ f.in)) rebuild(...)`; it is stale when the key changes (a click, a
+ seek, a step) and on the first frame after a reload, since new code
+ may derive it differently. A cheap derivation needs no cache at all:
+ the quadtree builds its tree in `f.scratch` every frame.
+- It is the user's work, not a function of State (a recording, a
+ document): Store.
+
+The timeline then needs nothing more: a seek changes the key like an
+update does (`sketches/noc`: `koch`, `lsystem`, `quadtree`).
+
**Sound scopes**, in the `scope` module (import `sb.modules.scope`): a
`scope.Scope` kept in Session takes samples with `push` and, once a frame,
`draw`s the views given rects for: the last seconds as a scrolling waveform
@@ -121,8 +332,9 @@ SVG parsing (the static subset Typst emits, and more) into cubic Bézier
data; flattening, stroking, dashing, trimming, clipping and morphing as
geometry; and `vector.Renderer(.gpu)` or `vector.Renderer(.cpu)`. The CPU
backend computes exact coverage and runs anywhere, wasm included. The GPU
-backend describes stencil-then-cover passes (8× MSAA, gradients in a
-shader). Both are tested against resvg (see `sketches/vecanim` in the game repository).
+backend describes one pass (8× MSAA, gradients in a shader): convex fills
+drawn directly, the rest stencil-then-cover, all batched into layers of
+non-overlapping fills, a few draws per layer whatever the shape count. Both are tested against resvg (see `sketches/vecanim` in the game repository).
**GPU work is data.** A sketch describes pipelines (shader code, vertex
layout, blend, stencil) and passes (`f.gpu(.{ .image, .pipelines, .draws,
@@ -164,31 +376,64 @@ stb_vorbis): WAV, FLAC and Ogg Vorbis, chosen by content.
- **State file.** `<name>.state` holds the live state plus 7 snapshot slots,
shared via `MAP_SHARED`. Its header carries the reflected layout, so a
layout change migrates every slot field by field, with enums matched by tag
- name, and `sketchbook-probe` can print any sketch's state.
+ name, and `sketchbook-probe` can print any sketch's state. Arrays and
+ vectors migrate element by element: the elements both layouts have, each
+ field by field, so an element type can gain a field and a capacity can
+ grow (new elements take their defaults) or shrink (the rest is dropped; a
+ count field such as `sk.List`'s `len` is kept, and `List` clamps it where
+ it is read). An array whose type is unchanged is copied whole. Files from
+ before element leaves (`SKETCH01`) are read and rewritten; a file that
+ is not a state file is refused, never truncated.
- **Store file.** `<name>.state.store` is a heap mapped at a fixed address
(`0x2000_0000_0000`, 64 GiB reserved), grown in place, locked to one
process. Power-of-two size classes with free lists in the file. Snapshots
and replays do not cover it (only `draw` and `command` change it).
- **Time travel.** Recordings, replay, seek and step work on any sketch,
- because they only need state bytes and events.
-- **Console and overlays.** `get`/`set <field path>`, snapshots, recordings and
+ because they only need state bytes and events. A recording is whole
+ frames; playback, `seek` and `step N` (frames) stop only between them.
+ Restoring a snapshot (play, seek, step, `load`) clears the pointer,
+ button and key state, and a recording begins with events that bring back
+ what was held when it started (a pointer move, a button or key down), so
+ a replay starts from the same input whatever the live pointer did since.
+ A recording carries a hash of the build that made it; `play` warns when
+ the running build differs (edited `update`, a new compiler), since the
+ replay may then diverge.
+- **Console and overlays.** `get`/`set <field path>` (`get` of a vector,
+ array or struct shows its values, in memory order), snapshots, recordings and
the memory and scope overlays come from the host; unknown lines go to the
- sketch.
+ sketch. Paths index arrays and vector lanes: `get pos[0]`,
+ `set boids.buffer[3].pos[1] 20`. `diff N` compares live state with
+ snapshot N leaf by leaf, so padding (a Debug `@Vector`'s spare lane)
+ never counts.
- **Scripts** (`--headless --fresh --script file`) drive the same routing and
frames as a player: `click`, `key`, `hold`/`release` (a key down until
- released, for modifiers), `wheel`, `type`, `console`, `expect field value`,
- `await field value` (frames until it holds, a minute at most),
- `expect-audio`, `screenshot`, `load`, `reload`, `await-reload`. A failed
+ released, for modifiers), `wheel`, `type`, `console`, `print field`
+ (to stderr, no frame: a vector, array or struct prints every value in
+ it, `{ 300, 200 }`), `expect field value`
+ (`expect pos[0] 250 ~0.5` within a tolerance; a failure prints what it
+ found),
+ `await field value [~tol]` (frames until it holds, a minute at most),
+ `expect-snapshot N` (live state equals snapshot N, leaf by leaf, printing
+ the first differences), `expect-log`/`expect-no-log text` (the console's
+ recent lines), `expect-audio`, `screenshot`,
+ `expect-same-screenshot a b [max [x y w h]]`,
+ `expect-different-screenshot a b [x y w h]`, `expect-pixel file x y r g b
+ a [tol]`, `load`, `reload`, `await-reload`. A failed
`expect`, or a console line that errors (a sketch command returning an
error included), fails the script. Headless always means offscreen, even
- with `SDL_VIDEO_DRIVER` set, and GPU work still runs, into a texture.
+ with `SDL_VIDEO_DRIVER` set, and GPU work still runs, into a texture. A
+ scripted `--fresh` run works on files of its own (`<state>.<pid>`),
+ renamed to the given `--state` at exit, so two builds running the same
+ script at once do not share them.
- **GPU.** The host's 2D renderer runs on an SDL GPU device, which also
runs sketches' GPU passes. Without a GPU it falls back to any renderer.
`--profile-gpu` times every upload, dispatch and pass alone on an idle
GPU (SDL_GPU has no timestamp queries) and prints count, mean, worst and
per-frame time by `label` at exit.
- **Memory.** SDL allocations go through a leak-checking allocator; a leak
- fails the exit.
+ fails the exit. SDL's Vulkan backend leaked when `vkAllocateMemory`
+ failed and it fell back to another memory type (it happens with many
+ headless hosts at once); the build compiles that file with the fix.
## The web host
@@ -243,12 +488,45 @@ and returns plain `std.Build` objects:
| --- | --- |
| `app.addLibrary()` | the hot-reloadable shared library |
| `app.addExecutable()` | host and sketch linked into one binary |
-| `app.addWeb(.{ .assets = ... })` | the wasm module and a ready-to-serve directory, built from the app's modules with every shader module swapped for its WGSL twin; tests can read its state by path with `sk_field` (numbers) and `sk_tag` (enum tag names) |
+| `app.addScriptExecutable()` | the same, built in `script_optimize` mode, as `e2e` plays scripts with |
+| `app.addWeb(.{ .assets = ... })` | the wasm module and a ready-to-serve directory, built from the app's modules with every shader module swapped for its WGSL twin; tests can read its state by path (indices too: `list[2].x`) with `sk_field` (numbers) and `sk_tag` (enum tag names) |
| `app.addServe(install)` | `miniserve` serving an installed web directory over https, on every interface, with a self-signed certificate made once by `openssl`: https makes the page a secure context on any device, which WebGPU and the microphone need. Its defaults are environment variables, so miniserve options after `--` replace them |
| `app.addRun(lib, .{})` | the generic host running the installed library |
| `app.addScript(exe_or_lib, file, .{})` | a headless, fresh-state scripted run, of the executable or of the library through the host (so the script can `reload` it) |
| `app.addProbe(state)` | the probe on a state file |
| `app.addTest(.{})` | tests with the app importable as `app` |
+| `app.addReloadCheck(.{ .script, .edits })` | a check that the app hot-reloads with State kept (below) |
+
+`sketchbook.init(b, .{ ..., .script_optimize = .ReleaseSafe })` builds
+the executables `e2e` plays scripts with in another mode than the rest,
+for sketches whose per-pixel loops crawl in Debug; null (the default) is
+`optimize`. Only Zig code changes mode (the host's and the app's), so it
+costs one more compile, not SDL's. A `b.option` makes it a `-D` flag.
+
+**Hot reload, checked.** `addReloadCheck` builds the app's library as
+written, and again from a copy of its sources with textual edits applied,
+then plays a script on the first through the generic host with `{v2}`
+defined as the second:
+
+```zig
+const check = app.addReloadCheck(.{ .script = b.path("test/reload.script"), .edits = &.{
+ .{ .file = "src/main.zig", .old = "0xff8040", .new = "0x40c0ff" },
+ .{ .file = "shaders/glsl/expo.frag", .old = "vec3(0.0, 1.0, 0.0)", .new = "vec3(1.0, 0.0, 0.0)" },
+} });
+steps.e2e.dependOn(&check.run.step);
+```
+
+Each `old` must occur exactly once in its `file` (a path as given to
+`b.path`), or the build fails. The copy is of each directory holding a
+source the app builds from (a module's root directory holds what it
+imports), and every module and shader set made from it (`addShaders`,
+`addZigShaders`) is made again from the copy, so edits to Zig code, GLSL
+and Zig shaders all reach the second library. The script plays, checks
+State, runs `load {v2}`, checks the same State, and compares screenshots
+(`expect-different-screenshot a.png b.png [x y w h]`). Pausing a replay
+first (`record`, `play`, `pause`) keeps the State still, so the two
+screenshots differ only by the edit. `sketches/shaders` and
+`sketches/noc` (bouncing_ball) have one each.
Shaders:
@@ -277,9 +555,25 @@ write-only storage buffers and no `coherent`: write them plain, or under
what includes it. `addGlslLayouts` and `addGlslc` are the pieces, for
anything else.
+Shaders can be Zig too: `sb.addZigShaders(.{ .sources, .imports })`, one
+shader per file with `export fn main() callconv(.{ .spirv_fragment = .{} })`,
+returns the same `Shaders`, so a sketch cannot tell the language. Zig's own
+SPIR-V backend compiles each for `spirv32-vulkan` (`spirv64` asks for
+physical pointers, which naga refuses), self-hosted (through LLVM the
+object comes out empty, silently); `tools/spirv_strip.zig` then drops the
+`Aligned` operands Zig puts on every load and store, which Vulkan accepts
+and naga's reader does not; and naga translates the result for the web as
+for GLSL. Shader code cannot use table-driven `std.math` (`atan2`: call
+GLSL.std.450 through inline assembly), and a uniform struct shared with
+the CPU needs a vec2 that is `@Vector(2, f32)` only on SPIR-V and `[2]f32`
+elsewhere. `sketches/shaders` has five Book of Shaders examples in both
+languages.
+
Tools: `glslc` (shaderc, or the Vulkan SDK's) for shaders, for web builds
with shaders `naga` (`cargo install naga-cli`; found on PATH or in cargo's
-directory), and for `serve`, `miniserve` and `openssl`.
+directory), and for `serve`, `miniserve` and `openssl`. This repository's
+own tests also run `node` (noise on wasm32, under WASI) and, for `zig build
+test-web`, Chrome.
`sb.modules`, `sb.host_exe` and `sb.probe_exe` are exposed for anything else.
Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
@@ -294,6 +588,12 @@ Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
leave it inconsistent, and `--fresh` starts it over.
- Handles inside Store containers (`std.ArrayList(sk.Image)`) are not caught
at compile time: the check does not follow pointers.
+- Native antialiasing resolves coverage per sample within a run of
+ shapes, the canvas per shape, so where two shapes' edges meet the web
+ can show a faint seam native does not. `fill` rects and images are
+ antialiased natively only inside a target. Without a GPU renderer,
+ native draws aliased. A stroke that overlaps itself blends twice
+ natively where it overlaps, once on the web.
- On the web: nothing persists (Store lasts as long as the page),
synthesised voices are silent, `loadSound` knows only sounds the page
decoded, multisampling is 4× at most, and mixing runs on the main thread
@@ -315,6 +615,20 @@ a call lives in host memory, since host code is never unloaded. Only the
recorded `Event` and the reflected `Layout` are `extern`, because they are
written to disk.
-`zig build test` in this directory runs the unit tests and a headless reload
+`zig build test` in this directory runs the unit tests, a headless reload
through `dlopen`, where a counter sketch changes its layout mid-run and keeps
-its values.
+its values, and a replay test (`test/replay.script`): a recording played,
+sought, stepped and replayed after a live pointer move, each ending on the
+state it was stopped at.
+
+The drawing layer's tests are there too: the shape cases drawn natively
+and checked pixel by pixel (`test/shapes.zig`), noise's golden values on
+wasm32 under Node, and the examples in `examples/` (`pen.zig`: Pens and a
+Clock; `flock.zig`: tessellations batched by hand, between Frame
+methods). `test/render.zig` covers targets (and that `set` and `load`
+repaint them while plain frames do not), blending, placed and tinted
+images and colours per subpath, checked pixel by pixel. `zig build
+test-web` draws the shape and render cases in headless Chrome, compares
+them with the native screenshots (`tools/chrome.mjs`), and times 5000
+circles a frame (software Canvas2D here: about 12 ms as 5000 shapes, 8 ms
+batched).