Veach Ajar scene from the Mitsuba gallery rendered in Koji

Veach's "ajar door" scene from the Mitsuba gallery, rendered in Koji. Today an imported scene like this becomes renderer-owned data before any integrator sees it. That was not always true of Koji's own built-in scenes.

A renderer becomes much easier to test once a scene stops being a side effect of whichever integrator happens to construct it.

That sounds obvious, but it was not how Koji began. Like many small renderers, it grew around concrete milestones: a particular scene exercised a particular feature, an integrator knew which setup it was expected to render, and validation assumed that those two identities belonged together. That was convenient while the renderer was small. It became a problem as soon as I wanted to compare independent transport algorithms on exactly the same input.

After decomposing the original monolith, the next architectural step was therefore to make scene identity and integrator identity independent inputs. Scene IR is how that happened.

What "entangled" actually looked like

The public execution selector was --milestone. A milestone did not just choose an output; it implied a scene, an integrator, and sometimes validation assumptions that belonged to that stage of development.

When I went looking for the coupling, it turned out to be concrete rather than conceptual:

The last one is the clearest illustration of the problem. A report that says "VCM" while quietly running three algorithms makes every comparison built on top of it ambiguous. If two outputs differ, is the difference caused by transport, or by the fact that they are not actually consuming the same scene?

Scene IR as the portable boundary

The rule I settled on is that a scene is renderer-owned data with an identity of its own, and an integrator is a separate registered component with its own identity and declared capabilities.

Koji's scene pipeline from scene sources through Scene IR, render data, integrators, and output
Scene sources normalize into Scene IR, which compiles into the backend objects integrators consume. Tap to open the full diagram.

Scene IR owns cameras, geometry and instances, materials, lights and environments, media, animation samples, scene metadata, and the capabilities the scene requires.

Scene IR does not own Embree acceleration structures, integrator-specific transport state, session state, accumulated film, or any substitution tied to a particular code path.

That division is the point. Scene IR describes what the scene is. The render-data compiler turns that description into the backend objects the transport layer can intersect and shade efficiently. Integrators only ever see the compiled result, never importer classes or Embree handles.

In practice the change was blunt. --milestone was removed outright, from help, tests, scripts, and documentation. --integrator and --scene became the public inputs, both backed by registries that can be listed as stable JSON: 49 registered scenes and 29 integrator IDs, each with an explicit capability record.

One scene, four integrators

The first useful demonstration was the cornell_box_measured scene, selected independently with four integrators:

koji-render --integrator pt          --scene cornell_box_measured
koji-render --integrator nee-2bounce --scene cornell_box_measured
koji-render --integrator sppm        --scene cornell_box_measured
koji-render --integrator vcm         --scene cornell_box_measured

All four outputs were finite and nonblank. Their means were not close:

Integrator Mean RGB
pt 0.1433
nee-2bounce 0.1205
sppm 0.0737
vcm 0.0956

Some of that gap is expected. The two-bounce diagnostic truncates transport by design and should come in below full path tracing. SPPM and VCM disagreeing with path tracing by that much is not expected, and I did not treat it as acceptable.

But that was the next problem, not this one. The result that mattered here was architectural: the same scene identity could now reach four transport implementations without any of them swapping in a different setup. Before, a disagreement like this could not be interpreted. Now it could be investigated, and it became the starting point for the bidirectional transport work later in the series.

Compatibility is checked, not assumed

Once scenes became independent data, compatibility had to become explicit too.

Each scene declares what it requires: delta transmission, environment lighting, media, motion, subdivision, textures. Each integrator declares what it supports. The renderer compares the two before compiling anything.

Scene and integrator capability check before rendering
A scene's required capabilities are checked against the integrator before anything is compiled. Tap to open the full diagram.

These are real rejections, observed verbatim:

missing_capability:delta_transmission scene=sphere_light_in_glass integrator=direct
missing_capability:envmap scene=m24_bdpt_production_envmap integrator=camera
missing_capability:media scene=m30_homogeneous_fog_box integrator=direct
missing_capability:motion scene=m16_motion_blur integrator=camera
missing_capability:subdivision scene=m15_subdivision_displacement integrator=camera
missing_capability:textures scene=m32_textured_graph_material integrator=camera

Unknown identifiers fail the same way, as unknown_scene:<id> or unknown_integrator:<id>.

This is a much stronger contract than letting a renderer quietly ignore an unsupported feature and still produce a plausible image. A direct-lighting integrator handed a light inside a glass sphere does not get to return a dark, reasonable-looking frame. It says why it cannot render that scene.

Round-trip as a renderer test

Scene export changed meaning too.

Koji's built-in scenes were originally procedural builders in C++. Instead of deleting them, I kept them as oracles: every builder exports its scene to JSON, and at runtime the renderer loads that JSON rather than calling the builder.

Scene round trip from builder oracle through JSON export, reload, and compilation back to comparison
Every built-in builder is kept as an oracle; its exported scene must reproduce it exactly. Tap to open the full diagram.

If that round trip fails, the problem is rarely "the JSON is malformed." It usually means some scene state still lives outside the scene description. The positional light mutations above are exactly that kind of state: they cannot survive an export, because they were never part of the scene in the first place. Fixing them meant baking the result into scene data through the exporter, so the scene file and the rendered scene finally say the same thing.

That makes serialization a test of ownership:

Is the scene truly owned by the scene system, or is some of it still owned by unrelated parts of the renderer?

All 49 registered scenes now pass that gate.

Evidence that nothing moved

A refactor of this size is only useful if it changes the architecture without changing the images.

The same fixed-seed reference renders from the previous baseline were rendered again after the change. All 12 final PFM images were byte-identical, with identical SHA-256 hashes. The full test suite passed, 77 of 77, and a set of source greps confirmed there were no remaining --milestone references, no integrator-side scene assignments, and no positional light writes.

The one intentional difference was the production VCM report: its hidden BDPT and SPPM comparison fields are now explicitly zero, and tests assert that no hidden output directories are created.

What remains imperfect

Scene IR did not make Koji physically correct.

Why this boundary matters

What Scene IR did was make later disagreement interpretable. When two integrators disagree, the question becomes narrower and much more useful: is the issue in transport, in import, in capability handling, in render-data compilation, or in how the scene was described?

Without Scene IR, those questions are hard to ask honestly, because scene setup and algorithm selection are still tangled together. With it, the rest of the renderer has a stable stage on which to disagree explicitly.

In the next article I will look at the first place that disagreement became concrete: path tracing, direct lighting, and multiple importance sampling, and why the probability densities behind them have to agree before anything built on top of them can be trusted.