Renderer · interface

ProbeBakeOptions

What a bake is for, and specifically whether it also replaces the scene's diffuse ambient.

interface ProbeBakeOptions

import type { ProbeBakeOptions } from '@driftengine/core';

In depth

The two halves of a probe were one decision until 2026-09-03, and nothing could ask for the first alone. A bake fills a cubemap that reflective surfaces sample, and it then reads that cubemap back, projects it onto spherical harmonics and raises uEnvIrradianceEnabled — from which frame on every diffuse surface in the world takes its ambient from the projection instead of from the values the consumer wrote into Environment. A consumer who wanted a car and a puddle to mirror the village got, as well, the whole scene changing what lights it, once, at whatever moment the bake landed.

That is a defensible default — a room's own light is usually better than a gradient — but it was not a choice, and it correlates with nothing a consumer can see. The one it was reported from gates its bake on a streamer being idle, so the substitution arrived minutes into a drive, and it was filed four times over two days as four different bugs.

irradiance: false declines the second half. The reflection is unaffected; the ambient stays whatever the consumer set. It also stops paying for it — the readback and the projection are the expensive part of a bake, and a caller that does not want the result does not wait for it.

It declines rather than undoes. A bake that declines leaves an earlier projection in place, because "do not compute this" is not "discard what is there". What a consumer gets by passing it on every bake is the guarantee they were asking for: their ambient is never substituted.

Properties

Name	Type	Description
`irradiance`readonlyoptional	`boolean`	Whether this bake also projects the room's diffuse light and lights the scene by it. More Defaults to true, which is what every bake did before this existed, so a caller that says nothing gets the frame it already had.
`bounce`readonlyoptional	`boolean`	Whether what the probe sees is lit by the grid's last bake, so each bake adds a bounce. More Defaults to false, which is what every bake did before this existed. Then everything a probe sees is lit by the sun and by the hemispheric ambient, so the grid holds one bounce. An enclosed space is mostly lit at the second bounce and later. A courtyard's arcades are the case this was built for: one bounce came out about two stops under a reference render. With it on, the surfaces in each face take their ambient from the grid instead. Round-robin baking then converges on the space's full interreflection, about a bounce each time the grid is swept, and a scene holding one moment bakes the grid two or three times. It costs no pass and no memory. The faces are drawn into their own cube and only the resolve writes the array, so the array is never read and written in one pass. Nothing changes until every probe has been baked once, because until then the grid is not readable; the first sweep lights by the ambient as before. What it gives up: light that leaks through a wall into a probe is bounced again, so a leak grows with each sweep. What would make it wrong is a space with near-white walls, where a sweep adds almost as much as the last and convergence takes many sweeps.
`faces`readonlyoptional	`readonly [first: number, count: number]`	Which of the six faces this call draws, as `[first, count]`: all six when absent. More A bake is six draws of the scene, and a scene of millions of triangles makes it the most expensive thing in a frame. Measured on a bought courtyard of eleven million: 6.4 ms of a 14 ms frame, on the frames it ran, which is a frame rate no display can hold steady. Spread over calls, each draws only its faces into the capture, and the convolution into the layer, which reads all six, runs when the sixth is drawn. Faces in the order a cube numbers them, `+X, -X, +Y, -Y, +Z, -Z`. The caller finishes one probe before starting the next, because the capture the faces are drawn into is one for the whole grid: faces of two probes interleaved make a cube of neither. What it gives up is a probe whose faces were drawn a few frames apart, under a light that moved a little between them.