How measured light becomes an 8-bit pixel

Light in real units

Before #200 the scenes' lights had no units: the sun's illuminance was 1, and every other light was a multiple of it. #200 gives them the units glTF defines for light. A camera-style exposure, the subject of chapter 2, then brings the results back to the range a display shows.

ADR 0023 measures light as glTF does, in photometric units. Three quantities cover every light:

• Illuminance, light arriving at a surface, in lux: the sun, a DirectionalLight, and the ambient light that every surface receives from all around.
• Luminous intensity, what a point light sends into each direction, in candela, as KHR_lights_punctual gives a PointLight.
• Luminance, light leaving a surface towards the eye, in cd/m²: emissive surfaces, the background, and what the lit pass computes for each pixel.

Every Reference scene is lit from one figure, the sun's 100,000 lx, "direct sunlight" (SUN_ILLUMINANCE in src/scenes/mod.rs). The other lights keep the ratios to the sun that they had before they had units (lights added since are given against it too: town's 1,024 lamps, from PR #273, are 2,000,000 cd each; see Town Explained).

For lamps, the point lights look extreme. A point light's illuminance falls with the square of the distance, so matching the sun 3 m away takes 900,000 cd: 900,000 / 3² = 100,000 lx. Those are the ratios the scenes had before units, when the sun's illuminance was 1; part 1 wrote them out in lux and candela. minification's light, 300 times the sun's figure, matches the sun about 17.3 m away, since √300 ≈ 17.3.

The lit pass computes each pixel's luminance from these numbers, in f32. The rest of this guide follows that luminance to the screen, through the chain #200 built:

Exposure

A camera does not show luminance as it is. Its exposure decides which luminance comes out as white, and a bright scene needs less exposure than a dim one. Praxis sets its exposure as photographers do, as an EV100, and multiplies each pixel's luminance by the resulting scale before storing it.

The scale comes from Lagarde and de Rousiers's course notes, "Moving Frostbite to Physically Based Rendering 3.0" (2014, pp. 85–86). An EV100 gives the exposure:

The 1.2 is a luminance: 1.2 cd/m² = 78 / (100 · 0.65), the luminance that saturates an ISO 100 sensor at EV100 0, with the notes' lens and vignetting factor q = 0.65. At EV100 0, 1.2 cd/m² therefore exposes to 1. Each EV100 more halves the scale, so the luminance that exposes to 1 doubles. Camera::exposure computes the scale and ev100_for_exposure inverts it (src/camera/mod.rs).

Sunny 16, a sunny day's exposure, is EV100 15, the default of Camera::new; it scales by 1/39,321.6. The Reference scenes set their own: each sets EV100 = log2(100,000 / 1.2) ≈ 16.35, an exposure of 10⁻⁵, one over the sun's illuminance in lux, which was 1 before units. Every value grew by 100,000 and the exposure divides by 100,000, so the lit pass's results came out as before. Part 1 changed no Golden: at most 110 pixels of a scene moved by one 8-bit step.

Storing HDR

Exposed values still span a wide range. At the scenes' exposure, a sun glint exposes to 1,240 and a white surface in sunlight to about 0.32, by this guide's arithmetic. So the lit pass stores colour as 16-bit floating-point numbers, which keep that range, and leaves the step down to the display's 0 to 1 to a later pass.

The lit pass computes luminance in f32, and needs to: a sun glint reaches 1.24 × 10⁸ cd/m² before exposure (ADR 0023), far past the largest finite value of fp16, 65504. It multiplies by the exposure first, then clamps to 65504. The clamp settles what the backends would otherwise disagree on: on overflow, Vulkan may store infinity, while the M4 Pro saturates, as measured (ADR 0023); Metal's specification does not say which.

It then weights the clamped colour for the resolve, chapter 4's c / (1 + Y(c)), where Y is luminance by ITU-R BT.709-6's coefficients, and writes it into a 4x MSAA Rgba16Float colour attachment:

That attachment is transient. The pass resolves it into the HDR target before it ends and discards its samples, so they never need to reach memory; on Apple GPUs it is memoryless. The clear colour, which is the background pre-exposed, is weighted the same way.

The hardware resolve writes the single-sample Rgba16Float HDR target, 8 bytes a pixel: 2560 × 1440 × 8 = 29,491,200 bytes at 1440p. It has the frame's size, so src/render/targets.rs creates it again with the other render targets on every resize. The tonemapping pass then loads it, one texel per pixel.

The resolve

A pixel on an edge holds four samples that can see different things, and the hardware averages them. If one sample catches a glint far brighter than the rest, the plain average is mostly glint, and once tone-mapped the whole pixel shows white: edges and highlights smaller than a pixel whiten. Averaging with weights that shrink as a sample gets brighter keeps the edge looking as it should.

The hardware's MSAA resolve is a box average: each of the four samples weighs a quarter. Over exposed HDR values, one sample of 100 over three of 0.05 averages to 25.04, which GT7 shows as white, as does a clamp to 1. PR #251, which resolved HDR that way, measured the effect: sub-pixel highlights whitened, and one pbr-sweep pixel went from sRGB code 228 to 255.

Karis's blog post "Tone mapping" (2013) gives a way to get a weighted average out of the hardware's plain one, a reversible weighting. The lit pass stores w = c / (1 + Y(c)) (chapter 3), the hardware averages the stored values, and the tonemapping pass undoes the weighting, c = w / (1 − Y(w)), clamped to 65504 (resolve_weighted and resolve_unweighted). What comes out is the samples' average weighted by 1 / (1 + luminance):

The proof takes one line. Y is linear, so Y(avg of c/(1+Y)) = avg of Y/(1+Y), and 1 − Y(avg) = avg of 1/(1+Y); dividing the stored average by that leaves Σ w c / Σ w. A stored luminance, Y/(1 + Y), stays below 1, so the attachment never holds a large value. It still needs fp16: a saturated colour's channels can pass 1, and every bright sample's luminance is stored just below 1, where only fine steps tell one from another.

The same four samples resolve to 0.395 weighted, against 25.04 boxed. In the scenes, part 3's weighting pulls partially covered highlight pixels back down, for example from code 200 to 180.

The weighting is cheap. Ticket #189's HDR survey, which HDR Pipeline Explained follows, timed it with its probe on the M4 Pro at 1440p: at most 0.009 ms in a lit pass and 0.018 ms in the final pass. Part 3 measured +4.6 to +7.6 µs a frame (chapter 7).

It has an image cost, which the survey's row 18 records. Sub-pixel highlights lose energy: a glint that covers one sample counts for less than its quarter of the pixel. And blending in the weighted space darkens 50% blends, which will matter for M6's transparency.

GT7

Exposed colour runs from 0 into the thousands; an SDR display shows 0 to 1. A tone curve maps the one onto the other. GT7's darkens the darks along a toe, leaves the mid-tones as the exposure set them and rolls the brights over a smooth shoulder towards white. It also handles colour: a very bright colour fades towards white instead of staying a pure primary.

Units and paper white

Polyphony Digital presented GT7's tone mapping in the SIGGRAPH 2025 Physically Based Shading course, with a sample implementation, gt7_tone_mapping.cpp 1.0, under the MIT licence; Praxis ports its SDR path. GT7 works in frame-buffer units, 1.0 = 100 cd/m². It takes an SDR display's paper white to be 250 cd/m², 2.5 units, and its SDR output is 0.4 · min(blended, 2.5), which runs from 0 to 1.

The curve

The tone curve is the GT tone curve v2, gt7_curve, at GT7's parameters: peak 2.5, alpha 0.25, mid point 0.538, linear section 0.444 and toe strength 1.28. The linear section ends at 0.444 × 2.5 = 1.11, and the curve has three parts:

Below the mid point, a power toe, x^1.28 scaled by the mid point, blends by smoothstep into the identity. From 0.538 to 1.11 the curve is the identity itself. Above 1.11 an exponential shoulder rises towards k_A = 2.963, and the final min clamps the result to the peak. k_B and k_C make the shoulder meet the identity at 1.11 with the same value and slope, by this guide's arithmetic.

Colour

The curve applied to each channel alone gives what the sample calls the skewed result. GT7 blends it 40/60 with a version that keeps the input's chroma in ICtCp, a colour space from ITU-R BT.2100, which GT7 computes through SMPTE ST 2084's PQ, and takes the skewed result's intensity. That chroma fades to white as the input's intensity goes from 0.98 to 1.16 of the paper white's, along a smoothstep:

How Praxis wraps it

Praxis reads exposed 1.0 as the paper white, so the frame-buffer value is 2.5 × exposed. GT7 works in Rec. 2020's primaries and the scene's colour is in Rec. 709's, so tonemap converts linear Rec. 709 to Rec. 2020 before GT7 and back after, with ITU-R BT.2087-0's matrix (R₂₀₂₀ = 0.6274 R₇₀₉ + 0.3293 G₇₀₉ + 0.0433 B₇₀₉, and so on), and clips to [0, 1], as the survey's probe did.

Reading exposed 1 as paper white puts GT7's linear section, frame-buffer 0.538 to 1.11, at exposed 0.2152 to 0.444, and there the operator maps a grey to itself: mid-tones keep their exposure, which the decision calls "keeps today's mid-tones". Exposed 1 itself shows at 0.835, on the shoulder.

The shader matches the sample within 7 × 10⁻⁵ for GT7 itself and within 2.3 × 10⁻⁴ for the Rec. 709 wrapper, on the M4 Pro (src/render/shader_function_tests.rs). The wrapper's largest error is in a saturated green's small red channel, where converting back to Rec. 709 subtracts near-equal terms; sRGB encoding is steep there, which makes it about a fifth of an 8-bit step.

Why GT7

The decision on map #17 chose GT7 over AgX for three reasons: of the five operators the survey offered, it is the only one with a path to any HDR peak, it keeps today's mid-tones, and it has MIT reference outputs. There is no operator switch; grading, when it comes, would bake the operator into a LUT. The survey's other rows cover the alternatives: Reinhard, Hable, ACES, AgX, PBR Neutral and Tony McMapface.

The Goldens see the shoulder. Clamping exposed colour to 1 before GT7 makes them fail: pbr-sweep by 376 pixels, up to 235 steps; normal-tangent by 159 pixels, up to 240; and minification by 1,038 pixels, up to 19. Exposed values above 1 reach the images, and the Goldens would catch an operator that clipped them.

sRGB and dither

The window takes 8-bit codes, 256 per channel. A dark gradient that spans only a few codes rounds into visible bands. Adding a little noise before rounding turns the bands into fine grain whose average follows the gradient. Praxis takes its noise from a fixed blue-noise pattern, so the grain is even and the same in every frame.

Encoding once, in the shader

sRGB encoding (IEC 61966-2-1) turns display-linear values into the codes a display expects:

The pass encodes in the shader, once, and writes an 8-bit UNORM target: the window picks a Bgra8Unorm or Rgba8Unorm surface, and the capture target is Rgba8Unorm. An sRGB surface written through a non-sRGB view would do the same, but it needs a downlevel flag outside the Capability floor, which Vulkan reports only with an extension. The target stores what the shader writes, rounded to 8 bits, so the noise the shader adds lands on 8-bit steps. Without the dither, the shader's encoding matches the hardware's sRGB view within one step: by scene, 0.8 to 9.7% of pixels differ by one.

Triangular noise of two steps

The dither is triangular noise on (−1, 1) 8-bit steps, added to the encoded value. Two steps peak to peak is the least that removes noise modulation (Lipshitz, Wannamaker and Vanderkooy 1992, p. 372): with it, the rounding error's power no longer depends on the signal. The noise goes in the encoded domain because that is where the rounding happens. Added in linear light instead, it would be 12.92 times too large near black, where the encoding multiplies by 12.92 (the survey's row 19).

The mask

The noise comes from Christoph Peters's free blue-noise textures (CC0): Data/64_64/LDR_LLL1_0.png, a 64 × 64 image that holds each of its 256 levels exactly 16 times, alike in red, green and blue. It is committed as assets/BlueNoise/LDR_LLL1_0.png with its manifest entry, and compiled into the binary from src/render/dither_mask.bin, since a build without cook links no PNG decoder; a test pins one to the other.

The mask's levels are uniform, and the dither needs triangular noise. Peters's "Dithering" remaps the mask's values through the inverse CDF of the triangular distribution, which changes the values and keeps their arrangement. Praxis reads each level at the centre of its bin, where Peters's listing uses the stored value, level/255:

Over the 256 bin centres, the noise's mean is 0 and its variance 1/6, within 10⁻⁴; its extremes are ±0.9375.

The mask is fixed to the screen and never animates, so the Goldens stay exact and ADR 0008's stance against temporal tricks holds. The same noise goes to all three channels. Each channel moves by a step in about a third of pixels, since E|noise| = 1/3, and the channels tend to move together: on average, a grey moves in a third of pixels, and a colour whose channels sit at unrelated points between steps moves in 1 − E[(1 − |noise|)³] = 3/5 of them, by this guide's arithmetic; measured by scene, 48 to 75% of pixels move.

What it costs

Nearly all of #200's GPU time is the new tonemapping pass, and most of that is GT7's arithmetic: about 0.33 to 0.35 ms a frame in all, at 1440p on the M4 Pro. pbr-sweep's GPU frame went from about 700 µs to 1,033 µs. The lit pass costs 5 to 9 µs more than before.

Each step was measured on the M4 Pro at 2560 × 1440 against the step before, in interleaved rounds:

• The dither first wrapped the mask with a modulo by the texture's size, at which it cost about 38 µs; a wrap by a constant power of two halved that.
• Part 2 cost the CPU 14 to 27 µs and 17 more heap allocations a frame, for one more wgpu render pass.

Why frame totals

The tonemapping pass's own timestamps do not measure it. On Apple's tile-based GPU, its first timestamp lands while the lit pass's fragments still run, so the span between its timestamps includes the lit pass. Its cost is read from frame totals instead: the change in the whole frame's GPU time between two builds.

What is not in M3

Some of what the survey covered stays out of M3 on purpose. Each item below was decided, and each that may return waits on the project's roadmap issue, #17, with the condition that would bring it back.

• Automatic exposure. Each scene keeps a manual EV100. Histogram exposure adaptation and local tone mapping return together, with the first scene that joins an interior and sunlight (M5) or changes the time of day (M6).
• Bloom. None, by decision B1; the survey measured a bloom chain at 0.27 ms.
• HDR display output. SDR only, by decision H1, though GT7 has a path to any HDR peak.
• An operator switch. None: GT7 is the operator, and grading, when it comes, goes into a LUT.

Reading list

Grouped by source, each with what it is good for here. Repo links are pinned to main at 69e02dc, and the links to the course notes, papers and talks are the ones the survey cites.

Glossary