Shader Patch Effects System - PrismaticFlower/shaderpatch GitHub Wiki

Contents

Intro

Shader Patch's so dubbed "Effects System" is a way modders can apply configurable rendering effects to their maps when Shader Patch is installed. It is designed to be easy to use, customizable and performant.

My hope is that modders will use it to fine tune the art of their mods in ways that the vanilla game is incapable of. Emphasis must also be placed on the fact that a mod using the Effects System will continue to work just fine on copies of the game that do not have Shader Patch installed. (Save the effects provided by SP obviously.)

Getting Started

To get started we'll dive straight into the fun part. Fire up SWBFII and launch the map you want to apply the Effects System over. Once ingame you'll need to open SP's Devloper Screen, the default key to do this is \.

The first thing you're interested in is the window named Effects. This window has all the modder controls for the effects system. It's important to note that any changes made under the Control tab require the Direct3D device to be reset, which can be done by pressing Reset Device & Apply under the User Config window.

To enable the Effects System simply check the Enable Effects box and reset the device. After you've done that you can start fiddling around with the controls under the other tabs. Any changes made under the other tabs do not require the device to be reset and will adjust immediately; it is very much intended to be a seamless What You See Is What You Get experience.

Custom Materials and Embedded Configs

Effects configs can be embedded inside worlds, so that when the world is loaded the config will automatically be used until the end of the map.

Assuming you've integrated the SP tools into your world embedding a config is straightforward. The first thing you need is for world to have a regular MAP.fx file, it can be empty, but the existence of the file is important. Next you just need use the Devloper Screen to save out your config under the name MAP.spfx and this is important it must be in the same folder as MAP.fx. After that you're done! Whenever the SP version of your map is loaded it should now include your config.

Now for a couple of gotchas. If you're map didn't already have MAP.fx it's possible you'll also need to add a reference to it in MAP.req. This just looks like this.

	REQN
	{
		"envfx"
		"MAP"
	}

Secondly on maps with water it quite common to copy-paste the water config from a stock map into MAP.fx. If you do this then you'll possibly need to find this line in the config.

WaterSplashColor((192, 192, 192,255);
// And change it to this.
WaterSplashColor(192, 192, 192,255);

This is because the parser for .fx files in spfx_munge is more primitive and less forgiving than Pandemic's and the double ( will trip it up.

Saving Config for Direct Use

Integrating SP's mungers to your toolchain and outputting a separate .lvl to just use the Effects System is likely overkill and something most people don't need to do. To just use the Effects System by itself all we need to is save out the munged config and load it up explicitly from our Lua script.

Saving the needed config is easy, it can just be done from the Effects window. At the bottom of the Control tab are buttons for Saving and Opening configs. There are two ones for save Save Config and Save Munged Config. In this case click on Save Munged Config, navigate to where you want the config saved and hit Save. (Due to a strange bug you may have some difficulty changing the name of the saved file, in this case simply rename the file after you've saved it.)

Be aware that SP can not load munged config's from the Devloper Screen, as such if you want to reload it from the Devloper Screen also save a copy of the config that isn't munged.

Now all that is left to is load the .mspfx file from your Lua scripts. The simplest way to do this to start with is to assume we're using one config for the entire mod and copy the .mspfx into the same folder as the mod's core.lvl.

Then at some point in your Lua code, likely just after you've loaded the world's .lvl, you'll put the following snippet.

-- Load the Shader Patch API
ReadDataFile("shader_patch_api.script")
ScriptCB_DoFile("shader_patch_api")

-- Check if Shader Patch is installed and if it is test the version.
local useShaderPatch = gSP_Installed and SP_TestVersion(1, 0, 0)

if useShaderPatch  then
   -- In this example we'll have put mod_config.mspfx in the same folder as core.lvl
   ReadDataFile("dc:mod_config.mspfx")
end

And we'll be all done. Aside from the fact that manually copying the config may be a bit laborious and we may want to have different configs for each world. In which case read Direct Use and Per World Configs next. Else you're done!

Direct Use and Per World Configs

Having just one effects config is useful and easy but it lacks flexibility. If on one world you want to increase the brightness but on another you want to to decrease you'll quick start to get frustrated. Thankfully using a different config for each world isn't too much work and still doesn't require us to integrate SP's mungers. So firstly we'll need to put this line

The system we're going to create for doing this is going to involve us putting the munged effects config into our worlds munged folder. (This is not the folder used during the munge process, this is one that goes alongside msh, odf, effects, world1, etc, if you don't have one for your world the create it!) From there we'll setup the munge scripts to automatically copy our *.mspfx files to be alongside our world .lvl.

Since the munge process pulls in everything from the munged when performing a munge all we need to do is add this line to our munge_world.bat script.

xcopy %MUNGE_DIR%\*.mspfx %OUTPUT_DIR% /D /Q /Y

Don't worry if you don't understand that line or have never edited your munge scripts before, because over here you can find a munge_world.bat with the changes already applied. Just copy that over _BUILD/Worlds/munge_world.bat and you'll be good to go!

Now after we've done that and save configname.mspfx config in the aforementioned munged folder of our map, all we then need to do is update our Lua script to this.

if useShaderPatch then
   ReadDataFile("dc:mapID\\configname.mspfx") 
end

Now you never need to worry about copying around the Effects config and you have the ability to use a unique config with each of your maps.

Saving Config for use with Custom Materials

TODO: Write documentation here.

Individual Effect Documentation

TIP: In the Developer Screen, anytime you see a color editor you can click on the color preview icon to bring up a color picker.

Control Config

This one isn't actually an effect, rather it is the grouping used for settings that alter how the entire Effects System works.

Control.HDR Rendering

Switching this on causes two things to happen. The first one is that the game will be drawn to 16-bit floating point render targets, allowing pixels to go above 1.0 in brightness. The second is that the game will be (with some guesswork) drawn in a linear colour space. However for correct results any normal mapped surfaces must be drawn using custom materials.

This is mostly here so PBR materials can be drawn correctly and for future extensions. Switching it on does come at a slight performance cost and does produce visually different results. (Whether or not it looks better or not for your mod is something for you to decide.)

Control.Request Order-Independent Transparency

Informs Shader Patch that the current map contains geometry that will only render correctly if Order-Independent Transparency is applied. If OIT is supported on the user's GPU it will be turned on for maps that set this, even if the user has OIT switched off.

Only use if your map requires it as OIT isn't free.

Post Processing.Color Grading

Always active post-processing Effect. Let's you adjust things like Exposure/Brightness, Saturation, Contrast, etc. Like all Post Processing Effects it is done before the interface/HUD is drawn and only ever affects the world.

Post Processing.Color Grading.Color Filter

A color to multiply the entire scene by. A typical use case would be to tint a specific the scene to adjust the overall feeling of the scene. Works better with light colors rather than dark ones.

Post Processing.Color Grading.Exposure

Adjust the exposure of the scene in EV space. Where by each step up is twice as bright (or dark) as the last. The following table illustrates this relationship.

Exposure Brightness Factor
-1.0 0.5
0.0 1.0
1.0 2.0
2.0 4.0

Post Processing.Color Grading.Brightness

Adjust the brightness of the scene. Provided as a convenience alternative to tweaking Exposure.

Post Processing.Color Grading.Saturation

Adjust the satruation of the scene, making colors more or less 'vibrant'.

TIP: Normally I like to refrain from giving out artistic advice but I see so many people go too crazy with Satruation in their color grading that I feel I must place a few points for people to keep in mind here.

First remember that more vibrancy isn't automatically better. I've definitely noticed that people tend to be drawn to vibrant screenshots but there is a lot more to a game's art style than how it screenshots.

Be sure to spend time actually playing the time and getting a grip on how the change
impacts the feel of the game. Basically make sure your art style invokes the desired
feeling in the player and isn't just visually striking (where in screenshots well but ultimately doesn't serve gameplay well).

The second thing is very related to the first and it is to not be afraid of decreasing the Saturation. If you're wanting say a harsh feeling environment doing so may help a fair bit in creating that feeling.

Overall the general point is use Saturation (and Color Grading) to help create the feel of the world, not to help create screenshots.

Post Processing.Color Grading.Contrast

Increas or decrease the contrast of colors in the scene.

Post Processing.Color Grading.Shadows Color

Adjust the tint of shadow colors in the scene.

Post Processing.Color Grading.Shadows Offset

Offset the luminance of shadow colors in the scene.

Post Processing.Color Grading.Midtones Color

Adjust the tint of midtone colors in the scene.

Post Processing.Color Grading.Midtones Offset

Offset the luminance of midtone colors in the scene.

Post Processing.Color Grading.Highlights Color

Adjust the tint of highlight colors in the scene.

Post Processing.Color Grading.Highlights Offset

Offset the luminance of highlight colors in the scene.

Post Processing.Color Grading.Channel Mixer

Mix color channels with each other. The Red, Green and Blue controls each respectively control which colors will contribute their channel's final color. By default each channel is made up using only itself.

Post Processing.Color Grading.HSV Adjustments

Adjust the colors in HSV space. The Hue adjustment will be added in while the Saturation and Value adjustments will be multiplied in.

Post Processing.Tonemapping

Shader Patch comes with the ability to render the game to floating point render targets, in a linear color space and some custom materials (PBR ones) even require it to be. Even when this feature is disable the Effects System does it's post processing in a linear color space using floating point textures.

Both these things possible for some very bright surfaces to find their way into the scene Shader Patch provides several tonemapping options that can be used to reign everything in for display.

Post Processing.Tonemapping.Tonemapper

Select the tonemapper to use. The options are below. Expirement around and pick the one that is best for your map, although if in doubt ACES is a good simple option used by many modern games.

Post Processing.Tonemapping.Curve Preview Range

Sets the range of input values for the curve preview.

Post Processing.Tonemapping.Filmic.Toe Strength

Controls the strength of the toe at the bottom of the curve.

Post Processing.Tonemapping.Filmic.Toe Length

Controls the length of the toe at the bottom of the curve. John Hable's recommends setting this to a constant value and using Toe Strength adjust the toe, but that doesn't mean you shouldn't play around with it. Just be aware of that.

Post Processing.Tonemapping.Filmic.Shoulder Strength

Controls where the shoulder curve starts.

Post Processing.Tonemapping.Filmic.Shoulder Length

Controls how many F-stops to add into the dynamic range of the curve.

Post Processing.Tonemapping.Filmic.Shoulder Angle

Controls how much overshoot to add to the shoulder, the more overshoot the steeper the angle of the curve.

Post Processing.Tonemapping.Filmic Heji 2015.Whitepoint

The whitepoint for the Filmic Heji 2015 tonemapper.

Post Processing.Bloom

Effect that causes bright pixels to bleed into their neighbours. Effectively a nicer looking, more configurable version of the game's stock bloom.

Not documented here are the 'Individual Scales & Tints' settings. These settings are no longer well defined or intuitive and will likely be removed to eke a little bit more performance out of the Bloom shaders.

Post Processing.Bloom.Enabled

Whether or not the Bloom Effect will be used or not.

Post Processing.Bloom.Threshold

The brightness threshold a pixel has to pass in order to contribute to the Bloom.

The default value for this is 0.5 and should be good in most cases as this is the treshold used by the game's stock bloom by default. If you have a different threshold for the stock bloom you should set this to that.

When using HDR Rendering you should set this to at least 1.0 or higher.

Post Processing.Bloom.Intensity

Sets the scale for the overall intensity of the Bloom. Lower values give a softer glow while higher values give a more overwhelming glow.

Post Processing.Bloom.Tint

Sets the color to tint the Bloom with.

Post Processing.Bloom.Use Dirt

Whether to use a Lens Dirt texture or not.

Post Processing.Bloom.Dirt Scale

Intensity scale applied to the Bloom dirt.

Post Processing.Bloom.Dirt Tint

Sets the color to tint the Dirt with.

Post Processing.Bloom.Dirt Texture

Sets name of the texture to use as the Lens Dirt. The texture must be munged with sp_texture_munge and be available (loaded) ingame.

There are currently no builtin dirt textures but I would like to change this.

Post Processing.Vignette

Vignette is a lens effect that causes the edges of an image to be darkend. It is a very cheap to evaluate effect and it can help draw the player's focus to centre of the screen.

Because of how cheap it is to evaluate the effect is enabled by default, so remember to disable it if it doesn't fit your mod's art style.

Post Processing.Vignette.Enabled

Whether to use the Vignette effect or not.

Post Processing.Vignette.End

End distance of the darkening. Lowering this will increase the darkening around the image edges, while increasing it will decrease the darkening around the image edges.

Post Processing.Vignette.Start

Start distance of the darkening, increasing this will increase the distance (from the centre of the image) at which the image starts to darken, while decreasing it will reduce it.

TIP: To see the way the falloff of the effect works set End to 0.5 and Start to 0.0.

Post Processing.Film Grain

This effect adds visual noise to the scene to simulate Film Grain. This effect is off by default because of how art style dependent it is. For some art styles it'll be a great fit and for others it won't be. In the former case the effect comes with some nice settings to let you tweak it to (hopefully!) be just what your mod needs.

Post Processing.Film Grain.Enabled

Whether to use the Film Grain effect or not.

Post Processing.Film Grain.Colored

Whether the Film Grain will be colored or not. Colored Film Grain uses different noise values for each color channel.

Post Processing.Film Grain.Amount

The overall visibility of the Film Grain.

Post Processing.Film Grain.Size

The size of the noise in the Film Grain.

Post Processing.Film Grain.Color Amount

The amount each color channel will differ from each other when Colored Film Grain is enabled. A value of 0.0 would effectively be the same as having Colored Film Grain off, while a value of 1.0 will make each color channel completely independent.

Post Processing.Film Grain.Luma Amount

Controls the overall luminance of the Film Grain. Lower values will cause the Film Grain to primarily show up in brighter parts of the image.