summaryrefslogtreecommitdiff
path: root/examples/noc/notes/impl-render-features.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-16 21:28:20 -0300
committerGabriel Schneider <[email protected]>2026-11-16 21:28:20 -0300
commit6933f99ddb2d7103515d26838496309a807bba26 (patch)
tree991c2fe7d4a57957222876e190fa4d16a0fb889c /examples/noc/notes/impl-render-features.md
parent82fca5c9f29124f37f6dcd08e73e6999ce44a69d (diff)
downloadsketchbook-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.md201
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.