Effect Merging

How It Works

The Effect framework defines a simple shader format for easy merging via the EffectPass. Effects are merged into a single compound shader by gathering and prefixing shader functions, varyings, uniforms, macros and blend functions. The shader is then used to process texels from an input buffer which usually contains the rendered scene colors. Texels pass through the effect function chain and intermediate results are blended with previous results. The final result is written to an output buffer or to screen.

Effect Execution Order

Effect merging can drastically improve performance by reducing the amount of fullscreen render operations, but it's sometimes necessary to split effects into separate passes to achieve optimal results. For instance, SMAA is usually applied first to avoid conflicts with other effects but some effects can introduce new aliasing artifacts at a later stage. If that's the case, it can be better to run these effects in a separate pass before SMAA.

The EffectPass sorts effects based on whether or not they read data from the input buffer or rely on depth. Other effects will be rendered in the order in which they were added. The recommended order for common effects is as follows:

Effect Order

• SMAA
• SSR (NYI)
• SSAO
• DoF
• Motion Blur (NYI)
• Chromatic Aberration
• Bloom
• God Rays
• Vignette
• Tone Mapping
• LUT / Color Grading
• Noise / Film Grain
• PixelationEffect

Effect Compatibility

The EffectPass prevents bad combinations of effects and informs the user about potential issues.

While it's technically possible to merge all kinds of effects, some combinations will produce undesired results like visual discontinuities and artifacts. Problematic effects either modify the screen coordinates inside the fragment shader or read additional data from the input buffer. To use such effects together, you'll need to use multiple EffectPass instances. The following table shows which combinations work well together and which don't:

+	UV Transform	Convolution	Other
UV Transform	✔️	❌	✔️
Convolution	❌	❌	✔️
Other	✔️	✔️	✔️

_{UV Transform = Modifies screen coordinates
Convolution = Reads data from input buffer}

UV Transform + Convolution

The following example shows the result of combining a PixelationEffect with an SMAAEffect:

SMAA	with Pixelation	Exaggerated Pixelation

The PixelationEffect transforms the screen coordinates that are passed to the SMAAEffect. The latter calculates its own coordinate offsets to blend texels with neighboring texels from the input buffer. These offsets won't be affected by the pixelation transformation which causes the antialiased lines to show up as artifacts in the final image. To better highlight the artifacts, the image on the right shows an extreme case where the PixelationEffect reduces the scene into a single grey pixel.

There is no feasible way to ensure that all custom texture coordinate calculations go through the same transformation. The best solution is to render these effects in separate passes.

Convolution + Convolution

Combining convolution effects leads to incorrect results because the contents of the input buffer remain unchanged while the EffectPass is running. A convolution effect reads additional data from the input buffer and applies it to the current texel. If two convolution effects are executed in the same shader, then the second one will work with outdated data. To better illustrate this problem, consider the following example:

Merging Convolution Operators

// A 1-dimensional texture with one color channel.
const inputBuffer = [60, 0, 255, 127];

// A simple convolution algorithm.
function blur(inputColor, i, inputBuffer) {

	// Offset and clamp to edge.
	const j = Math.max(i - 1, 0);
	const k = Math.min(i + 1, inputBuffer.length - 1);

	// Calculate the average.
	return (inputColor + inputBuffer[j] + inputBuffer[k]) / 3;

}

// Single pass (wrong way).
const outputColor = blur(inputBuffer[1], 1, inputBuffer); // => 105
console.log("incorrect:", blur(outputColor, 1, inputBuffer)); // => 140

// Two passes (right way).
const outputBuffer = [0, 0, 0, 0];
outputBuffer[0] = blur(inputBuffer[0], 0, inputBuffer); // => 40
outputBuffer[1] = blur(inputBuffer[1], 1, inputBuffer); // => 105
outputBuffer[2] = blur(inputBuffer[2], 2, inputBuffer); // => 127.33
outputBuffer[3] = blur(inputBuffer[3], 3, inputBuffer); // => 169.66

console.log("correct:", blur(outputBuffer[1], 1, outputBuffer)); // => 90.77