nordisk/facett

The render engine — for idiots

Class: idiot. Every step, nothing assumed. Goal: from a cold shell, prove the render kernel actually draws — run its tests, see them green, and (if your machine has a GPU) watch the GPU and CPU lanes agree. If you already know Rust, read render-guide.md instead — this one spells out every keystroke.

What you need first

• A terminal (the black window where you type commands).
• Rust installed. Check it — type this and press Enter:

cargo --version

If that prints a version, you're fine. If it says "command not found", install Rust from https://rustup.rs first, then come back.

• The facett repo on disk. In the terminal, type this and press Enter:

cd /run/media/rickard/T9/git/facett

Step 1 — build the render kernel

The CPU renderer is always compiled — no GPU needed. Type and press Enter:

cargo build -p facett-core

Text scrolls by. Wait for it to finish. If the last line is Finished, the kernel built. Red text = an error; read what it names and fix that, then run it again until it's quiet.

Step 2 — run the CPU render tests (no GPU, always works)

These prove the CPU lane rasterizes real circles, rings, markers, and lines. Type and press Enter:

cargo test -p facett-core render::cpu

Watch the last line. test result: ok. N passed (a green-ish line) = the CPU renderer draws. One of those tests, parallel_raster_matches_sequential, proves the multi-core raster produces the exact same pixels as a single thread — the picture is identical no matter how many cores ran it.

Step 3 — run the shared coverage-math tests

The shape math (what makes a circle a circle) is one set of functions that BOTH the CPU and the GPU use. Type and press Enter:

cargo test -p facett-core render::cpu::sdf

Green = the coverage math is correct (a circle is lit inside its radius and dark outside, a ring has a hole, a line matches its width). This is the "source of truth" both drawing lanes copy.

Step 4 — run the pixel oracle tests

A render test must look at the pixels, not just check "something got drawn". This module is the eye. Type and press Enter:

cargo test -p facett-core imgscan

Green means the analyzer can tell a clean picture (solid filled shapes) apart from a smeared one (thin lines shooting out from the centre — a real bug that once shipped). If it can separate those two, it can catch that bug.

Step 5 — try the GPU lane (only if your machine has a working GPU)

The GPU lane sits behind a build feature called wgpu. Turn it on. Type and press Enter:

cargo test -p facett-core --features wgpu render::gpu

Two things can happen, both fine:

• You have a GPU: the tests actually run on it and draw. Green = the GPU lane works, and the CPU↔GPU parity test proved the two lanes make matching pictures.
• You have no usable GPU (a plain server, a sandbox): the tests print a line like no GPU adapter — skipping and pass anyway. That is on purpose — the GPU is never required; the CPU lane covers you.

Either way, the last line should be test result: ok.

Step 6 — force the CPU lane on purpose

Even on a GPU machine you can make the kernel pick the CPU lane (useful for a repeatable picture). Type and press Enter:

FACETT_RENDER_CPU=1 cargo test -p facett-core render::backend

That environment variable is read by the backend picker. Green = the picker honoured it and chose CPU. This is the same switch the design describes: probe once, decide once, draw once.

Step 7 — run the whole render subsystem at once

To sweep everything — CPU lane, coverage math, backend picker, camera, layers, decorations, edges, effects, the pixel oracle — type and press Enter:

cargo test -p facett-core

Add the GPU and beauty lanes too, if your machine can:

cargo test -p facett-core --features "wgpu l1-vello"

A final test result: ok across the board = the render engine is proven end to end on your machine, and the GPU/vello lanes either ran for real or cleanly skipped.

What you just proved

• The renderer draws real shapes to pixels with no window open.
• The multi-core path makes the same picture as one core.
• The CPU and GPU lanes share one shape math, so they agree.
• A test can see the picture (the pixel oracle), not just guess it drew.
• The GPU and beauty layers are optional — the base always works.

That's the render kernel, exercised cold. If a step went red, the failing test names exactly which piece broke; fix that one thing and re-run the same command.