Turning on dynamic global illumination

What it is#

Four node kinds a .vxcompositor can name, which together are the lit path docs/plan/19-lighting-and-global-illumination.md describes:

| Node | Does | |---|---| | !GlobalDistanceField | Composites the camera-following signed-distance clipmap every trace marches | | !IrradianceField | Fills the probe field that carries the scene's bounced light | | !DistanceFieldAo | Marches the clipmap for ambient occlusion and a sun shadow | | !IndirectDiffuse | Reads the probe field into the ambient term |

What it is for#

Indirect light that follows a scene which changes — a lamp that is switched on, a wall that falls down, a door that opens. Nothing here is baked, which is doc 19's whole argument.

You do not want it for a scene that never changes and ships on a budget: a baked solution is cheaper and, for a static scene, better. And you do not want the first two nodes at all if your project supplies no field — they build and do nothing, which is deliberate, but a document that names them without a host that fills them is a document promising something no frame delivers.

Using it#

The nodes go in the frame, before whatever shades with them:

version: 2resources:  - name: SceneDepth    format: Depth32Float    usage: DepthStencilTarget, Sampled  - name: SceneNormals    format: Rgba16Float    usage: ColourTarget, Sampledgame: !Sequence  name: Frame  children:    - !GlobalDistanceField      name: Clipmap    - !IrradianceField      name: Probes      budget: 16    - !DistanceFieldAo      name: Occlusion      depth: SceneDepth      normals: SceneNormals      source: DistanceFieldAo.GlobalDistanceField    - !IndirectDiffuse      name: Indirect      depth: SceneDepth      normals: SceneNormals

⚠ source is a contract, not a decoration. It is the compose-slot prefix that !GlobalDistanceField writes its bindings under and !DistanceFieldAo reads them from, so the two have to be the same string. They are separate settings because a frame may march a field a different node composited — or none.

⚠ Leave source out and you get the honest default, not a broken frame. !DistanceFieldAo answers "nothing is near" — fully open, fully lit. !IndirectDiffuse answers no indirect light *and* an unshadowed sun, which are two different right answers rather than one convenient zero: answering zero for the second would put every surface in the world into shadow.

The fields themselves are the host's, on exactly the terms the virtualized path's traversal is:

using Vixen.Core.Mathematics;using Vixen.Rendering.Compositor;using Vixen.Rendering.DistanceFields;using Vixen.Rendering.IrradianceFields;public static class Lighting {    public static void Supply(CompositorBuilder builder) {        builder.DistanceField = new GlobalDistanceField();        builder.IrradianceField = new IrradianceField(            new BoundingBox(new(-64f, -8f, -64f), new(64f, 24f, 64f)),            new Int3(16, 4, 16)        );    }}

A GlobalDistanceField owns volume textures and a residency the camera drives; an IrradianceField owns a brick pool and a probe budget. Neither is something a document can create, and a node built without one does nothing rather than throwing — which is what a shared compositor document says to a project that has no field in it.

Examples#

Choosing how fast the field settles. budget is the whole quality-against-cost decision:

- !IrradianceField  name: Probes  budget: 32          # converges in fewer frames, costs more in each  dilationPasses: 2   # spread a filled probe's answer into its unfilled neighbours

A field settles over several frames, so a higher budget reaches the right answer sooner and costs more per frame. Which of those a project wants is not something the engine can know.

Turning the sun shadow off where a shadow map already covers it:

- !DistanceFieldAo  name: Occlusion  depth: SceneDepth  normals: SceneNormals  sunShadow: false

That is a permutation rather than a branch, so the march is not compiled at all and the pass carries none of the sun's uniforms either.

Registering the factory, which is what lets a document name the two screen passes:

using Vixen.Rendering.Compositor;using Vixen.Rendering.PostFx;public static class Frames {    public static void Register(CompositorBuilder builder) => builder.Factories.Add(new PostEffectFactory());}

CompositorBuilder cannot switch on those types — Vixen.Rendering.PostFx is downstream of it, and a case there would be a cycle — so the knowledge travels the only direction it can.

⚠ Ambient occlusion is marched in the material, not composited over the frame#

The obvious arrangement — a screen-space pass that writes an occlusion buffer, and something that multiplies it over the picture — cannot be right in a forward frame, and the reason is an ordering one. Occlusion belongs on indirect light and nothing else; multiplying it into direct light is what makes a scene look dirty rather than grounded. A screen pass has to run after the depth and normals it reads, which in a forward frame is after the pass that shades — and by then direct and ambient are one number that cannot be taken apart.

So ForwardPlus marches the clipmap itself, at the shading point, and writes the answer into d.occlusion — which Ambient reads and which Direct and Punctual never see. A corner darkens because less sky reaches it; a lamp three metres away still lights it.

It takes three lines and none of them works alone:

# 1. The bindings. Without this the composition below declares five volumes and a sampler in#    set 0 that nothing fills, and a set written short is every draw in the pass refused.- !GlobalDistanceField  name: Clipmap  shader: DistanceFieldAo.GlobalDistanceField  passes:    - ForwardPlus.GlobalDistanceField

// 2. The composition, which says what is behind the slot.slots[MaterialCompiler.ForwardDistanceFieldSlot] = "GlobalDistanceField";// 3. The permutation, which compiles the march. Off, it is not merely skipped — it is not built.permutations.Set(ForwardPlusKeys.UseDistanceFieldOcclusion, true);

⚠ And a fourth thing that is not a line of configuration at all: the clipmap has to contain something. GlobalDistanceField is a composite and holds no geometry of its own — GlobalDistanceFieldRenderer.Instances is what it is assembled from. With the list empty, every march answers "nothing is near", every counter reports success, and the picture is exactly the one with no occlusion in it.

Two out of the four is the interesting failure, because the two halves fail in opposite directions: a composition with no bindings is a black pass, and bindings with no composition are a march that reads nothing and says nothing.

See also#

• Players and possession — what puts a camera in the scene these
• nodes light.

The design record is docs/plan/19-lighting-and-global-illumination.md. The nodes' placement in a frame follows docs/plan/06-rendering-pipeline.md § Compositor, which is why they are an asset at all: a path that cannot be written down is a path every host has to reimplement.