1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
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.
|