Ole-Morten Duesund
f8b7ff475c
Preserves Andrew Kensler's original card.cc verbatim and adds: - CMakeLists.txt building both the original and a de-obfuscated variant (card_explained.cc) that produces a visually identical render - A heavily annotated rewrite explaining the vector ops, ray-sphere intersection, soft shadows, depth of field, and reflection recursion - Rendered sample output (docs/aek.png) embedded in the README - CLAUDE.md establishing the "never modify card.cc" rule for future work
52 lines
2.1 KiB
Markdown
52 lines
2.1 KiB
Markdown
# card-raytracer — project notes for Claude
|
|
|
|
This repo is a small study of Andrew Kensler's "business card raytracer".
|
|
The point of the project is **preservation + explanation**, not extension.
|
|
|
|
## The sacred rule
|
|
|
|
**`card.cc` must never be modified.** It is a historical artifact, ~1337
|
|
characters of obfuscated C++ that fits on a real business card. Any cleanup,
|
|
formatting, comment, or "fix" goes into `card_explained.cc` instead.
|
|
|
|
If a compiler warning or modern-C++ issue appears against `card.cc`, the
|
|
answer is always a CMake flag adjustment (e.g. silencing warnings), never
|
|
an edit to the source.
|
|
|
|
## Layout
|
|
|
|
| File | Role |
|
|
|---|---|
|
|
| `card.cc` | Original, golfed, untouched. Read-only by convention. |
|
|
| `card_explained.cc` | De-obfuscated rewrite with full names and comments. Same visual output. |
|
|
| `CMakeLists.txt` | Builds both binaries; provides `image` and `image_explained` render targets. |
|
|
| `docs/aek.png` | Published render used by the README. Regenerate after meaningful changes. |
|
|
| `README.md` | Human-facing description with the embedded render. |
|
|
|
|
## Build & render
|
|
|
|
```sh
|
|
cmake -S . -B build
|
|
cmake --build build # builds both binaries
|
|
cmake --build build --target image # → build/aek.ppm
|
|
cmake --build build --target image_explained # → build/aek_explained.ppm
|
|
```
|
|
|
|
Convert PPM → PNG (for README, etc.) with `pnmtopng build/aek.ppm > docs/aek.png`.
|
|
|
|
## Conventions
|
|
|
|
- `card_explained.cc` is built with `-Wall -Wextra` and should stay
|
|
warning-clean. `card.cc` is built with `-w` because we can't edit it.
|
|
- C++14, no external dependencies beyond `libm`.
|
|
- The de-obfuscated version preserves the **same `rand()` call sequence** as
|
|
the original so the rendered image is visually identical. Don't reorder
|
|
the `randf()` calls inside `shade()` or the per-sample loop in `main()`
|
|
without re-checking the output.
|
|
|
|
## Remote
|
|
|
|
Hosted on Forgejo: `ssh://git@kode.naiv.no:2222/olemd/card-raytracer.git`.
|
|
Per global instructions, use the `forgejo` skill (invoke via `/forgejo`) and
|
|
the `fj` CLI for any repository interactions (PRs, issues, releases, etc.).
|
|
Never use `gh` for this repo.
|