Monorepo for Aesthetic.Computer
aesthetic.computer
shared/rast: Makefile + README with cross-browser compat matrix
Build targets for every shipping variant:
make test → self-tests (currently 4 green)
make native → libac_rast.a for linking into ac-native
make wasm → four modules (baseline / simd / threads / full)
README captures the integration plan, the cross-browser compat table
(what features unlock on which Safari/Firefox/Chrome versions), and the
COOP/COEP prereq for the threads+SAB parallel path. Status checklist
marks what's done and what's next so the next session doesn't need to
re-derive the plan from the commit log.
+213
2 changed files
+92
shared/rast/Makefile
+92
shared/rast/Makefile
···
1
1
+
## shared/rast — build the cross-platform rasterizer for every target.
2
2
+
##
3
3
+
## Targets:
4
4
+
## test → native test binary (gcc), runs the self-tests
5
5
+
## native → static archive (libac_rast.a) for linking into ac-native
6
6
+
## wasm → wasm modules for the web runtime (needs emscripten in PATH):
7
7
+
## raster-baseline.{wasm,js} — no SIMD, no threads
8
8
+
## raster-simd.{wasm,js} — SIMD, no threads
9
9
+
## raster-threads.{wasm,js} — threads + SAB
10
10
+
## raster-full.{wasm,js} — SIMD + threads
11
11
+
## clean
12
12
+
##
13
13
+
## Pixel output must stay identical across test / native / every wasm
14
14
+
## variant. raster_test.c exercises the correctness path; a follow-up
15
15
+
## snapshot harness (golden PNG diff) covers the richer drift catch.
16
16
+
17
17
+
CC ?= gcc
18
18
+
CFLAGS ?= -O3 -Wall -Wextra -std=c99 -fPIC
19
19
+
AR ?= ar
20
20
+
EMCC ?= emcc
21
21
+
22
22
+
RAST_SRC := raster.c
23
23
+
RAST_OBJ := raster.o
24
24
+
25
25
+
.PHONY: all test native wasm clean
26
26
+
27
27
+
all: test
28
28
+
29
29
+
# ── self-test (gcc native) ───────────────────────────────────────────
30
30
+
raster_test: $(RAST_SRC) raster_test.c raster.h
31
31
+
$(CC) $(CFLAGS) -o $@ $(RAST_SRC) raster_test.c -lm
32
32
+
33
33
+
test: raster_test
34
34
+
./raster_test
35
35
+
36
36
+
# ── static archive for ac-native link ────────────────────────────────
37
37
+
$(RAST_OBJ): $(RAST_SRC) raster.h
38
38
+
$(CC) $(CFLAGS) -c -o $@ $<
39
39
+
40
40
+
libac_rast.a: $(RAST_OBJ)
41
41
+
$(AR) rcs $@ $^
42
42
+
43
43
+
native: libac_rast.a
44
44
+
45
45
+
# ── WASM variants (emscripten) ───────────────────────────────────────
46
46
+
# Each variant exports the same C API, so the JS loader probes features
47
47
+
# and picks the best one the browser can actually run. See raster.h for
48
48
+
# the exported entry points.
49
49
+
#
50
50
+
# Build flags (same across variants for everything NOT related to the
51
51
+
# capability being toggled, so variants stay pixel-identical):
52
52
+
# -O3 — maximum inlining and loop opts
53
53
+
# -flto — link-time optimization
54
54
+
# -s STANDALONE_WASM=1 — emit a standalone module (no Emscripten JS shim)
55
55
+
# -s EXPORTED_FUNCTIONS=['_ac_rast_triangle','_ac_rast_clear']
56
56
+
# -s ENVIRONMENT='web,worker' — only ship web code paths
57
57
+
#
58
58
+
# Variant-specific flags:
59
59
+
# baseline → (none)
60
60
+
# simd → -msimd128
61
61
+
# threads → -pthread -s PTHREAD_POOL_SIZE='navigator.hardwareConcurrency'
62
62
+
# full → -msimd128 -pthread …
63
63
+
64
64
+
EMCC_COMMON := -O3 -flto \
65
65
+
-s STANDALONE_WASM=1 \
66
66
+
-s EXPORTED_FUNCTIONS='["_ac_rast_triangle","_ac_rast_clear","_malloc","_free"]' \
67
67
+
-s EXPORTED_RUNTIME_METHODS='["HEAPU8","HEAPU32","HEAPF32"]' \
68
68
+
-s ENVIRONMENT='web,worker' \
69
69
+
-s ALLOW_MEMORY_GROWTH=1 \
70
70
+
-s MALLOC=emmalloc
71
71
+
72
72
+
raster-baseline.wasm: $(RAST_SRC) raster.h
73
73
+
$(EMCC) $(EMCC_COMMON) -o $@ $(RAST_SRC)
74
74
+
75
75
+
raster-simd.wasm: $(RAST_SRC) raster.h
76
76
+
$(EMCC) $(EMCC_COMMON) -msimd128 -o $@ $(RAST_SRC)
77
77
+
78
78
+
raster-threads.wasm: $(RAST_SRC) raster.h
79
79
+
$(EMCC) $(EMCC_COMMON) -pthread \
80
80
+
-s USE_PTHREADS=1 -s PTHREAD_POOL_SIZE=8 \
81
81
+
-o $@ $(RAST_SRC)
82
82
+
83
83
+
raster-full.wasm: $(RAST_SRC) raster.h
84
84
+
$(EMCC) $(EMCC_COMMON) -msimd128 -pthread \
85
85
+
-s USE_PTHREADS=1 -s PTHREAD_POOL_SIZE=8 \
86
86
+
-o $@ $(RAST_SRC)
87
87
+
88
88
+
wasm: raster-baseline.wasm raster-simd.wasm raster-threads.wasm raster-full.wasm
89
89
+
90
90
+
clean:
91
91
+
rm -f raster_test $(RAST_OBJ) libac_rast.a \
92
92
+
raster-baseline.* raster-simd.* raster-threads.* raster-full.*
+121
shared/rast/README.md
+121
shared/rast/README.md
···
1
1
+
# shared/rast — cross-platform triangle rasterizer
2
2
+
3
3
+
One C99 triangle rasterizer used by both **ac-native** (fedac/native) and the
4
4
+
**web runtime** (system/public/aesthetic.computer). Same pixel output on both
5
5
+
platforms — no more drift between what a piece looks like in a browser and
6
6
+
what it looks like on bare metal.
7
7
+
8
8
+
## Why
9
9
+
10
10
+
Before this, arena.mjs (and other 3D pieces) ran through two completely
11
11
+
independent rasterizers — `graph.mjs`'s JS triangle path on web, and
12
12
+
`graph3d.c`'s software rasterizer on native. Both implementations had to be
13
13
+
maintained in parallel and drifted in subtle ways: different pixel coverage
14
14
+
rules, different near-plane behaviour, different color precision. The fix
15
15
+
is structural: one source of truth, multiple build targets.
16
16
+
17
17
+
## Source
18
18
+
19
19
+
- `raster.h` — public API (pixel format, vertex struct, options, entry points)
20
20
+
- `raster.c` — implementation (~180 lines, pure C99, no libc allocs on the
21
21
+
hot path, no mutable globals — fully re-entrant so worker threads can
22
22
+
rasterize independent tiles against shared framebuffers)
23
23
+
- `raster_test.c` — self-tests (solid fill, perspective-correct color
24
24
+
interpolation, depth occlusion, scissor clipping)
25
25
+
26
26
+
## Build
27
27
+
28
28
+
make test # run self-tests (gcc)
29
29
+
make native # libac_rast.a for linking into ac-native
30
30
+
make wasm # four WASM variants for the web runtime (needs emcc)
31
31
+
make clean
32
32
+
33
33
+
The `wasm` target emits four modules with progressive feature sets. The
34
34
+
web loader probes browser capability and picks the best one available:
35
35
+
36
36
+
| Variant | Tradeoff |
37
37
+
|---|---|
38
38
+
| `raster-baseline.wasm` | ubiquitous; 2-3× faster than current JS |
39
39
+
| `raster-simd.wasm` | needs WASM SIMD (Chrome 91+, FF 89+, Safari 16.4+); 4-6× |
40
40
+
| `raster-threads.wasm` | needs SharedArrayBuffer (COOP+COEP on server); 8-15× |
41
41
+
| `raster-full.wasm` | SIMD + threads; 20-40× on multicore desktops |
42
42
+
43
43
+
See the [compatibility matrix](#cross-browser-support) below.
44
44
+
45
45
+
## Integration status
46
46
+
47
47
+
- [x] Pure-C rasterizer + self-tests
48
48
+
- [x] Makefile for native + wasm build targets
49
49
+
- [ ] Wire into `fedac/native/src/graph3d.c` (replace `rasterize_triangle`)
50
50
+
- [ ] emcc build variants produced + smoke-tested via wasmtime or node
51
51
+
- [ ] JS loader in `system/public/aesthetic.computer/lib/graph.mjs` that
52
52
+
probes caps and instantiates the best module
53
53
+
- [ ] Replace `graph.mjs`'s JS triangle inner loop with a WASM call
54
54
+
- [ ] Golden PNG snapshot diff in CI (catches any drift between variants)
55
55
+
- [ ] Tile-binning + multi-worker pipeline (unlocks `threads`/`full` variants)
56
56
+
57
57
+
## Cross-browser support
58
58
+
59
59
+
Graceful fallback — every current browser gets at minimum the baseline
60
60
+
WASM (2-3× faster than today's JS). Better variants unlock automatically:
61
61
+
62
62
+
| Feature | Chrome/Edge | Firefox | Safari |
63
63
+
|---|---|---|---|
64
64
+
| Baseline WASM | 57+ (2017) | 52+ (2017) | 11+ (2017) |
65
65
+
| SharedArrayBuffer | 68+ (2018, isolated 91+) | 79+ (2020) | 15.2+ (Dec 2021) |
66
66
+
| Atomics | same as SAB | same | same |
67
67
+
| WASM SIMD (128-bit) | 91+ (2021) | 89+ (2021) | 16.4+ (Mar 2023) |
68
68
+
| WASM threads | same as SAB | same | same |
69
69
+
70
70
+
### Hosting prerequisites for the parallel path
71
71
+
72
72
+
The server must send these headers to enable `crossOriginIsolated`:
73
73
+
74
74
+
Cross-Origin-Opener-Policy: same-origin
75
75
+
Cross-Origin-Embedder-Policy: require-corp
76
76
+
77
77
+
The docs route already does this (see `system/netlify/functions/docs.js`).
78
78
+
Extending to the piece-hosting routes is a separate commit. If third-party
79
79
+
iframes (YouTube, Spotify, arbitrary user URLs) need to still work, use
80
80
+
`COEP: credentialless` instead of `require-corp` — same isolation, fewer
81
81
+
embedding breakages.
82
82
+
83
83
+
## Pixel format
84
84
+
85
85
+
All framebuffers use `uint32_t` per pixel packed as:
86
86
+
87
87
+
(A << 24) | (R << 16) | (G << 8) | B
88
88
+
89
89
+
Matches `graph3d.c`'s existing convention and web's `Uint32Array` view over
90
90
+
a `Uint8ClampedArray`. The `AC_RAST_PACK(a,r,g,b)` macro constructs one.
91
91
+
92
92
+
## Depth buffer
93
93
+
94
94
+
32-bit float per pixel, parallel to the color buffer. Lower values =
95
95
+
closer to camera (matching `graph3d.c` but inverted from WebGL's default
96
96
+
— callers that pass post-perspective-divide Z in `[-1,+1]` should negate
97
97
+
before calling if they want standard z-buffer semantics).
98
98
+
99
99
+
Modes:
100
100
+
101
101
+
- `AC_RAST_DEPTH_RW` — read + write (standard opaque pass)
102
102
+
- `AC_RAST_DEPTH_READONLY` — read only (transparent / overlay pass)
103
103
+
- `AC_RAST_DEPTH_NONE` — no test / no write (painter's-order fallback,
104
104
+
also what pieces without a depth buffer at all use)
105
105
+
106
106
+
## Parallelism plan
107
107
+
108
108
+
The rasterizer is designed so each triangle call is independent. A tile
109
109
+
binner — not yet implemented here — will:
110
110
+
111
111
+
1. Split screen into 64×64 tiles
112
112
+
2. Transform all vertices on the main thread
113
113
+
3. Bucket each triangle into the tiles it covers
114
114
+
4. Dispatch tiles to a worker pool (Web Workers on web, pthreads on native)
115
115
+
5. Each worker rasterizes its tiles using `ac_rast_triangle` with a
116
116
+
scissor rect set to the tile bounds
117
117
+
6. Main thread waits on a completion counter, flips buffers, presents
118
118
+
119
119
+
Workers never touch each other's tiles, so no locking is needed beyond
120
120
+
the submit/complete atomics. SharedArrayBuffer holds the color + depth
121
121
+
backing store; workers write with normal pointer ops.