1. KornnerStudios
  2. OpenSauce-Release

Wiki

Clone wiki

OpenSauce-Release / Halo1 / Doc_Halo1_PostprocessingFull

OpenSauce Post Processing

What is post processing?

Generally a post process is something that happens after something else. In the context of computer graphics it can refer to a technique used to change how a rendered frame looks by taking a frames colour data and manipulating it with pixel and vertex shaders before presenting it to the viewer.

Using the post processing system of OpenSauce you can enhance your maps by adding post processing effects that change the visual style of your map or add new gameplay functionality.

The Post Processing system

In OpenSauce there are two applications of the post process system available to the general user:

  • The "Internal" post process system is the system that map makers use to add their own unique visual effects to their maps through the use of custom tags added to the OpenSauce HEK.
  • The "External" post process system can be used by anybody with some HLSL knowledge to customise their own personal installation, adding effects that are globally applied to the game. It also has a major use for map makers, as this system has nearly all of the capabilities of the Internal system, but without the hassle of having to repeatedly compile a map and reload the game, allowing map makers to rapidly prototype their effects.

HLSL Shaders

Please see the full HLSL reference.

The Internal System

The internal post process system adds per-map effects through the use of four new tags:

  • shader_postprocess_generic - Stores your shader and provides an interface to your shaders variables.
  • effect_postprocess_generic - Brings your shaders together into a single effect.
  • effect_postprocess_collection - Defines which effects to include and how and where they are applied.
  • shader_postprocess_globals - Provides basic control over the built in subsystems, on a per-map basis.

shader_postprocess_generic

This tag stores your shaders compiled binary code and provides a way for you to set your shaders variables without having to recompile it.

Techniques

The techniques block is populated when the shader is compiled in os_tool. It's purpose is to list up to 3 techniques in the shader, which can be targeted at specific shader models. The block count and technique name cannot be modified manually, but the targeted shader models can be changed post-compile.

Field Type Usage
name tag string The name of the technique. This is automatically set when compiling the shader and cannot be edited manually. The technique name must not exceed 31 characters.
shader model word flags Defines which shader model(s) the technique is intended for. The highest supported shader model is always used.

Passes

The passes block within the technique block is also populated automatically when compiling a shader. The pass block defines how a pass and it's resources need to be applied.

Field Type Usage
name tag string The name of the pass. This is automatically set when compiling the shader and cannot be edited manually. The pass name must not exceed 31 characters.
flags word flags See below.
render chain enum Sets which render chain the pass needs to draw to.

Render chain values:

Value Result
main chain Causes the passes output to be drawn to the main render chain. This must occur on the last pass of an effect for it to be applied correctly.
buffer chain Causes the passes output to be drawn to the secondary render chain, for passing per pixel data between passes and shaders without changing the main chain.

Variables

The tag has a number of variable blocks that all have the same basic functionality, with some exceptions.

All blocks have the following fields:

Field Type Usage
value name tag string This corresponds to the variable name in your shader that you want to set.
value lower bound varies When animated this is the value used as the lowest possible value, not used by default.
value upper bound varies Used by default. When animated this is the value used as the highest possible value.
runtime value enum When set, the variable is overriden with a variable taken from the engine.
animation function enum Defines the function used to interpolate between the upper and lower value bounds. Defaults to "one", resulting in the upper bound being used by default.
animation flags word flags See below.
animation duration real Controls how long a single animation cycle takes.
animation rate real Controls how often the variable is updated.

Animation flags:

Flag Usage
invert Flips the animation functions value, essentially swapping the upper and lower bounds
multichannel noise Only applies to variables with 2 or more channels. When the "noise" animation function is used, a different noise value is applied to each channel.
ignore alpha Only applies to colour variables. Variable animation has no affect on the alpha channel, the upper bound alpha value is always used.

Exceptions

Bitmaps

Only uses the value name field.

Field Type Usage
bitmap index short When the referenced bitmap contains more than one texture, this is the index of the texture you wish to use.
bitmap tag reference The bitmap tag to use.

Bools

Does not use the upper and lower bounds fields.

Field Type Usage
value word flags enabled - Controls the initial value of the boolean variable.
flags word flags Has one flag, Invert, which inverts the runtime value when it is used.

Creating a shader_postprocess_generic tag

To create this tag you use the os_tool command 'compile-shader-postprocess' to compile a directory of HLSL .fx shaders which will be saved as shader_postprocess_generic tags in your tags directory. If a shader_postprocess_generic tag already exists for a shader, it's shader binary code is updated with the newly compiled code.

Child shaders

The internal post process system allows you to override the variables in a shader_postprocess_generic tag by referencing it in a child shader_postprocess_generic tag. This allows you to have a single shader tag which contains the shader code and initial variable values, and any number of child shader tags that override the initial variables to create a different variant of the shader. For instance, if you have a shader that tints the scene blue and the blue colour variable is controlled in the tag, you can use that shader as a base for another shader tag that overrides the colour variable to create a child shader that tints the scene green. This is done simply by referencing the original shader in the "base shader" field and adding a variable of the same type with the same value name as a variable in the base shader.

effect_postprocess_generic

This tag controls how your shaders are put together to create your final effect.

The effect_postprocess_generic tag starts with a quad definition, however the internal system does not currently use it. It is there in case a future application of the post processing system requires a quad definition but does not go through the effect_postprocess_collection tag.

Field Type Usage
quad tessellation point2d Sets how many segments the quad has on the x and y axes.
x screen bounds real_bounds Defines the start and end points of the quad on the x axis.
y screen bounds real_bounds Defines the start and end points of the quad on the y axis.

Shaders

All of the post process shaders you want to use in your effect must be added to this block.

Field Type Usage
shader tag reference Points to a single shader_postprocess_generic tag.

Shader Indices

Controls what shaders are used and the order in which they are applied. When you add an entry to the shader indices block you are adding an instance of that shader to the list. Meaning that you can add multiple instances of a shader to the list to create a complex effect from separate shaders. For instance if you wanted to create an effect that blurs the scene, but your blur shader does not create as large a blur as you want, you can simply add multiple instances of the blur shader to the shader indices block to multiply its effect.

Field Type Usage
shader block index The index of the shader to use for this instance.

Exposed Parameters

The purpose of exposed parameters is to define which variables in the shader instances (if any) are available to be overriden by a post processing subsystem. For the internal system the exposed parameters are connected to through the effect_postprocess_collection tag to be changed using Halo script. Exposed parameters only access a single parameter in a single shader instance. This means that if you used a shader multiple times in an effect the exposed parameter will only affect a single instance of the shader. For instance, suppose you have an effect with two instances of a blue tint shader. The effect will end up tinting the scene blue, twice. However, if you expose the colour parameter of the first shader instance and it is set to green by a post processing subsystem, the effect will end up first tinting the scene green, and then tinting it blue. So even though the two shader instances use the same shader you can control the parameters of each instance separately via the exposed parameters.

Field Type Usage
exposed name string The name the parameter will be referenced by outside of the effect.
parameter name string The name of the shader parameter to expose.
shader index block index The shader instance the exposed parameter belongs to.

effect_postprocess_collection

This tag is used to bring the effects together that you want to use in a map and set up where and when they are applied.

Effects

The effects you wish to use are added to this block. This block also sets up which of the effects exposed parameters (if it has any) you wish to modify with Halo script, and by what name you wish to reference them by.

Field Type Usage
effect tag_reference Points to an effect_postprocess_generic tag to include in the collection.
name tag_string A unique for the effect. This is used to reference the effect in Halo script.

Script Variables

The script variables block connects the exposed parameters in an effect to Halo script via a unique identifier.

Field Type Usage
script variable name tag_string A unique identifier for the script variable. This is used to reference the variable in Halo script.
exposed parameter name tag_string The name of the exposed parameter in the effect that this variable is connected to.

Effect Instances

An effect instance defines when and where an effect is applied. Each effect instance can be treated as a single entity, so multiple effect instances can reference the same effect and apply it at different points in the render cycle, as well as being active at different times with individual levels of fading.

Field Type Usage
name tag string A unique identifier used to reference the effect from Halo script
effect block index The index of the effect to use when rendering this instance.
render stage enum The point during Halo's render cycle to apply this effect instance.
quad tessellation point2d Defines how many segments the instances quad should consist of on the x and y axes.
x screen bounds real_bounds The start and end points of the instances quad on the x axis.
y screen bounds real_bounds The start and end points of the instances quad on the y axis.
activation operation enum When using multiple activation controls, this defines whether to boolean AND or OR the control values.

Render stages:

Value Usage
after bsp - before blur Applies the effect immediately after all opaque geometry has been drawn and prior to the built in motion blur system.
after blur - before alpha's faces Applies the effect immediately after the motion blur and before alpha tested geometry is drawn.
after alpha'd faces - before hud Applies the effect immediately after alpha tested geometry has been drawn, and before the HUD.
after hud - before menu Applies the effect after the HUD has been drawn and before Halo's menus are drawn.
after menu Applies the effect after the menus have been drawn.

Activation Operations:

Value Result
all The effect instance is only applied when all of the activation controls evaluate to true.
any The effect instance is applied when any of the activation controls evaluate to true.

Activation Controls

Activation controls allow you to tie whether an effect instance is on or not to one or more engine states, without using Halo script.

Field Type Usage
state enum The engine state the instance will be controlled by.
flags word flags A single flag, invert which controls whether the controls result should be inverted.

Activation states:

Value Usage
initially active Controls whether the effect instance is initially made active when the map is loaded. Instances are initially active anyway, so this is only of use when inverted.
is in cutscene This state will return true whenever the cinematic black bars are displayed in the game.
player is zoomed This state will return true whenever the local player is zoomed in with their current weapon.
player using a vehicle This state will return true whenever the local player is in any seat of any vehicle.

shader_postprocess_globals

This tag provide basic control over built in subsystems for your map. Currently the only system you can change is the bloom subsystem. To use this tag simply add it to your maps tag_collection tag.

Bloom Globals

Field Type Usage
flags word flags Control the blooms activation and render stage.
bloom size real Defines how far the bloom should extend, 1.0 to 5.0 is the recommended range. Any higher and the effect becomes fragmented. Default value is 3.5.
bloom exposure real Multiplies the bloom to increase or decrease its brightness. Default value is 1.0.
bloom mix amount real An amount between 0.0 and 1.0 that blends between no bloom and full bloom respectively. Default value is 0.5.
bloom minimum color real rgb color When filtering out the colour range for the bloom, colours below this are lost. Default value is { 0.55, 0.55, 0.55 }.
bloom maximum color real rgb color When filtering out the colour range for the bloom, colours above this are kept. Default value is { 1.0, 1.0, 1.0 }.

Flags:

Flag Usage
enabled Turns the bloom subsystem on or off. Default value is true.
apply after hud Defines whether the bloom effect should be applied after or before the HUD is drawn. Default value is true.

Halo Script

A number of new Halo script functions have been added by OpenSauce that allow you to interact with post processing effects through your maps scripting.

The full script function listing can be found in the [Doc_Halo1_NewScriptInterfaces script functions page]

The External System

Using the external system only requires you to have a HLSL shader file (.fx) and an effect set up in your OS_Settings.PostProcessing.xml file.

Directory tree

The location of your external subsystems settings file is under your (My) Documents folder, in your Halo CE game directory:

`(My) Documents\My Games\Halo CE`

In that directory you should have the following directory/file tree:

  • OpenSauce
    • OS_Settings.PostProcessing.xml - mirrors most of the functionality of the tags in the internal post processing system.

OS_Settings.PostProcessing.xml

This xml file mirrors most of the functionality of the tags in the internal post processing system, to define how your shaders are applied and where.

This is a basic example of setting up a single shader and a single effect:

<?xml version="1.0" encoding="utf-8"?>
<OpenSauce>
    <PostProcessing>
        <ShaderDirectory>D:\Program Files (x86)\Microsoft Games\Halo Custom Edition\data\postprocess\shaders</ShaderDirectory>
        <TextureDirectory>D:\Program Files (x86)\Microsoft Games\Halo Custom Edition\data\postprocess\bitmaps</TextureDirectory>
        <Shader>
            <ID>tint_shader</ID>
            <File>my_tint</File>
        </Shader>
        <Effect>
            <ID>tint_effect</ID>
            <ShaderID>tint_shader</ShaderID>
        </Effect>
        <EffectInstance>
            <Name>tint_effect_instance</Name>
            <Effect>tint_effect</Effect>
            <RenderStage>3</RenderStage>
            <ActivationOperation>0</ActivationOperation>
            <Quad>
                <Tessellation>
                    <X>4</X>
                    <Y>4</Y>
                </Tessellation>
                <BoundsX>
                    <Lower>0.0f</Lower>
                    <Upper>1.0f</Upper>
                </BoundsX>
                <BoundsY>
                    <Lower>0.0f</Lower>
                    <Upper>1.0f</Upper>
                </BoundsY>
            </Quad>
            <ActivationControl>
                <State>1</State>
                <Invert>True</Invert>
            </ActivationControl>
        </EffectInstance>
    </PostProcessing>
</OpenSauce>

Initial setup

Before you can start adding post process effects you have to set the directory attributes under the postprocessing element.

  • ShaderDirectory - Should contain a path to where your shaders are located. This directory is also used to resolve the relative file includes in your shaders.
  • TextureDirectory - Should contain a path to where your shaders textures are located.
        <ShaderDirectory>D:\Program Files (x86)\Microsoft Games\Halo Custom Edition\data\postprocess\shaders</ShaderDirectory>
        <TextureDirectory>D:\Program Files (x86)\Microsoft Games\Halo Custom Edition\data\postprocess\bitmaps</TextureDirectory>

Adding a shader

The shaders you want to use are added under <PostProcessing> by adding a child <Shader> node and setting the <ID> and <File> nodes. The <File> node should contain the the location and file name of your shader, minus the .fx extension. The shaders location will be relative to the <ShaderDirectory> node of the <PostProcessing> element. You must also set the <ID> node of your shader element as this is what is used in the effect definition to reference the shader.

        <Shader>
            <ID>tint_shader</ID>
            <File>my_tint</File>
        </Shader>

Shader nodes:

Child Node Type Usage
ID string This must be set as this is used to reference the shader in the effect node.
File string This must be set as this is the path to the shader file, relative to <ShaderDirectory>.

Adding an effect

To add an effect you add a child <Effect> node under <PostProcessing> and set its <ID> node.

        <Effect>
            <ID>tint_effect</ID>
        </Effect>

Shader instances are added to an <Effect> by adding a <ShaderID> under the <Effect> node and using the shaders <ID> value as it's inner text. This does not load the file directly, but references a shader from the under <PostProcessing>, so a shader must be added to that node before it can be used in an effect.

        <Effect>
            <ID>tint_effect</ID>
            <ShaderID>tint_shader</ShaderID>
        </Effect>

Effect nodes:

Child Node Type Usage
ID string This must be set as this is used to reference an effect in the effect instance node.
ShaderID string This is a reference to a shader under the <PostProcessing> node.

Effect instances

To add an effect instance you add a child <EffectInstance> node to <PostProcessing> and set its various child nodes.

        <EffectInstance>
            <Name>tint_effect_instance</Name>
            <Effect>tint_effect</Effect>
            <RenderStage>3</RenderStage>
            <ActivationOperation>0</ActivationOperation>
            <Quad>
                <Tessellation>
                    <X>4</X>
                    <Y>4</Y>
                </Tessellation>
                <BoundsX>
                    <Lower>0.0f</Lower>
                    <Upper>1.0f</Upper>
                </BoundsX>
                <BoundsY>
                    <Lower>0.0f</Lower>
                    <Upper>1.0f</Upper>
                </BoundsY>
            </Quad>
            <ActivationControl>
                <State>1</State>
                <Invert>True</Invert>
            </ActivationControl>
        </EffectInstance>

Effect instance nodes:

Attribute Type Usage
Name string Purely for your own reference, is not used in-game.
Effect string The ID of the effect to instantiate.
RenderStage int Controls when the effect instance should be applied, defaults to pre-HUD.
ActivationOperation string Purely for your own reference, is not used in-game.
Quad Controls the quad the shader will be rendered with.
ActivationControl Controls when the effect should be active.

Render stages:

Value Render Stage
0 Pre motion blur.
1 Pre alpha blended geometry.
2 Pre HUD.
3 Pre Menus.
4 Post menus.

Activation operation values:

Value Result
0 The activation controls are AND'd so all must be true for the effect instance to be displayed.
1 The activation controls are OR'd so if any of the values are true, the effect instance is displayed.

Quad child node:

The quad node defines the tessellation and bounds of the quad used to render the effect instance.

            <Quad>
                <Tessellation>
                    <X>4</X>
                    <Y>4</Y>
                </Tessellation>
                <BoundsX>
                    <Lower>0.0f</Lower>
                    <Upper>1.0f</Upper>
                </BoundsX>
                <BoundsY>
                    <Lower>0.0f</Lower>
                    <Upper>1.0f</Upper>
                </BoundsY>
            </Quad>
Child Node Usage
Tessellation Controls the number of segments the quad for this effect instance has.
BoundsX Controls the x axis dimension of the quad.
BoundsY Controls the y axis dimension of the quad.

Tessellation child nodes:

Attribute Type Usage
X int Defines how many segments the quad should have on the x axis.
Y int Defines how many segments the quad should have on the y axis.

BoundsX/Y child nodes:

Attribute Type Usage
Lower real Defines the start point of the quad on the respective axis.
Upper real Defines the end point of the quad on the respective axis.

Activation Controls

An effect instances activation controls are added to the <EffectInstance> node. To set the control you want to use, set the state node to the corresponding integer. If you wish the controls value to be inverted set the invert node to true.

            <ActivationControl>
                <State>1</State>
                <Invert>True</Invert>
            </ActivationControl>

Activation control child nodes:

Attribute Type Usage
State int Indicates the engine value to use when determining if the effect instance should be active.
Invert bool Inverts the result of the control.

Available activation states:

Value State Condition
0 initially active Controls whether the effect is displayed by default.
1 is in cutscene This value is true whenever the cinematic black bars are displayed.
2 player is zoomed This value is true whenever the player zooms with their current weapon.
3 player using a vehicle This value is true whenever the player is in any vehicle seat.

Prototyping

The external system can be used by map makers to rapidly prototype their shaders, without having to recompile their map. Doing so requires the game to be running in devmode, with the console available.

First you set up your shader using the external system, as normal. You then run the game and play your map, which should not yet have the shader added to it as a tag. If you decide to change your shader, you simply alt-tab out of the game, edit your shader, and return to the game. Then to reload the shader you open the console and run "pp_unload" and "pp_load" in that order. This will force the game to completely unload and completely reload all of the post processes being used, thus reloading the shader being worked on so you can view the affect of your changes.

Updated