Color grading in GZDoom

[exl]

If you've ever wanted to do those color grading post processing effects like modern games do, you can now use this PK3! You can do subtle mood-altering effects:

 

 

Or go for something crazy:

 

 

 

 

All you'll need to do is integrate the code from the PK3 in your own project as described in the readme (also readable down below). Then you can make your own color grading LUT texture consisting of up to 16 LUTs. The image below shows part of such a texture with a couple of the included example LUTs:

 

 

You could do some of these effects with PLAYPAL\COLORMAP modifications, but the big advantage of these is that you can set these during runtime and transition smoothly between them, as demonstrated in the included demo map. These will however only work in a hardware rendering mode as they utilize a fragment shader.

 

Download PK3 with the code and a demo map

 

Full instructions:

Spoiler

This includes a fragment shader and some ZScript to control the selection of a
pixel look-up table used to alter the colors of the rendered map. This is used
in many modern games to apply a color grading effect to alter the mood or
atmosphere of a certain scene. With more extreme modifications to a LUT you can
even accomplish some pretty interesting effects as can be seen in the included
example map.

 

Usage
Any map wishing to use this has to import the acs/colorgrade.acs library in
their map's ACS, after which they can use the ColorGradeSet, ColorGradeTo and
ColorGradeTransition ACS named functions to alter which color grading LUT is
active.

 

The event handler "ColorGradeEventHandler" must also be added for each map in
MAPINFO data. See the PK3 file for a barebones example.

 

The included map is a demonstration of some of the default included LUTs. It
demonstrates how to use the ColorGrade* functions using ACS_ExecuteAlways and
line actions. Some LUTs are pretty subtle and will work best when the map or
area is designed around them.

 

ColorGradeSet immediately sets the supplied LUT index on the player who called
the script.

 

ColorGradeTo transitions to the supplied LUT index over the course of the
specified number of tics. If a transition is already taking place, the LUT is
queued to transition to after the current transition is done.

 

ColorGradeBetween is meant to be used as a linedef action. It will transition to
a LUT depending on which side the line is triggered from. This is useful to mark
a LUT "boundary" between two areas without having to use two linedefs with a
ColorGradeTo call.

 

The transition speed is measured in ticks. If a speed of 0 is used, a default of
70 ticks is used instead.

 

Creating custom LUTs
Opening the pplut.png texture will show all the default LUTs. There is room in
the texture for 16 LUTs, with the last one (index 15) being a "dummy" LUT of
unaltered color values. LUT 0 will be active by default.

 

Each LUT represents a low resultion map of all possible colors. For every pixel
in the output, the color grading fragment shader looks up at which coordinates
in the LUT that color is, then returns an interpolated color from the LUT to be
used instead.

 

The easiest way to alter the default LUT and create your own is by taking a
screenshot of the area of your map that you want to make a LUT for. Then add the
default LUT as a layer in your favorite photo editing application. By applying
color effects to the entire image you can experiment to reach your desired
effect. Make sure to not use any masked effects or effects that alter the image
physically instead of just the colors.

 

When done, copy the modified LUT from the corner of the image and place it in
the pplut.png texture at a vertical offset of your choice. You can then
reference that LUT from map actions by it's index from the top (starting at 0,
ending at 15).

 

Performance
The shader does incur a very small performance penalty. At 1920x1080 resolution
and 1x render scale the shader requires around 0.18 ms to do it's job. At 2x
render scale (so effectively 3840x2160) the shader needs 0.69 ms. This is using
a reasonably old AMD Radeon R9 280X GPU which was released in 2013.

Disabling

Players can disable the color grading effect by using the option in the Display
options > Hardware renderer > Postprocessing menu, or using the r_colorgrading
console variable.

 

[Tango]

this is fantastic, thanks so much for sharing exl :D

[elend]

Fantastic stuff, would love to incorporate that into my map. The instructions sound awfully complicated, though. xd

[Nevander]

Minimum required GZDoom version?

[exl]

It's been tested with 3.7.2 and the recent 4.0, but it should work with some earlier versions too, or whenever postprocessing shader support was introduced. I can't find the exact version version number from when that was.

[Tormentor667]

Absolutely brilliant indeed. Though, is there an explanation somewhere how the pplut.png texture works? I have absolutely no idea how the mechanique behind the texture works.

 

*EDIT*

Maybe even a photoshop tutorial might be of good use :)

 

*EDIT2*

After fiddling around for a while I got it working now. This is pretty awesome indeed, I just need to learn now how to implement that properly. For some reason I have the feeling that it somehow makes fog and light colors a bit redundant if you used them before in larger scale areas. Are there any subtle examples in other games?

Edited April 10, 2019 by Tormentor667

[exl]

The color grading section of http://www.adriancourreges.com/blog/2017/12/15/mgs-v-graphics-study/ has a good visual explanation of how it works, and shows an example of it. This Gamasutra article is an excellent deep dive into colors used in games. A few other examples and explanations:

 

https://www.gamedev.net/articles/visual-arts/unity-lut-color-correction-in-our-game-immortal-redneck-r4389/

https://www.youtube.com/watch?time_continue=84&v=xkAzeukUzlQ

https://imgur.com/gallery/Lt4YH

 

[Linguica]

Is this compatible with InstaDoom?

[exl]

It's mostly just a GZDoom post processing shader. It'll work on top of any PLAYPAL changes and can be toggled on, off, and crossfade between or set a LUT. But for hardware rendering only.

[Gez]

On mardi 9 avril 2019 at 8:05 AM, exl said:

It's been tested with 3.7.2 and the recent 4.0, but it should work with some earlier versions too, or whenever postprocessing shader support was introduced. I can't find the exact version version number from when that was.

The ZScript requires version 3.7.2 minimum, if you try to load with an older version you'll get an error message during startup. It might work if you edit the ZScript code to put in a lower version, I dunno, but as-is it's 3.7.2 minimum.

[MFG38]

On 4/9/2019 at 9:05 AM, exl said:

It's been tested with 3.7.2 and the recent 4.0, but it should work with some earlier versions too, or whenever postprocessing shader support was introduced. I can't find the exact version version number from when that was.

 

Trying to launch this in GZDoom 3.7.2 gives me the following error message:

Script error, "colorgrd.pk3:menudef.txt" line 1:
PostProcessMenu is not an option menu that can be extended

 

[exl]

Oh right, it does reference a menu new to 4.0. You can remove menudef.txt if you don't care about the menu option, or change the menu that it appends the option to.

[Tormentor667]

I noticed that the game crashes if you put the grading script into an OPEN Script. Can this be fixed?

[exl]

Since the color grading is applied on a per-player basis, and the ColorGrade* functions operate on the current player (through PlayerGet) it doesn't make much sense to call it from an OPEN script. It will however work from an ENTER script where it will run for each player individually.

[Ozymandias81]

Hi exl, and wow quite 6 years I think that I didn't post anything on Doomworld... Any hope to include somewhere the non-compiled library for this awesome thing? Since as Torm I am involved in Blade of Agony development, it is important for us to have such source code in order to embed the whole thing in our particular ACS setup, so we can track exactly what it is happening and merge the whole code without compiling the library, instead using it open like we did with all other scripts present on the project (the boalib.acs once compiled has #include references which points up on a folder, so we can work easily this way via github, slade and gzdbuilder to optimize also the load order of each library due to the complexity of BoA whole code "tree"). Any chance? Thanks in advance.

[MFG38]

53 minutes ago, Ozymandias81 said:

Any hope to include somewhere the non-compiled library for this awesome thing?

 

Quoting because I'd like that as well, if for other reasons.

[exl]

Sure thing, here's the full build source I used. The ACS is not at all noteworthy but just a simple link to ZScript.

[Tormentor667]

Thanks kindly for sharing that and thanks for the information. Calling it on an OPEN script makes sense in terms of a global change of a map or for a cutscene sequence for example that can't be launched on a ENTER basis but only on an OPEN basis.

[exl]

Ok, I've updated the zip file in the first post so that any call done without a player as a trigger will instead affect all players present in the map. Additionally _metal_ from the ZDoom forums found a compatibility bug in the fragment shader so it should now also work on macOS. The entire source is included in the zip this time.

 

Edit: BTW, will 16 LUTs be enough for your uses? Blady of Agony seems like a large project that might need more than 16. The fragment shader would have to be adjusted so that it can work with 64 LUTs in a 512x512 texture.

[Ozymandias81]

6 hours ago, exl said:

Ok, I've updated the zip file in the first post so that any call done without a player as a trigger will instead affect all players present in the map. Additionally _metal_ from the ZDoom forums found a compatibility bug in the fragment shader so it should now also work on macOS. The entire source is included in the zip this time.

 

Edit: BTW, will 16 LUTs be enough for your uses? Blady of Agony seems like a large project that might need more than 16. The fragment shader would have to be adjusted so that it can work with 64 LUTs in a 512x512 texture.

Atm I think we are fine as is, BoA is already complex okay but 16 LUTs are enough ime... In case you wanna improve it for us and if you are familiar with Github, you can send us a pull request if you notice something that may need adjustments with actual state of the project, like playtesting it and giving us some clues about where you would suggest to implement colorgrading.
I have suggested for now to use it even for poisonus effects, so with mutants and zombies related attacks.
Today I have committed and implemented the source code, if you wanna give a look check the repository then and thank you in advance in any case :)