003 — Tonemapping, Color LUTs and a CPU Profiler

2026-10-28 → 2026-11-02

The ARAL renderer has rendered in HDR (R16G16B16A16_SFLOAT) since its first steps, but until now the image reached the screen with a plain blit: values above 1.0 were simply cut. This step replaces that blit with a real post-processing pass: tonemapping, color grading, dithering.

For this capture the shader had a temporary test line: left half of the screen = LUT A, right half = LUT B, to see both at once. Everything is driven from the console: inga:lut 1 1 3 (window 1, A = the WARM preset, B = a LUT loaded in slot 3), inga:lutBlend, then the operators with inga:tonemap 1 aces / agx.

Where this is going

ProjectO is now the demo priority. The milestone: the reference scene made in Blender (the ruins), seen from the default camera of the application — the same one as the Blender capture of the previous post — rendered by ARAL better than that capture.

  • Level 1, "match": materials, sun, shadows.
  • Level 2, "beat": sky and tinted ambient light, soft shadows, fog, color grading, AO — exactly where the Blender capture is weak: grey and flat shadows, empty background, no depth, no contact at the foot of the columns.

Style targets: painted textures, warm sun, strong shadows, contact AO, tilt-shift, haze. Tonemapping and grading come first because everything after them will be judged through them.

What was implemented

  • A tonemap pass instead of the blit
    • one full-screen triangle, the HDR target is now SAMPLED (no more TRANSFER_SRC), read after the MSAA resolve
    • UV = gl_FragCoord.xy / outputExtent: when renderScale < 1.0, the bilinear upscale happens on the HDR image, before the tonemap
    • writes the swapchain as a color attachment; the swapchain lost TRANSFER_DST, the blit is gone
    • a descriptor set dedicated to post-processing, owned by the renderer (a render target is not an asset: no bindless slot for it). FXAA, upscaling and bloom will reuse the same layout.
  • Tonemap operators, switchable at runtime
    • eNONE (clamp — Blender's "Standard"), eREINHARD, eACES (Narkowicz approximation), eAGX (default, like Blender), ePBR_NEUTRAL (Khronos)
    • AgX and PBR Neutral ported from three.js (MIT)
    • an operator is a setting, not a renderer mode; manual exposure in EV stops (0 = neutral, +1 = twice as bright), room left for auto-exposure later
  • Color grading LUTs
    • 3D LUTs 32³, 8 slots, two of them active at once (A and B) with a blend factor: zone transitions driven by the game
    • applied after the tonemap, on the sRGB-encoded value, then decoded back to linear (the swapchain is _SRGB)
    • always applied, no branch: slot 0 is an identity LUT generated at init
    • built-in presets DEFAULT / WARM / COLD (white balance); moods like night, underwater or sepia are the game's choice, loaded from files into slots 3+
    • source format: the neutral 1024×32 PNG strip (32 slices, the Unity / Unreal layout) — the engine can export it, you grade it in any image editor, you load it back. .cube later.
  • Dithering: ±0.5 LSB of interleaved gradient noise before the 8-bit quantization, against banding (the sky gradients that come later will need it)
  • All of it goes through push constants (exposure, operator, LUT A/B, blend, dithering), not the frame UBO.

Estimated cost: ~0.05–0.1 ms on a Steam Deck, ~0.1–0.15 ms on a Switch 2 in handheld mode.

Usage

renderer->setTonemap(Inga::EToneMap::eAGX);
renderer->setExposure(0.5f);        // EV: +0.5 stop

renderer->loadColorLut(3, "data/luts/presets/inga_lut_preset_night.png");
renderer->setColorLuts(0, 3);       // A = default (identity), B = night
renderer->setColorLutBlend(0.5f);   // halfway: entering the zone

Or from the console, at runtime (the first argument is the window id):

inga:listTones
inga:tonemap 1 aces
inga:exposure 1 0.5
inga:loadLut 1 3 data/luts/presets/inga_lut_preset_sepia.png
inga:lut 1 1 3
inga:lutBlend 1 1
inga:dither 1 0

A LUT slot can be replaced while running. The update is refused if the slot is currently A or B, and vkDeviceWaitIdle is only called if a frame still in flight reads it.

More debug: a CPU profiler

The debug overlay (FPS, console) now also shows named CPU zones under the FPS line: average and worst frame over the period, and calls per frame, in microseconds. From update to present: scene.update, aral.begin, vk.fenceWait, vk.acquire, debug.overlay, aral.flush, vk.submit, vk.present.

void CRendererAral::flush()
{
  INGA_PROFILE_SCOPE("aral.flush");
  // ...
}

Waiting zones (fence, acquire, present) are declared with INGA_PROFILE_WAIT_SCOPE, so the engine can subtract them and get the real work time of the frame, whatever the present mode. Debug builds only: in release the macros are empty.

These are debug numbers (-O0 + ASan): the absolute values are inflated, only the comparison between zones means something. Here aral.flush is the biggest item. It will matter much more once lights and shadows arrive.

How it was tested

  • operators switched at the console, on the same frame;
  • identity LUT = unchanged image; a sepia LUT loaded in slot 3, blend adjustable from 0 to 1;
  • swapchain without TRANSFER_DST;
  • validation and synchronization clean on resize and when changing MSAA; 0 GPU allocation alive at shutdown.

The side-by-side comparison with Blender's AgX render is postponed to level 1: without lighting, ARAL only displays albedos while Blender lights the scene. Comparing them now would not mean much.

Little problems / choices made along the way

  • 8-bit LUTs, not 10-bit. The plan was A2B10G10R10 against banding. But the sources are 8-bit PNGs, and the dithering happens after the LUT anyway: R8G8B8A8_UNORM is enough. 10 bits the day a 16-bit source or a .cube file shows up — same memory size.
  • Rectangular dithering, not triangular. IGN at ±0.5 LSB. Triangular noise will be reconsidered when the sky gradients are there to judge it.
  • The end-of-upload barrier was only for the fragment stage; it now covers VERTEX | FRAGMENT.
  • The LUT setters have no effect on the SOLID renderer. A "renderer × feature" table needs to be written.

Tested on

AMD RX 6800 (RADV), Linux / Wayland.

Next step

Frustum culling.