Easy Tonemapper

PART 1

Using Easy Tonemapper

What the plugin does, whether you need it, and how to use it. The technical reference below explains exactly what it changes.

What it does

Unreal renders your scene with a far wider range of brightness than a screen can show. A tone mapper squeezes that range down into the final image. Unreal's default, Filmic, handles very bright, saturated colour in a particular way: a bright red light can drift toward orange, and strong colours wash out toward white.

Easy Tonemapper replaces Filmic with a tone mapper of your choice. Exposure, bloom and your Post Process Volume colour grading carry on as before (in SDR; see HDR output for what has been checked in HDR). The one exception is Blue Correction, an ACES-specific adjustment, which is switched off by default (see Settings).

Is it right for your project?

A quick way to judge: open the included test chart, or put a bright red or blue light in one of your scenes, and compare Filmic with AgX.

Before you start

• The plugin changes one engine file while the editor is open. That is how it swaps the curve inside Unreal's own colour-grading LUT build, which keeps your Post Process Volume grading working in SDR (see HDR output for HDR). The original is backed up first and restored when you close the editor and from the crash handler; after a crash or forced shutdown, opening a project with Easy Tonemapper enabled restores it. Your tone mapper choice stays saved in your project. See Safety and recovery.
• Your engine install must be writable. Standard Epic Games Launcher installs are. If yours isn't, the plugin tells you and leaves the engine file untouched.
• If your studio forbids modifying the engine installation, don't use this plugin.
• On UE 5.8, try Epic's option first: Post Process Volume → Film → Method → Standard ACES. It's free and may be all you need.
• Existing scenes will look different after switching, and scenes tuned under Filmic may need some re-grading. That's true of any tone mapper change.

Quick start

1. Install the plugin from Fab (or copy the EasyTonemapper folder into your project's Plugins folder), enable it in Edit → Plugins, and restart the editor.
2. Open the Easy Tonemapper menu from any of these:
   • the Easy Tonemapper button in the level editor toolbar
   • Tools → Rendering → Easy Tonemapper
   • Project Settings → Plugins → Easy Tonemapper
3. Choose a tone mapper from the drop-down list. It's applied straight away: the shader recompiles in a few seconds and the viewport updates. The menu always shows the tone mapper that's active.

To go back to Unreal's default at any time, choose Restore Engine Defaults.

Test chart

The plugin includes a small map that shows what a tone mapper does to bright colour: rows of glowing spheres in red, orange, green, blue and white, each column two stops (4×) brighter than the one before. Exposure is fixed and bloom is off, so only the tone curve changes (plus Blue Correction, which is off by default while another tone mapper is active).

1. In the Content Browser, open Settings and tick Show Plugin Content.
2. Open Easy Tonemapper Content → Demo → Maps → ToneMapperTestChart.
3. Switch tone mapper and compare the right-hand columns.

What to look for: under Filmic, bright red turns orange and then yellow, bright green turns yellowish, and bright blue turns pale cyan. Under AgX each colour keeps its hue as it fades to white. In the first two columns, at ordinary brightness, the difference is small.

For the chart's intended framing, right-click Chart Camera in the Outliner and choose Pilot.

Choosing a tone mapper

Tuning the look with the Film sliders

While a tone mapper other than Engine Default is active, the five Film sliders in your Post Process Volume adjust that tone mapper instead of Filmic (in SDR; see HDR output for HDR). Not every slider acts on every tone mapper (see Film slider mapping). Changes show up immediately, with no shader recompile — a quick way to find the look you want.

An untouched Post Process Volume gives each tone mapper's standard look; nothing changes until you move a slider. Like any post-process setting, the sliders work per volume, but most projects set them once for a consistent look.

To use a slider, tick its box in the volume's Film section. The Easy Tonemapper menu shows what each slider does for the tone mapper you've selected, under Fine-Tuning (its wording differs slightly from this table). For AgX, for example:

The full table is in Film slider mapping. To leave the sliders alone, turn off Map Film Sliders To Operator.

Settings

Project Settings → Plugins → Easy Tonemapper, or Advanced Settings... in the Easy Tonemapper menu.

Every change is applied as soon as you make it, here or in the menu.

Settings are saved in Config/DefaultEasyTonemapper.ini, so they can go into source control and be shared with your team.

Packaging your game

The tone mapper you've selected is compiled into your game's shaders when you package a Windows build. The plugin's code is not included in packaged builds. HDR in a packaged game has not been checked (see HDR output).

If your project doesn't list which maps to package, Unreal packages every map and asset it can find, and that includes the plugin's test chart (about 320 KB). To leave it out, add /EasyTonemapper/Demo to Project Settings → Packaging → Directories to never cook.

Movie Render Queue

Render (Local) and Render (Remote) both use the tone mapper you've selected.

Render (Remote) starts a second Unreal process. Its log says Easy Tonemapper is inactive there, because your editor already owns the engine file. That's expected: the render still uses your editor's tone mapper. Keep the editor open until the render finishes.

HDR output

On UE 5.0 to 5.7 your curve applies on Unreal's ACES 1000 and 2000 nit HDR output devices (PQ and scRGB). On UE 5.0 to 5.7, on those four ACES devices, Engine Default uses Unreal's own HDR output transform (ACES), not Filmic. Other HDR output devices have not been checked. How far this has been tested is listed at the end of this section.

Where a pixel's brightest colour channel is below four fifths of SDR white, the picture is the same as the SDR picture from the same tone mapper (this is not Unreal's own HDR look). Above that, pixels are brightened on a smooth curve, measured in stops, towards the output's peak, scaling the whole pixel so hue and saturation are untouched in the scaling.

On UE 5.0 to 5.5 the peak is a fixed 1000 or 2000 nit preset for the output device; it is not read from your display. On UE 5.6 and 5.7 the code uses the peak Unreal reports when HDR output is running and the same preset otherwise; the reported-peak path was not observed. Very saturated highlights can read above the peak after Unreal's colour conversion.

On UE 5.8 the plugin adds nothing to HDR: the curve you pick feeds Epic's own HDR path, which does the expansion while Film → Method is Filmic. That is read from Unreal's shader and was not tested.

From reading Unreal's shader, on UE 5.0 to 5.7 Post Process Volume white balance, saturation, contrast, gamma, gain and offset are applied before the HDR step; that was not tested in HDR.

To set up HDR output, follow Epic's steps, for example r.AllowHDR=1, then r.HDR.EnableHDROutput 1 or the Enable HDR Display Output node. Nothing needs switching on in the plugin. Windows also needs HDR switched on for the display ("Use HDR" in Windows display settings). These are Epic's and Windows' steps, not the plugin's, and they were not used as written in the HDR checks described below.

How far this has been tested:

• HDR was checked by decoding captured frames of the included test chart from the ACES 1000 nit PQ output back to nits, on UE 5.0, 5.6 and 5.7 only, with the output device forced on an ordinary monitor.
• The 2000 nit and scRGB outputs were not measured.
• UE 5.1 to 5.5 were not measured: on the test machine, which has no HDR display, UE 5.1 would not switch to an HDR output device.
• HDR on UE 5.8 was not tested.
• HDR in a packaged game was not checked.
• The Color Grading LUT, Tone Curve Amount and Blue Correction have not been checked in HDR.
• None of it has been viewed on a physical HDR display.

Troubleshooting

Still stuck? Ask in the SDProjects Discord support channel ↗.

Removing the plugin

1. Choose Restore Engine Defaults from the Easy Tonemapper menu.
2. Close the editor.
3. Delete the EasyTonemapper plugin folder (or uninstall it through the Launcher). You can also delete Saved/EasyTonemapper and Config/DefaultEasyTonemapper.ini from your project.

Roadmap

Planned updates (none of these are included in the current version):

• Before/after images: save your viewport side by side, Unreal's default next to your tone mapper.
• Match Blender out of the box: an AgX option aimed at matching Blender's default look.

PART 2

Technical reference

For technical artists and programmers who want to know exactly what the plugin changes.

Where it hooks into the pipeline

Unreal bakes tone mapping into a 3D colour-grading LUT built in /Engine/Private/PostProcessCombineLUTs.usf. In that pass:

1. Post Process Volume grading (white balance, then ColorCorrectAll: saturation, contrast, gamma, gain, offset) runs in scene-referred linear space.
2. The tone curve runs — FilmToneMap for Filmic.
3. A user Color Grading LUT, if any, is applied to display-referred values.

Easy Tonemapper replaces the call in step 2. In SDR, steps 1 and 3 are unchanged, and so are Tone Curve Amount and the 5.8 Standard ACES path.

On UE 5.0 to 5.7 the four ACES HDR output devices (1000 and 2000 nit, PQ and scRGB) take a separate branch of the same file that never calls the tone curve in step 2: it hands the graded colour from step 1 straight to an ACES output transform, so Easy Tonemapper replaces that call as well (see What changes in the engine file). UE 5.8 routes its HDR branches through the same tone-curve call as SDR while Film → Method is Filmic, so nothing more is replaced there (as read from Unreal's shader; HDR on UE 5.8 was not tested). What has been checked in HDR is listed under HDR output.

Why not a LUT, a post-process material or a Scene View Extension

• Filmic applies its S-curve to each channel separately, in AP1. That's what shifts the hue of bright, saturated colour, and grading can't prevent it because grading runs before the curve.
• A Color Grading LUT runs after the curve, so it can't recover what the curve has already compressed.
• A post-process material in the Replacing the Tonemapper slot needs no engine edits, but Unreal then skips building its colour-grading LUT, so Post Process Volume grading stops applying. (Checked in the UE 5.0 and 5.8 renderer.)
• A Scene View Extension subscribed to EPostProcessingPass::ReplacingTonemapper does the same: the LUT pass is skipped, and the extension receives only scene colour and bloom, so exposure, local exposure, vignette, film grain, chromatic aberration and output encoding all have to be reimplemented. That pass only exists from UE 5.6. (Checked in the UE 5.8 renderer and in all nine engine versions' headers.)

Swapping the curve inside the LUT build is how this plugin keeps Unreal's own grading path.

What changes in the engine file

The plugin edits PostProcessCombineLUTs.usf in place:

• The call FilmToneMap( ColorAP1 ) is rerouted to EasyTonemapper_ToneMap( ColorAP1 ).
• The two Blue Correction lines are scaled by a define, so the setting can switch it off.
• On UE 5.0 to 5.7 only, the call that applies Epic's ACES output transform on the four ACES HDR output devices (1000 and 2000 nit, PQ and scRGB) is rerouted to EasyTonemapper_ToneMapHDR(...). On UE 5.0 to 5.5 that is two lines, one for each of the 1000 and 2000 nit transforms. On UE 5.6 and 5.7 it is two lines (the ACES 1.3 and ACES 2 versions), and each appears twice, once in the PQ (ST2084) branch and once in the scRGB branch; both are rerouted. UE 5.8 needs no such edit, because its HDR branches already go through the call above while Film → Method is Filmic (as read from Unreal's shader; HDR on UE 5.8 was not tested).
• After #include "TonemapCommon.ush", one fenced block is inserted: the current settings as #defines, followed by the plugin's shader code written out in full.

The code is inlined rather than included from the plugin's folder so that any project on the same engine version can compile the file, including projects that don't have the plugin. Before writing, the plugin checks that each anchor appears the number of times it expects (once, except the two HDR lines on UE 5.6 and 5.7, which appear twice each), and refuses shader code that includes anything outside /Engine/. No copy of an Epic shader file is shipped or swapped in.

Safety and recovery

• Backup first. The original is copied to <Project>/Saved/EasyTonemapper/Backups/ with a manifest recording its hash and engine version. The patched file starts with a marker carrying the same hash.
• Refuses rather than guesses. If any anchor is missing, or appears a different number of times than the plugin expects (for example on an unsupported engine version), the engine file is left untouched.
• Restored automatically on editor exit and from the crash handler. If neither got the chance, for example after a forced shutdown, the next launch of a project with the plugin restores it.
• Engine Default leaves the file byte-identical to a clean install.
• UE 5.8's Standard ACES method is never touched.

Several editors and engine versions

Projects on the same engine version share one engine file, so the plugin holds one lock per engine version (in %LOCALAPPDATA%/EasyTonemapper). Only the first editor opened on that version applies its settings; any other shows a warning and leaves the file alone. While the first is open, other projects on that engine version — with or without the plugin — compile the patched file and use its tone mapper. A lock left behind by a crashed editor is taken over automatically.

Different engine versions have separate locks and don't affect each other.

Film slider mapping

Each slider is measured from its engine default (Slope 0.88, Toe 0.55, Shoulder 0.26, Black clip 0.0, White clip 0.04). The sliders are already bound shader parameters on the LUT pass, which is why changes need no recompile.

For GT and Lottes, the resulting parameters are clamped to the ranges where the curve rises smoothly to white with no dips or overshoot, checked numerically over every combination of the sliders across their full range. Pushing a slider to its end simply stops having an effect past that point.

Operators

Performance

The tone curve is evaluated while Unreal builds its colour-grading LUT, not per pixel. The plugin's modules are UncookedOnly and Editor, so neither is included in packaged builds.

Known limitations

• HDR highlights are expanded, not re-derived. On UE 5.0 to 5.7, on Unreal's ACES 1000 and 2000 nit HDR output devices (PQ and scRGB), your tone mapper's curve is what shapes the image. Where a pixel's brightest colour channel is below four fifths of SDR white, the picture is the same as the SDR picture from the same tone mapper; above that, pixels are brightened on a smooth curve, measured in stops, towards the output's peak. The expansion is monotonic, so values the curve maps to different levels stay different; anything the curve clips to white stays white and is brightened as white. Very saturated highlights can read above the peak after Unreal's colour conversion. On UE 5.8 the plugin adds nothing to HDR: the curve you pick feeds Epic's own HDR path, which does the expansion while Film → Method is Filmic; that is read from Unreal's shader and was not tested. Measured on UE 5.0, 5.6 and 5.7 only (1000 nit PQ output) and not viewed on a physical HDR display; the full testing limits are under HDR output.
• Auto-exposure on UE 5.6 and later meters through Epic's Filmic curve (PostProcessHistogramCommon.ush) rather than the selected tone mapper.
• Windows only. Tested in SDR with Epic Games Launcher engine installs. Engines built from source have not been tested.

Automation tests

Eight tests ship with the plugin. Run them from the editor console:

Automation RunTests EasyTonemapper

They check that a patch round-trips back to byte-identical stock, that the patched file is self-contained, that unsafe shader code is refused, that settings survive a reload, that the HDR output branches are hooked on UE 5.0 to 5.7 (UE 5.8 needs no separate HDR hook), and that the anchors still match your installed engine. That last check reads the engine file only; no test writes to your engine.

Licence and credits

Copyright © 2026 SDProjects. Licensed under the Fab Standard License, which licenses plugins per user: each person using the plugin needs their own licence.

Easy Tonemapper builds on published work by Troy Sobotka (AgX), Benjamin Wrensch (real-time AgX), Erik Reinhard et al., John Hable, Hajime Uchimura, Timothy Lottes and the Khronos Group. Full attribution and licence texts are included with the plugin, in Source/ThirdParty/THIRD_PARTY_NOTICES.md and beside the code they cover under Source/ThirdParty.