handle-sdr-tonemap-lut

--- name: handle-sdr-tonemap-lut description: "RenoDX HLSL/Slang shader workflow for proven shader-side SDR tonemap, hard clip, LUT, color grade, and HDR bridge changes. Use when editing game shaders for neutral-by-default ToneMapPass/RenoDRT, vanilla/0 ToneMapPass user grading, Preset Off vanilla reset, PsychoV17, vanilla midgray/slope or inflection matching, UpgradeToneMap delta, SDR LUT bridges, N2 max-channel reconstruction, gamut compression, hue/saturation clip emulation, internal/user LUTs, or shader-side tonemap/LUT replacements after upstream HDR/SDR signals are identified." argument-hint: "game shader, proven HDR/SDR signals, and goal, e.g. audit LUT bridge, add PsychoV17, fix hard-clip ToneMapPass, or verify Preset Off" ---

# Handle SDR Tonemap + Optional LUT

Use this skill for RenoDX **shader-side** tonemap/LUT work in HLSL or Slang. Keep the workflow focused on shader changes: finding the right color signal, preserving the vanilla SDR appearance, and choosing a shader bridge into HDR.

RenoDX is not a final-frame inverse-tonemap postprocess. Do not start from the completed SDR swapchain image and expand it with an inverse curve like Microsoft AutoHDR, RTX HDR, or generic ReShade FX. If the target pass/resource or upstream signal is not proven, switch to `swapchain-resource-analysis` first.

Shader-side RenoDX tonemapping is a forward display-mapping decision for a proven upstream signal. It should target user-configurable HDR output levels, preserve the game's intended SDR art direction, and avoid overcoloring or oversaturating the original look.

## Neutral-by-default rule

RenoDX mods should be neutral out of the box. Treat HDR as extending the original game's SDR pipeline limits into a display-referred range, not as permission to redesign the image.

- Preserve vanilla/original SDR contrast, saturation, hue, grade, and presentation effects unless the task explicitly proves a different target. - Default tonemap/LUT settings should match the original/vanilla look as closely as practical in SDR output mode and keep the same art direction in HDR output mode. - Use HDR headroom to preserve highlights, bloom, gradients, and gamut that the original pipeline clipped or compressed; do not add contrast or saturation just because the output is HDR. - Put creative/non-neutral looks behind explicit user settings that default to neutral, or behind named presets such as `HDR Look`; document rare exceptions with validation evidence. - Reject shader changes whose main visible effect is "more punch" without a proven vanilla reference or user-requested artistic control. - `ToneMapPass` with `RENODX_TONE_MAP_TYPE == 0` / Vanilla is a valid mode for keeping the game's vanilla process as the tonemap while still allowing user grading controls such as exposure, contrast, and saturation. Do not treat that as the same thing as a full Off preset. - A Vanilla/0 path may explicitly `saturate` or clamp to emulate the original implicit RGBA8U/UNORM resource write clamp after a resource upgrade. Keep that scoped to vanilla preservation/reset behavior; do not reuse it as an HDR bridge, LUT proxy, or `neutral_sdr` recommendation. - A Preset Off or equivalent reset should restore true 100% vanilla as closely as practical by disabling custom grading, HDR-look controls, and effect overrides; exact equivalence may be impossible after resource upgrades, but the difference must be intentional and documented.

## Related skills and scope

| Need | Use | |---|---| | Find the target pass, prove HDR source location, plan resource upgrades, or handle final `SwapChainPass` output | `swapchain-resource-analysis` | | Build/link game addon, configure DevKit, create/resume a game folder | `setup-game-mod-dev` | | Plot tone curves, slopes, LUT residuals, or sampled shader behavior | `analysis-graphing` |

This skill starts after a shader-side target and relevant signals are known. If the task is still about finding those signals, stay in `swapchain-resource-analysis`.

Treat the visible SDR look as a pipeline, not just a curve:

```text scene / post exposure / bloom / vignette / fade -> SDR tonemap or hard clip -> optional user LUT -> internal/generated LUT or color grade -> blend masks / strength / scaling -> output encode ```

## Boundaries

- Focus on HLSL/Slang shader changes and shared shader includes. - Read `shared.h` only to understand shader injection constants/macros used by the shader. - Put nontrivial reusable shader logic in the game's `common.hlsl`, `common.hlsli`, or an existing nearby purpose-specific `.hlsli` include when that fits the folder pattern. - Do not turn this into addon UI, C++ plumbing, resource upgrade, CMake, or release workflow guidance. - If the shader fix requires addon/resource/C++ work, report that as an external requirement instead of expanding this workflow. - Require a proven shader-side signal such as `untonemapped`, `neutral_sdr`, or `graded_sdr`; if draw/resource analysis is missing, use `swapchain-resource-analysis` first. - Reject final swapchain/backbuffer inverse tonemapping as a RenoDX strategy. That is AutoHDR/RTX HDR/ReShade FX class postprocessing, not shader-side tonemap replacement.

## Shader rules

- Keep changes local to the game/shader being worked on. - RenoDRT is `renodx::draw::ToneMapPass(...)`. - Prefer current `ToneMapPass` methods used in the repo such as Neutwo or Reinhard. Do not recommend Hermite or Daniele as new strategy choices. - Do not extract helpers for local control flow, one-off math, basic field access, or short condition checks. - Do move substantial tonemap/LUT bridge functions into a game-local common include instead of pasting large logic blocks into every original shader. - When modifying decompiled/original shaders, keep edits minimal: capture the needed signal, call a common include helper or small scoped block, then assign the output. - Clearly mark custom snippets and preserve vanilla logic by leaving it intact or commenting out replaced lines where practical; avoid silently deleting vanilla code. - Prefer lightly injected snippets in original shaders over broad rewrites.

## Expected output from this skill

Produce these sections:

1. **Detected shader pipeline** - capture point, tonemap/clip, LUTs, encodings, masks, and output. 2. **Shader strategy** - primary HLSL/Slang approach and why. 3. **Fallback/legacy shader path** - what to preserve if replacing is risky. 4. **Shader edit plan** - exact shader files, include files, and injected constants used. 5. **Visual/math validation** - curve, slope, LUT, and screenshot checks.

## Step 1: Discover the shader pipeline

Inspect the relevant shader(s) and nearby shared HLSL/Slang includes. Answer:

| Area | What to identify | |---|---| | Local includes | Existing `common.hlsl`, `common.hlsli`, or purpose-specific `.hlsli` files that can hold helper logic. | | Resource proof | Draw/resource evidence that the shader input is not just final SDR backbuffer color. | | Capture point | Last useful linear scene value before SDR clamp/tonemap/LUT. | | Presentation effects | Exposure, fades, bloom, vignette, hero lights, grain, or clip effects already inside the shader. | | Tonemap | Analytic curve, hard clip/saturate, black-box shader math, or none. | | LUTs | Internal LUT, generated LUT, optional user LUT, chained LUTs, or custom LUT draw count. | | Encoding | Linear, sRGB, gamma 2.0/2.2/2.4, packed 2D LUT, or 3D LUT. | | Sampling | Trilinear, tetrahedral, manual 2D strip, or hardware sample. | | Blending | Strength scalar, vanilla constant, per-pixel blend mask, or multiple LUT paths. |

## Step 2: Choose the shader reference scope

Use the narrowest reference scope that preserves the intended look.

| Scope | Use when | |---|---| | `tonemap-only` | The LUT is unrelated or should remain a separate post-grade bridge. | | `tonemap-plus-lut` | Final SDR look is defined by tonemap plus LUT. | | `full-sdr-look` | Effects such as fades, vignette, bloom, masks, or exposure are part of shader presentation. | | `hard-clip-sdr` | There is no true tonemap; vanilla is saturate/clip plus optional LUT. | | `unknown-black-box` | No analytic model is reliable; sample or measure shader behavior. |

## Step 3: Identify shader signals

Prefer a linear scene capture before SDR clipping, but keep intentional presentation scaling if it belongs to the vanilla look.

| Signal | Meaning | |---|---| | `untonemapped` | Linear scene/HDR source that will feed `ToneMapPass` or PsychoV. | | `neutral_sdr` | Linear vanilla ungraded SDR/reference baseline, such as an engineered SDR proxy, analytic vanilla tonemap, or neutral LUT-domain reconstruction. | | `graded_sdr` | Linear vanilla SDR after LUT/color grade/masks. |

`ToneMapPass`, PsychoV, and other tonemappers expect linear input in the shader's proven working color space. Do not feed encoded/gamma/sRGB values into `ToneMapPass`. If a LUT must be sampled in sRGB/gamma space, encode only for the LUT address/sample, then decode the sampled result back to linear before using it as `graded_sdr`, `neutral_sdr`, or tonemapper input.

For hard-clip/no-tonemap shaders, do not turn the HDR source into `neutral_sdr` with a raw hard clip. `ToneMapPass(untonemapped, graded_sdr, neutral_sdr)` uses `neutral_sdr` through `UpgradeToneMap`, so the neutral/reference baseline must be an engineered SDR/LUT-domain proxy, analytic vanilla tonemap, or other proven reference signal. The two-argument `ToneMapPass(untonemapped, graded_sdr)` defaults the neutral path to RenoDRT neutral SDR, which may be wrong for custom vanilla baselines. The Silksong-style repo path is the reference shape for this: keep SDR-like clip controls explicit, build a safe `neutral_sdr`/`graded_sdr`, then call `ToneMapPass(untonemapped, graded_sdr, neutral_sdr)` when that is the right bridge.

Do not assume a hard clip is safe just because it is vanilla. Hard clipping `untonemapped` for an HDR bridge can collapse highlights to white or wrong hues; `ToneMapPass` can then scale that damaged grade back up. A `saturate` on an already-tonemapped value may simply trim small vanilla overflow, and a Vanilla/0 branch may intentionally simulate the original RGBA8U/UNORM resource clamp after an upgrade. Those are not the same issue. Wobbly Life is the warning case: vanilla hard-clip-to-LUT sampling needed max-channel/N2 scaling, gamut compression, and reconstruction to preserve hue and saturation. Silksong goes further when the clip itself is part of the look by emulating hue and saturation clip effects selectively instead of blindly scaling clipped white.

In original/decompiled shaders, prefer a small injection shape:

1. capture `untonemapped`, `neutral_sdr`, or `graded_sdr` near the vanilla signal; 2. leave the vanilla computation readable nearby; 3. replace only the final color assignment or narrow branch with the RenoDX call.

Use [ToneMapPass injection snippets](./snippets/tone_map_pass.hlsl) as starting shapes for proven shader targets. Do not copy them until draw/resource analysis proves the source signals.

## Step 4: Choose the shader HDR strategy

| Strategy | Status | Use when | |---|---|---| | `ToneMapPass(untonemapped)` | Preferred | No SDR LUT/grade needs to be preserved. | | `ToneMapPass(untonemapped, graded_sdr)` | Preferred | A trustworthy graded SDR result exists and default RenoDRT neutral SDR is acceptable. | | `ToneMapPass(untonemapped, graded_sdr, neutral_sdr)` | Preferred | Custom neutral/reference baseline that is safe for `UpgradeToneMap`; not a raw hard clip of `untonemapped`. | | `ToneMapPass` with Vanilla/0 config | Valid mode | Keep the game's vanilla process as the tonemap while allowing user grading controls; pair with a true Off preset/reset when no custom grading is requested. | | `direct-psychov17` | Preferred for PsychoV | User requests PsychoV17 or observer tonemap; handle LUT bridge after PsychoV unless final SDR look is the reference. | | `extended-vanilla` | Situational | Preser