# 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.