Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -157,6 +157,10 @@ part was built.
`4k-fixed-point`, `canyon`, `4k-canyon`, `test`, `nondeterminism`, `clippy-bans`,
`doc-links`, `help`) over the container runner. (flyingrobots/lumen#17, #23, #25, #40, #104,
#115.)
- **All graphics in Bunny, decided** ([ADR 0016](docs/adr/0016-graphics-in-bunny.md)): Bunny
defines reusable graphics evaluation, integrators included; Lumen supplies inputs, selects
contracts, schedules work and records results. Debug views and image decoding stay in Lumen.
Nothing is built yet: the diffuse integrators are still Lumen's. (flyingrobots/lumen#275.)
- **The command's interface, decided** ([ADR 0015](docs/adr/0015-command-interface.md)): a job
file in, an output directory, versioned JSON Lines on standard output and on standard error, and
published JSON Schemas; the key-value report is to be retired. Nothing is built yet.
Expand Down
1 change: 1 addition & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,7 @@ sections, never rewrites.
| [0011](adr/0011-analytic-surfaces-lights-and-lens.md) | Analytic surfaces, point lights and the thin lens: arithmetic in Bunny, scene model in Lumen | accepted (2026-11-15) |
| [0012](adr/0012-image-decoding.md) | Image decoding lives in a dependency-free `lumen-image` crate | accepted |
| [0015](adr/0015-command-interface.md) | The command's interface: job files in, JSON Lines out, published schemas | accepted (recorded 2026-11-15) |
| [0016](adr/0016-graphics-in-bunny.md) | All graphics in Bunny, the integrators included | accepted (2026-11-17) |

## Measurement records

Expand Down
5 changes: 5 additions & 0 deletions docs/adr/0010-debug-views.md
Original file line number Diff line number Diff line change
Expand Up @@ -158,3 +158,8 @@ golden hashes and hand-derived tests.
- The default output, the lit provenance and every existing golden hash are unchanged: `lit` is
the old render by construction, and the tests check the provenance field for field and the
golden hash through `render_view`.

## Clarification, 2026-11-17: ADR 0016

ADR 0016 moves graphics evaluation, integrators included, to Bunny. It keeps this decision as an
explicit exception, unchanged; see its section "Exceptions, with their reasons".
5 changes: 5 additions & 0 deletions docs/adr/0012-image-decoding.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,3 +90,8 @@ reproducible if Lumen states the arithmetic that produced the pixels.
| Decoders in Bunny's codec crate | Bunny holds math and mesh formats, and every decoder fix would need a pin move here. The crate boundary lets the code move there later unchanged. |
| Decode once offline and commit raw pixels | A raw 4096 by 4096 RGB map is 48 MiB, and agents composing covers bring images that must be decoded at render time. |
| A module inside the `lumen` crate | The decoders need nothing from the renderer; a separate crate keeps that true and gives the fuzzers one target. |

## Clarification, 2026-11-17: ADR 0016

ADR 0016 moves graphics evaluation, integrators included, to Bunny. It keeps this decision as an
explicit exception, unchanged; see its section "Exceptions, with their reasons".
118 changes: 118 additions & 0 deletions docs/adr/0016-graphics-in-bunny.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# ADR 0016: All graphics in Bunny, the integrators included

Status: accepted, decided by the maintainer on 2026-11-17. Extends ADR 0011. Nothing in this record
is built yet: the integrators named below are still Lumen's code.

## Context

ADR 0011 put every computation that can change a pixel in Bunny as a versioned contract, and left
Lumen the scene model, storage, formats and threading. It was written for hit tests, lights and
the lens. The plan has since grown to glass, textures, bump mapping, caustics, denoising and the
glass-teapot scene (flyingrobots/lumen#275).

One part of light transport is still implemented in Lumen: the integrator, the loop that follows a
path from hit to hit. Lumen has two, each with an identity that a render's provenance records:
`lumen-diffuse-path/1` and `lumen-smooth-diffuse-path/1` (`crates/lumen/src/render.rs`, selected
by `Integrator::for_scene`; ADR 0007 states the naming rule). Each is a documented composition of
Bunny contracts, and Bunny's `bunny-diffuse-shading/1` already fixes the order of operations within
a hit. What Lumen implements is the composition: which sampler pair feeds which decision, when a
path continues, when it ends. The planned `lumen-path/1` (flyingrobots/lumen#203) would add a third
loop in Lumen: mirror first, with later metal and glass extensions.

Those decisions change results as surely as any multiplication does. The maintainer decided on
2026-11-17 that the complete light-transport algorithm, continuation and termination included, is
Bunny's, so that it is implemented and maintained beside the operations it composes and another
caller can use it without rebuilding it.

## Decision

### The rule

**Bunny defines reusable graphics evaluation. Lumen supplies the authored inputs, selects the
contracts, schedules the work and records the results.**

"Changes a pixel" alone does not decide ownership: moving the camera or choosing a material
changes pixels too, and both are Lumen's. The line is between choosing inputs and defining the
algorithm that interprets them. pbrt's layout is a useful comparison but not the rule: pbrt's
tiled parallel loop is part of its integrator, and here threading stays in Lumen.

| Concern | Bunny | Lumen |
| --- | --- | --- |
| Materials | What scattering, reflection, refraction and their samples mean | Which material and parameters a scene uses |
| Camera | How camera inputs produce rays | Where the camera is and what it frames |
| Integration | Path evaluation, continuation, termination, the sample dimension each decision uses | Which integrator and its settings (bounces, samples) |
| Geometry | Hit tests, the tree and traversal, tessellation, vertex normals, mesh offsets and checks | Scene organisation, assets and their provenance, scene identities |
| Lights | Light kinds, light sampling, environment lookup, photon maps | Which lights a scene has |
| Textures | Lookup, filtering, procedural patterns, shading normals from maps | Which texture a material names |
| Image processing | Tone curve, reconstruction filters, the denoiser | Which stages run, and keeping their results |
| Evidence | The contracts and the observations a caller needs (ray outcomes, errors) | Provenance, hashes, statistics, golden values, gates |
| Running | Nothing | The command, job files, JSON Lines, threading, row bands, progress |

### Exceptions, with their reasons

- **Debug views stay in Lumen (ADR 0010, unchanged).** A view's integer map from a normal, a depth,
an ID or a work count to a colour encodes evidence for a person to read. It interprets no light,
and it uses only Bunny's results for the values it maps. If another caller needs the same views,
moving them to Bunny is a new record.
- **Image decoding stays in `lumen-image` (ADR 0012, unchanged).** It reconstructs raster data
from files without evaluating a scene. The JPEG standard leaves the IDCT's precision and chroma
upsampling open, so `lumen-jpeg-decode/1` fixes the arithmetic choices needed for reproducible
decoded pixels; it keeps that identity and its place. The decoder is kept whole, in one crate; it is not split
between repositories by step. Mesh decoding is already Bunny's (`bunny-ascii-ply-triangle-mesh/1`)
and stays there.

### What moves, and how

- **New integrators are Bunny's.** flyingrobots/lumen#203 is re-scoped: the path loop with a mirror
is a Bunny integrator, and Lumen's task selects it and wires its settings, provenance and
statistics. The sampling rule that #185 asks for (which sample dimensions each decision at each
depth consumes) is part of that integrator's contract.
- **Bunny reaches the scene through a small interface, not Lumen's `Scene`.** As Lumen already owns
the tree's storage and calls Bunny's construction and traversal, Lumen adapts its scene to a
Bunny trait for closest-hit and any-hit queries and for a hit's material. Bunny does not learn
the command, job files, scene files or provenance. The trait answers queries; a callback that
only observes (for statistics) must not influence sampling, branching or termination. ADR 0002's
equal-provenance promise keeps its present scope: it does not extend to a caller's own tracer.
- **The existing diffuse integrators move later, and only as a move.** An identity is a promise
about results, not about which repository holds the code. `lumen-diffuse-path/1` and
`lumen-smooth-diffuse-path/1` keep their names and meaning; when Bunny's implementation replaces
Lumen's, it must preserve, not just the image:
- the image bytes, on the golden corpus and every Determinism platform;
- the linear radiance of each path, compared before the tone curve and quantisation;
- flat, smooth and mixed scenes, for both identities;
- the ray outcomes Lumen reports (camera hits, bounces, shadow rays, rejected bounces);
- the typed failures, with their context;
- the tracer's declared query behaviour and tie-breaking;
- the public API and provenance fields, or an explicit, recorded transition.

A golden image witnesses the image only. Measured traversal work (ADR 0008's counts) may change
with a different traversal and is recorded as such, not treated as a broken promise. The
independent composition in `crates/lumen/tests/render.rs`, written with brute-force queries, stays
independent: it is never rewritten to call the implementation it checks. A move is not combined
with a numerical change; a change of result is a new identity, separately reviewed.
- **The tone curve is already Bunny's.** `ToneCurve::apply` and `write_rgba8` are Bunny's;
Lumen's `TONE_CURVE` only selects `bunny-tone-srgb/1` and records it. Extracting the diffuse
integrators preserves the selected curve, the output bytes and the provenance.

## Alternatives rejected

| Alternative | Why not |
| --- | --- |
| Keep integrators in Lumen (ADR 0011 as written) | They are named and recorded already, but the composition would stay in a repository other than the operations it orders, and every new material would add transport code to Lumen that no other caller can reuse. |
| Split by "kernel in Bunny, loop in Lumen" | The termination rule and branch choice change results as much as any kernel; the split would be arbitrary. |
| Move the scene model, scene files or evidence into Bunny | ADR 0011's reason stands: storage, identities, file formats and provenance are a renderer's business. |
| Move debug views and image decoders to Bunny now | Coherent, but neither evaluates light; the move would churn accepted decisions and open work (flyingrobots/lumen#272, #273) for no caller that needs it. |

## Consequences

- Lumen's arithmetic narrows to integer bookkeeping, the debug-view colour maps (ADR 0010) and image
decoding (ADR 0012). A reviewer can refuse any other Lumen change that defines how light, geometry
or a texture is evaluated.
- Bunny grows from a library of primitives into one that also offers complete integrators. It
stays modular: a caller that needs only a box test does not take on the integrators' dependencies.
Bunny's README says it does not try to be a renderer; the first Bunny integrator task updates it.
- Each feature still takes a Bunny pull request first and a move of Lumen's pin (ADR 0011).
- The first Bunny integrator is small: #203's mirror facing a diffuse card, with bounded termination
and stated sampling. Glass, media, photon maps and denoising are not its prerequisites.
- Issues filed before this record that put such work in Lumen are re-scoped when picked up, and
their Bunny prerequisite is added to their frontmatter.
Loading