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. 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. Unreal offers no way for a plugin to change its tone mapper and keep its own colour grading without editing this file. The original is backed up first and restored when you close the editor, or at the next launch after a crash. 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 changes nothing.
• 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 the tone mapper is the only thing that changes.

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. 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. 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, so the packaged game looks the same as the editor. The plugin's code is not included in packaged builds.

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.

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):

• HDR output.
• 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 that matches Blender's default look, so scenes look the same in Blender and Unreal.

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 (ColorCorrectAll: white balance, 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. Steps 1 and 3 are unchanged, and so are Tone Curve Amount and the 5.8 Standard ACES path.

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 the only way to change it while keeping 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.
• 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 each anchor appears exactly once, 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 more than once, for example on an unsupported engine version, nothing is written.
• 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.
• Standard ACES 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, so the per-pixel cost is the same as Filmic. The plugin's modules are UncookedOnly and Editor, so neither is included in packaged builds.

Known limitations

• SDR output only for now. HDR output is planned (see Roadmap).
• 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 with Epic Games Launcher engine installs; engines built from source have not been tested.

Automation tests

Seven 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, 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.

Unreal® Engine is a trademark of Epic Games, Inc.