diff options
| author | Gabriel Schneider <[email protected]> | 2026-11-16 21:28:20 -0300 |
|---|---|---|
| committer | Gabriel Schneider <[email protected]> | 2026-11-16 21:28:20 -0300 |
| commit | 6933f99ddb2d7103515d26838496309a807bba26 (patch) | |
| tree | 991c2fe7d4a57957222876e190fa4d16a0fb889c /examples/noc/notes/impl-render-features.md | |
| parent | 82fca5c9f29124f37f6dcd08e73e6999ce44a69d (diff) | |
| download | sketchbook-6933f99ddb2d7103515d26838496309a807bba26.tar.gz sketchbook-6933f99ddb2d7103515d26838496309a807bba26.zip | |
Move standalone sketches into sketchbook examples
Diffstat (limited to 'examples/noc/notes/impl-render-features.md')
| -rw-r--r-- | examples/noc/notes/impl-render-features.md | 201 |
1 files changed, 201 insertions, 0 deletions
diff --git a/examples/noc/notes/impl-render-features.md b/examples/noc/notes/impl-render-features.md new file mode 100644 index 0000000..31f1e5c --- /dev/null +++ b/examples/noc/notes/impl-render-features.md @@ -0,0 +1,201 @@ +# Phase 3, render-features: as shipped + +Offscreen targets and `Input.jumped`, blend modes, placed and tinted +images, native antialiasing for `shape`, colours per subpath, and two +small API fixes. Each feature came with an example in sketches/noc, +written from scratch on the new API. Paths are relative to +`lib/sketchbook/` unless they start with `sketches/`. + +## API added + +```zig +// ---- abi (L0) ---- +pub const BlendMode = enum(u8) { alpha, add }; +pub const Corners = struct { top_left: [2]f32, top_right: [2]f32, bottom_left: [2]f32 }; +pub const MouseButton = enum(u16) { left = 1, middle = 2, right = 3, _ }; // for lib-features +Command.target: Image // 2D commands after it draw into the image; .none = canvas +Command.blend: BlendMode // for rect, shape, image; clear and text ignore it +Command.shape.colors: []const Color = &.{} // one per subpath (ends); empty = `color` +Command.image.corners: ?Corners = null // any affine placement; dst unused then +Input.jumped: bool // draw only: State did not get here by update +Input.mouseHeld(button) bool, mousePressed(button) ?Event, mouseReleased(button) ?Event +Color.alphaFloat(c, a: f32) Color // a in 0..1, saturating (negative lifespans: 0, NaN: 0) + +// ---- sk.Frame ---- +pub fn target(f, img: Image) void +pub fn blend(f, mode: BlendMode) void +pub fn imageAt(f, img: Image, xf: math.Affine, options: struct { src: Rect = .{}, size: ?[2]f32 = null, tint: Color = .white }) void +pub fn shapeColors(f, t: *const draw.Tessellation, colors: []const Color) void +// colour params of clear/fill/image tint/text/print also take Color constants by name: f.clear(.white) +// re-exported: sk.BlendMode, sk.MouseButton (and lib-features' sk.Derived) +``` + +No new vtable entry: `host.newImage` images are the targets. + +Tests and tools: `test/render.zig` + `test/render.script` (in `zig build +test`), `tools/render_web.mjs` (in `zig build test-web`), +`tools/chrome.mjs` (the headless-Chrome harness and page-side compare, +now shared with `tools/shapes_web.mjs`). + +Examples (sketches/noc, `// phase 3: render-features` in build.zig): +`smoke` (4.8), `additive_blending` (4.9), `recursive_tree` (8.6), each +with a behaviour script, timeline script and reload check; +`random_walk` and `noise_walker` rewritten on targets; +`src/trail.zig` deleted; `assets/texture.png` with `assets/README.md` +(MIT, The Nature of Code). + +## Decisions + +- **Targets are images.** `newImage` now makes an SDL render-target + texture (it was streaming), cleared to transparent at once, since a new + SDL texture is undefined and a canvas starts clear. `pixels` still + uploads into it (SDL's GPU renderer updates target textures through a + transfer buffer). The web already backed `newImage` with a canvas: a + target switches `ctx` to that canvas's context. A frame starts on the + canvas with `alpha` blend on both hosts, and switching target clears the + clip on both. GPU-pass images and loaded PNGs are not targets (ignored). +- **Premultiplied natively** (critique-core §2.4 (1)). Drawing straight + colour with SDL `BLEND` into a transparent texture stores premultiplied + colour, so targets are drawn with `BLEND_PREMULTIPLIED`. SDL's alpha mod + does not scale the colour of a premultiplied texture, so the host + scales the colour mod by the tint's alpha itself (this also fixes tinting + GPU-pass images). A target `clear` premultiplies its colour, as a canvas + cleared with `copy` holds it. +- **`jumped`** is a Host flag set by: the first frame; any snapshot + restore (`Timeline.restored`: play, seek, step, load, record); any + successful console line except `help overlay get snapshot recording + diff stop pause save quit exit` (so `set`, `reset`, sketch commands, + `f.run` lines); and every reload (it is or-ed with `reloaded`). Only + `draw` sees it. On the web it is the first frame. Checked by + test/render.script: `set` and `load` repaint, plain frames and `get` do + not. +- **Blend.** `add` is colour times alpha plus destination, and alpha plus + alpha: canvas `lighter` exactly, natively `SDL_ComposeCustomBlendMode + (SRC_ALPHA, ONE, ADD, ONE, ONE, ADD)` (`ONE` source for premultiplied + textures). SDL's `ADD` would keep a transparent target's alpha + (critique-core). **No `multiply`:** E10 holds (SDL's `MUL` brightens + under translucent white where canvas leaves the backdrop). The vertex + colour could be premultiplied for shapes, but images have no + fixed-function equivalent, inside a supersampled layer it would not + associate, and no example needs it. `clear` and `text` ignore the blend + on both hosts (the web wraps text in `source-over`). +- **Image placement** is three corners, not an `Affine` in abi (abi does + not import `math`): native `SDL_RenderTextureAffine`, web the unit + square mapped by `ctx.transform` and `drawImage(..., 0, 0, 1, 1)`. + `f.imageAt` builds the corners from an `Affine` centred on the image + (`imageMode(CENTER)`), at the image's size from `host.imageSize` (zero + while the web is still loading it: nothing drawn). +- **Exact tint on the web.** Canvas compositing (multiply then + destination-in) gives (1−α)·tint + α·src·tint at translucent pixels, + where SDL gives src·tint. The web now multiplies the pixels + (`getImageData`) into a scratch canvas per image, cached by tint RGB, + region and an image version (bumped by `pixels` and by drawing into + it). Tint alpha is `globalAlpha`, so 4.9's fading tint costs nothing. + GPU-pass images keep the compositing path (they change every frame and + cannot be read back cheaply); it is exact where they are opaque. +- **Native antialiasing: supersampling, 4x4 samples a pixel.** Only a GPU + renderer; without one native stays aliased. Averaging is two halvings, + each a bilinear sample at the centre of a 2x2 block (their exact mean). + If 16 samples a pixel would exceed 16 Mi samples, 2x2; beyond that, none. + - On the canvas, consecutive shapes of one blend share a layer: a + canvas-sized x4 texture (`layer.big`), drawn at render scale 4 from + transparent, then averaged and composited premultiplied when any other + command comes. Only the union of the shapes' bounds is cleared, + averaged and composited. + - A target is supersampled whole (`Entry.big`, x4, render scale 4 in its + own SDL view). Everything drawn into it goes there; `texture` is its + average, brought up to date when the image is drawn (`stale`). + - Why targets whole and not per command: a first version composited + every shape alone (exactly the canvas's per-shape coverage), batching + only shapes whose pixels could not touch. That makes batching + invisible, but the recursive tree's ~1000 touching lines then cost + ~1000 layers, 3 render passes each: ~400 ms a frame. Plain batching + (all consecutive shapes in one layer) is fast, but resolves coverage + per sample, so a trail painted one step a frame (one composite per + step) differed from the same trail repainted at once after a seek (by + up to 145 at overlapping circle edges; noise_walker's timeline check 7 + failed). Supersampling the target itself makes its picture + independent of how commands split into frames, bit for bit, and keeps + the canvas batched. The tree draws in ~5 ms a frame (Debug, loaded + machine), down from ~400. + - The difference left from the web: within a run of shapes, coverage + resolves per sample natively and per shape on the canvas, so where two + shapes' edges meet the web can show a faint conflation seam that + native does not. Measured below. + - The window: the layer is at canvas resolution x4 and its last halving + is drawn to the canvas rect, so with a HiDPI window the final draw + samples a x2 texture (still sharp at 2x output scale). +- **Colours per subpath.** Native expands them into a per-vertex + `SDL_FColor` array in the frame arena (points of subpath i get + `colors[i]`) for one `SDL_RenderGeometryRaw` call; the web sets the fill + style per group from the group's first subpath. A group (an outline and + its holes) and its triangles must share a colour; documented on + `Command.shape` and `f.shapeColors`. +- **Decl-literal colours.** Frame's colour params stay `anytype` (so + `0x202020` and duck-typed structs keep working); an enum literal is + looked up among `Color`'s declarations (`f.clear(.white)`, `.black`). + `.gray(220)` cannot work through `anytype` (no result type); it needs + `sk.Color.gray(220)`, as documented. +- **Gaussian random** is `rng.random().floatNorm(f32)` from State's + `Xoshiro256`, as research-zig verified deterministic across targets. +- **system_of_systems** now uses `alphaFloat` (the clamp and + `@intFromFloat` are gone). It keeps one Pen circle per particle: with + `shapeColors` its draw would batch but get longer, so I left it; the + render test exercises `shapeColors` on both hosts instead. + +## Parity results (native headless vs headless Chrome, same frame) + +- `test/render.zig` (targets plain, half-transparent and turned; add + over gray of shapes, a rect and a tinted soft image; three circles and a + ring in one command; a soft `pixels` image plain, tinted, turned; a fan + of 1 px lines): of 103063 pixels away from edges, 0 differ by more than + 3 (worst 3). Next to edges (16937): mean difference 1.8, 493 over 16, 14 + over 48 (the turned images: canvas antialiases a turned `drawImage`, + SDL samples nearest). +- `test/shapes.zig` (draw-layer's cases): 150050 away from edges, worst + 0; next to edges (9950) mean 0.9, 4 over 16, 0 over 48. Before, native + edges were aliased. The 1 px line stays 0,0,0 on its row on both. +- Sampled: tinted target 127 vs 126; add 192,255,64 both; tinted soft + image 139,73,155 vs 139,73,156. + +## Tests + +- `zig build test` (lib): `test/render.script` checks pixels (target, + premultiplied tint, turned target, add, colours per subpath, the ring + hole), and `jumped`: `set` repaints, `get` and plain frames do not, a + snapshot `load` does. shapes.script passes unchanged with AA on. +- `zig build test-web`: render parity passes. shapes' 5000-circle timing + is 16.8–18.7 ms against its 16 ms budget on this machine at load ~20 + (other agents' builds); draw-layer measured 12 ms idle. The parity part + passes. +- sketches/noc, for each of smoke, additive_blending, recursive_tree: + behaviour script with screenshots I looked at next to the Processing + sketch (the smoke plume drifting with the wind arrow; the magenta glow + saturating to white where particles crowd, 255 vs 4.8's 244; the tree at + the pointer's angle, straight at the left edge), pixel checks (the arrow + at half intensity on two rows, antialiased branch edges natively); + timeline script from the template with pointer moves, including + screenshot after seek equals live; reload check (orange smoke, blue + glow, green tree) with State equal across `load {v2}`. +- random_walk and noise_walker: their timeline scripts pass check 7 + (seek end and seek start + step all equal the played screenshot, bit + for bit) now from a target. noise_walker.script: a snapshot load + repaints to the loaded step and equals a straight run. Values updated + for lib-features' Clock slack (one more step). + +## What's left + +- `multiply` (see Decisions). Possible for shapes and rects alone, one + layer per command; not for images. +- Native rects and images on the canvas are not antialiased (inside a + target they are, being supersampled). A fractional `fill` rect shows it. +- Coverage per sample vs per shape (the faint web seam where shapes meet). +- A self-overlapping translucent stroke still blends twice natively. +- Targets cost 17x their size natively (x4 samples plus the average); + drawing a target into another target, or tinting it, works but was only + tested plain, tinted and turned onto the canvas. +- `f.target` into a GPU-pass image is ignored; sampling a 2D target in a + GPU pass is not supported (critique-core's ordering hazard (5)). +- The web `clear` of the canvas still respects the clip, native's does + not (pre-existing). +- The 5000-circle web budget should be rechecked on an idle machine. |
