exposure

Exposure in stops, and eye adaptation.

local exposure = require("@builtin::systems.exposure.exposure")

exposure.set({ auto = true, targetGrey = 0.18, meter = "centre" })
exposure.tick(dt)     -- adaptation is a rate; give it the frame's delta
exposure.get()        --> the settings in force
exposure.active()     --> are the exposure passes running
exposure.clear()      --> off, settings kept for the next set()

set takes any subset — omitted fields keep their current value. With auto off and compensation at 0 nothing is being asked for, and the passes are released rather than run at identity.

Each setting names the interval it means something in, and set refuses a value outside it — the whole call, naming the field, the value and the interval, so the scene stays on the exposure it already had. What set and get report is therefore what the frame is rendered with.

compensation, minEV and maxEV are in stops, and a stop is a power of two: +1 doubles the light reaching the image, +8 multiplies it by 256. Each accepts -exposure.STOP_LIMIT .. exposure.STOP_LIMIT — the width of what the frame can represent — and starts at 0, -4 and 4 respectively, which is the neighbourhood a scene is usually authored in.

tick is separate from set because adaptation moves per second: the passes need each frame's own delta to run at the same speed whatever the frame rate. The AutoExposure component calls it; code driving this module directly calls it once a frame.

speedUp and speedDown name the direction exposure moves, not the scene. Exposure rises when the scene has gone darker, and that is deliberately the slower one — the eye adapts to darkness far more slowly than to light, and matching that is what makes walking into a cave read as a moment rather than a switch.

meter decides which part of the frame is read. The thing a viewer is looking at is rarely the thing filling the most pixels, so a bright sky over a dark street would otherwise stop the street down until it is unreadable.

For exposure a scene should simply have, author the AutoExposure component instead — it carries the same settings, persists with the scene, edits live in the inspector, and ticks itself. This module is for code that changes exposure at runtime: a cutscene, going underwater, a photo mode.

The full description of what each knob does and how the passes work is in the package readme: guides { path = "systems/exposure" }.