Shader Variants

Background of Shaders

One particular facet of modern graphics development that is often a pain - even for AAA games -- is shader variants!

If you have bought an AAA game in recent years and wondered what the heck it is doing when it says it is compiling shaders for a long time (up to an hour or more for some recent PC titles on slower machines!), then this blog will explain it a little.

Modern graphics APIs (Vulkan, D3D12, Metal) like to know about everything that has to do with GPU state, up front. A large chunk of the GPU state is provided by so-called shader programs. These shader programs fill in various gaps in the graphics pipeline that used to be provided by fixed-function hardware back in the days of OpenGL 1.x.

As OpenGL (and DirectX) evolved, people wanted to do a wider range of things when processing vertices into colorful pixels on-screen. So, over time, the fixed function silicon on GPUs has gradually been replaced by more and more general purpose processors. As with CPUs, we now need to tell these processors what to do by writing small (sometimes larger), specialized programs called shader programs.

In OpenGL, we would write our shaders in the high-level GLSL language and feed that to the OpenGL driver as a string at runtime. The OpenGL driver would then compile the GLSL to GPU machine code and we could then throw big piles of vertices and other resources like textures at it and marvel at the results -- or, more likely, swear a bit and wonder why we are staring at a black window yet again.

The necessity of including a complete compiler in the graphics driver was a huge burden for each of the GPU vendors, resulting in a great deal of overhead for them. It also led to some strange problems for developers when running code on a new platform with a different GLSL compiler in the driver and hitting new and different bugs or shortcomings.

With the advent of modern graphics APIs, there has been a move toward consuming shader code in the form of a bytecode intermediate representation, such as SPIR-V. SPIR-V is still not the final form of executable code required by the GPU silicon but it is much closer to it than GLSL and means the Vulkan drivers no longer need the entire compiler front-end.

Tooling, such as nSight and RenderDoc, are able to decompile the SPIR-V shader code back to GLSL (or HLSL) to make it easier for you to debug your applications.

The conversion from GLSL (or any other suitable language) to SPIR-V can still happen at runtime if that's what you need -- for example, in dynamic editor tools. However, for constrained applications, we can now compile the GLSL to SPIR-V up front at build time.

That's nice! We can simply add a few targets to our CMakeLists.txt and go home, right? Well, not quite.

The Need for Shader Variants

You see, shader developers are just as lazy as any other kinds of developers and like to reduce the amount of copy/paste coding that we have to do. So, we add optional features to our shaders that can be compiled in or out by way of pre-processor #defines, just as with C/C++.

Why is this even needed, though? Well, we don't always have full control over the data that our application will be fed. Imagine a generic glTF file viewer application. Some models that get loaded will use textures for the materials and include texture coordinates in the model's vertex data. Other models may just use vertex colors, completely leaving out texture coordinates.

To handle this, our vertex shader's prologue may look something like this:

Then, in the main() function, we would have:

The fragment shader would have similar changes to handle the cases with and without texture coordinates.

Super, so we have one set of shader source files that can handle both models with textures and models without textures. How do we compile the shaders to get these shader variants?

Just as with C/C++ we have a compiler toolchain and, similarly, we invoke the compiler with the various -D options as needed, e.g.:

Then, within our application, we can load the glTF model, inspect its data to see whether it uses textures, and then load the appropriate SPIR-V compiled shader.

Hooray! The job is done and we can go home now, right? Well, actually, no -- the project manager just called to say we also need to handle models that include the alpha cut-off feature and models that don't include it.

Alpha cut-off is a feature of glTF files by which any pixels determined to have an alpha value less than some specified threshold simply get discarded. This is often used to cut away the transparent parts of quads used to render leaves of plants.

Ok then -- let's simply repeat a process similar to that which we did for handling the presence, or absence, of texture coordinates.

The fragment shader implementation of alpha cut-off is trivial:

We can then add suitable CMake targets to compile with and without this option.

Of course, there's a catch. We have a combinatorial explosion of feature combinations. This only gets worse when we add the next optional feature or optional features that have various settings we wish to set at compile time, such as the number of taps used when sampling from a texture to perform a Gaussian blur.

Clearly, we do not want to have to add several thousand combinations of features as CMake targets by hand! So, what can we do?

Exploring the Problem

Let's consider the above combination of the texture coordinates and alpha cut-off features. Our table of features and compiler flags looks like this:

Adding another option would add another dimension to this table. The above mentioned option of blur filter taps with, say, 3, 5, 7, or 9 taps would add a 3rd dimension to the table and increase the number of options by another factor of 4, for a total of 16 possible configurations of this one shader program.

Adding just a handful of features, we can see that it would be all too easy to end up with thousands of combinations of compiled shaders from the single set of GLSL files!

How can we solve this in a nice and extensible way?

It is easy enough to have nested loops to iterate over the available options for each of the specified axes of variations. But what if we don't know all of the axes of variation up front? What if they vary from shader to shader? Not all shaders will care about alpha cut-off or blur filter taps, for example.

We can't simply hard-wire a set number of nested loops to iterate over the combinations in our CMake files. We need something a bit more flexible and smarter.

Let's think about the problem in a slightly different way.

To start with, let's represent a given configuration of our option space by a vector of length N, where N is the number of options. For now, let's set this to 3, for our options we have discussed:

1. Texture Coordinates (Off or On)
2. Alpha Cut-off (Off or On)
3. Blur filter taps (3, 5, 7, or 9)

That is, we will have a vector like this:

To save some typing, let's now replace the wordy description of each element with a number representing the index of the option for that axis of variation:

1. Texture Coordinates: (0 = Off, 1 = On)
2. Alpha Cut-off: (0 = Off, 1 = On)
3. Blur filter taps: (0 = 3 taps, 1 = 5 taps, 2 = 7 taps, 3 = 9 taps)

With this scheme in place, our above option set will be:

And the vector representing texture coordinates on, no alpha cut-off, and 7 blur filter taps option will be:

How does this help us? Well, it allows us to succinctly represent any combination of options; but it's even better than that. We can now easily go through the list of all possible combinations in a logical order. We begin by incrementing the final element of the vector over all possible values. Then we increment the previous element and repeat, like this:

Note that the total number of option combinations is just the product of the number of options in each dimension or axis of variation, e.g. 2x2x4 = 16 in this example.

The above sequence is exactly what we would get if we had 3 nested for-loops to iterate over the options at each level. How does this help us?

Well, looking at the above sequence of options vectors, you may well notice the similarity to plain old counting of numbers. For each "decimal place" (element in the vector), starting with the final or least significant digit, we go up through each of the available values. Then, we increment the next least significant digit and repeat.

The only difference to how we are used to counting in decimal (base 10), binary, octal, or hexadecimal is that the base of each digit is potentially different. The base for each digit is simply the number of options available for that axis of variation (e.g. the texture coordinates can only be on or off (base = 2)). It's the same for the alpha cut-off. The blur taps option has a base of 4 (4 possible options).

We know how many combinations we need in total and we know that each combination can be represented by a vector that acts like a variable-base number. Therefore, if we can find a way to convert from a decimal number to the corresponding combination vector, we are in a good situation, as we will have converted a recursive approach (nested for-loops) into a flat linear approach. All we would need would be something like this pseudo-code:

So how do we do this?

A Solution

To convert a decimal number into a different base system is fairly easy. The process is described well at https://www.tutorialspoint.com/computer_logical_organization/number_system_conversion.htm, where they give an example of converting from decimal to binary.

All we have to do, in our case, is use a base that differs for each digit of our combination vector. However, before we show this, we need a way to specify the options for each shader that we wish to consider. We have done this by way of a simple JSON file, for now. Here is an example showing our above case for these options as applied to the fragment shader, but only the texture coordinates and alpha cut-off for the vertex shader. This is just an example for illustration. In reality, the vertex shader has nothing to do with alpha cut-off and our simple shaders do not do anything with the blur tap option at all:

The default in our system, if no explicit options are provided in the JSON file, is defined (on) or not defined (off).

Each input shader file section then specifies which of the options it cares about. So, in this example, the fragment shader considers all 3 options and will have 16 variants compiled.

In order to generate the possible build combinations, we have written a small Ruby script to implement the necessary logic. Why Ruby? Because I couldn't face trying to do the necessary math in CMake's scripting language and Ruby is lovely!

The core of the script that implements the decimal to a variable-base number (combination vector) is pretty simple:

In the above code, the bases argument is a vector representing the base of each digit in the final combination vector. Here, bases = [2, 2, 4]. We then loop over the decimal number, performing the divmod operation at each step to find the value of each digit in our combination vector. When we have reduced the input decimal number to 0, we are done. This is exactly analogous to the decimal to binary conversion linked above but for variable base at each digit.

With the resulting combination vector in hand, it is simple for us to then look up the corresponding compiler -D option for that selection and output that into a JSON string. Here is an example of the output of running the ruby script against the above configuration file:

If you are interested, this is the full script:

Integrating into the Build System

CMake is now able to read and parse JSON documents -- a fact that I didn't know at first. This means that we can quite conveniently ask our build system to execute our Ruby script as an external process at configure time, capture the JSON output as shown above, iterate over the generated combinations, and add a build target for each one.

The cut-down code for doing this is:

Here, CompileShader() call is another helper function that just invokes the glslangValidator GLSL->SPIR-V compiler with the specified options.

This nicely takes care of generating all of the required shader variants that will be compiled with correct dependencies on the source GLSL files. To ensure that the targets get updated if the input JSON configuration file changes, we can add the following snippet to the above function:

Now, if we edit the JSON configuration file that contains the options, CMake will automatically re-run and generate the targets.

On the C++ runtime side of things, we have some logic to construct the appropriate shader file name for the compiled SPIR-V shader matching the options needed by whatever model we are rendering.

In the future, we may make this part more reusable by making it read in the same JSON configuration file used to create the shader variants.

Wrapping Up

So, going back to where we started: how does all of this tie into your PC's spending an hour compiling shaders when we have shown here how to compile them at application build time?

It all goes back to SPIR-V's just being a bytecode intermediate representation. Before the GPU can execute these shaders, it needs to do a final compilation step to convert the SPIR-V to actual machine code. In a modern graphics API, this is done when we create a so-called "graphics pipeline." At this point, we have to specify pretty much all GPU state, which then gets baked into a binary blob along with the shader code by the driver. This binary blob is both GPU-vendor and driver-version specific. So, it cannot be built at application build time but, rather, has to be done on the actual machine on which it will execute.

The first time you run such a game or other application, it will often loop through all of the shader variants and compile a graphics pipeline for each one. These then get cached to disk for use on subsequent runs. If you change your GPU or (more likely) the driver version, then this cache might get invalidated and you'd have to sit through this process once again.

For systems with known hardware and drivers, this whole process can be performed as part of the build step. This is why consoles such as the PlayStation 5 do not have to do this lengthy shader compiling step, while we wait there and watch.

There is some work going on in Khronos at present, in the shape of VK_ext_shader_object, to try to get back to a more dynamic-shader friendly way of doing things, in which the driver takes care of much of this compiling and caching for us. As with all things in computer science though, it will be a trade-off.

Thank you for reading about what turned out to be a nice little excursion of simplifying a problem by changing it from recursive to linear and learning about converting between numbers of different bases.

If you would like to learn more about modern 3D graphics or get some help on your own projects, then please get in touch.