This chapter is from the book
This chapter is from the book
This chapter is from the book
SPIR-V
SPIR-V is a Khronos-standard intermediate language that provides an alternative for distributing shaders. OpenGL accepts shaders in SPIR-V form much like it accepts shaders in GLSL form. Typically, for SPIR-V form, an offline tool chain will generate SPIR-V from a high-level shading language such as GLSL, and rather than distributing GLSL source with your application, you would distribute the generated SPIR-V.
SPIR-V is created, distributed, and consumed as binary units called modules. A SPIR-V module can live in memory as a sequence of 32-bit words, or it can be stored as a file, again, as a sequence of 32-bit words. However, as with GLSL, OpenGL does not deal with files, so SPIR-V must be handed to OpenGL as a pointer to an in-memory sequence of 32-bit words.
Each SPIR-V module contains one or more entry points, as places to begin shader execution, and each entry point knows what OpenGL pipeline stage it belongs to. Each of these entry points must form a single, complete OpenGL pipeline stage. That is, unlike in desktop GLSL, SPIR-V shaders don’t hold multiple compilation units to later link together to form a single stage. For SPIR-V, such linkage would be done offline by a front end when it translates the high-level language form to SPIR-V, yielding a result that is a fully linked stage. A single SPIR-V module may contain many entry points, even for the same stage.
SPIR-V modules can be specialized, which means changing the values of some specially identified constants inside the module before final compilation at run time. This is done to reduce the number (or size) of SPIR-V modules needed to represent multiple slight variations of a shader.
Reasons to Choose SPIR-V
There are several potential reasons you might distribute shaders in SPIR-V rather than GLSL. Some might apply to your situation, and some might not:
Better portability. One problem with portability is that each platform’s driver can have a slightly different interpretation of the high-level rules for GLSL. High-level languages are in part high-level because of the freedom of expressiveness they allow the coder. However, the limits of this freedom are sometimes hard to completely pin down, leading to variance in interpretation. SPIR-V is much stricter and much more regular about how constructs are expressed, leaving less room for interpretation. This in turn leads to less variance between platforms’ interpretation of SPIR-V and, hence, improved portability. Of course, you are not coding in SPIR-V, so you still have GLSL (for example) to contend with. However, for generating SPIR-V, you can select a single front end for all the platforms you target. That is, you can eliminate portability problems that originate from different GLSL interpretations by sticking with a single GLSL front end. Someone else might select a different front end for their shaders, and that’s fine too. What matters is that one application’s GLSL shaders get the same GLSL interpretation for all platforms on which the SPIR-V ends up running.
Other source languages. SPIR-V enables use of high-level languages other than GLSL. As long as the distributed SPIR-V is of correct form, it does not matter how it was generated.
Reduced distribution size. SPIR-V has multiple features to dramatically reduce the size of shader collections as they are distributed. Individual shaders, on their own, are typically larger in SPIR-V than in GLSL, but individual shaders are small in either case. Collections of related shaders can, however, be quite large, and two SPIR-V features in particular are aimed at addressing such collections: specialization and multiple entry points per module. Specialization allows late changing of some constant values, and multiple entry points in the same SPIR-V module allow shipping a single instance of a function body that might be used by many entry points. GLSL distribution might have distributed a copy of the function for each shader in the collection, whereas SPIR-V distribution is able to ship only one copy.
Protecting your source code. This is sometimes referred to as obfuscation, as there are times you don’t want to distribute your shader source code in an easy-to-leverage form. Shader source code can represent novel ideas or intellectual property, which you don’t want to distribute to other parties in a transparent, easily modifiable format. You can avoid distributing your source code by offline compilation of your source to SPIR-V and distribution of the SPIR-V instead. This makes it much harder to see how a shader achieves an effect. Yes, it is still conceivable that a reverse compiler can re-create GLSL or some other high-level shading language, which would compile down to the SPIR-V you distributed. However, the need for a recipient to undertake such a reverse-engineering activity provides real protection to your intellectual property.
Runtime compiler performance is often sought as another reason to select an intermediate language over a high-level language, but caution is needed here. A high-performing shader executable will typically require scheduling and register allocation algorithms, executed at runtime, that are themselves time-consuming. These later steps cannot be eliminated by using a portable intermediate language. Runtime compiler performance, however, is improved in a number of ways. For one, parsing a high-level language takes some time. Although parsing is normally a small portion of the compilation stack, it becomes more significant for shaders that have lots of unused code or when multiple shaders compile down to the same intermediate result. In these cases, notable parsing time is eliminated through use of SPIR-V. Also, some high-level optimizations can be performed offline, but take care not to perform platform-specific optimizations that would hurt performance on some targets. For example, it might be platform-dependent whether all functions should be inlined at all call sites.
Using SPIR-V with OpenGL
Using SPIR-V shaders in OpenGL is quite similar to using GLSL shaders. After you create your shader objects, in the same way we described earlier, there are two steps needed to associate a SPIR-V entry point with each of those shader objects. The first step is to associate a SPIR-V module with each shader object by calling glShaderBinary():
Because SPIR-V is normally specified and manipulated as a stream of 32-bit words, make sure you translate the size of your SPIR-V to bytes to use glShaderBinary(). This glShaderBinary() function can be used for other non-source forms of shaders, so this is a generic function, not specific to SPIR-V, unless SHADER_BINARY_FORMAT_SPIR_V_ARB is specified.
The second step needed to associate SPIR-V entry points with your shader objects is glSpecializeShader(), which, if successful, changes their compile status from the GL_FALSE set by glShaderBinary() to GL_TRUE:
We discuss using GLSL for specialization later in this section.
After this, you use glAttachShader() and glLinkProgram(), just as we did earlier when using GLSL with glShaderSource(), and everything else works the same way.
Using GLSL to Generate SPIR-V for OpenGL
There are no requirements on how you generate SPIR-V, only that the SPIR-V itself be well formed. While this is great for supporting a broad range of high-level languages and novel tools for creating SPIR-V, it is also convenient to have a standard high-level language for writing and exchanging shaders. To aid in this, Khronos has standardized a form of GLSL for creating SPIR-V.
There are two flavors of GLSL for making SPIR-V shaders: one that creates SPIR-V suitable for Vulkan (via the KHR_glsl_vulkan extension), and one that creates SPIR-V suitable for OpenGL (via the ARB_gl_spirv extension). Here, of course, we will discuss GLSL for generating SPIR-V for OpenGL. GLSL for this purpose is the same as standard GLSL, with a small number of additions, a small number of deletions, and a few minor changes. Generally, all inputs and outputs need a location specified, and I/O is similar to using the SSO model. Otherwise, it is identical to the GLSL already presented in this chapter.
Validating SPIR-V
OpenGL drivers won’t fully validate SPIR-V at runtime, as it is a performance advantage that valid SPIR-V is created offline. OpenGL only needs to behave properly when given fully valid SPIR-V. That is, invalid SPIR-V may lead to unexpected behavior. Khronos has made a SPIR-V validator, along with other tools, available at https://github.com/KhronosGroup/SPIRV-Tools to help you verify, offline, that the SPIR-V you want to distribute is valid SPIR-V. This tool should be integrated into your offline tool chain for generating SPIR-V to give maximum portability to your shaders.
Additions to GLSL for SPIR-V Generation
The key addition to GLSL for SPIR-V for OpenGL is specialization. Specialization constants can greatly reduce the number of variants of shaders you distribute. They allow late changing of a shader constant without having to manually generate a new shader.
Generally, knowing what values are constant at compile time helps optimizers generate faster executing code, as compared to accessing a variable that always has the same value. Loops can get known counts, and computations can simplify. Because of these positive impacts of using constants, GLSL shaders are often parametrized with preprocessor macros or some form of computer-generated code. Then multiple distinct shaders are created for different values of the parameter. With specialization constants, such a parameter is explicitly identified, given a default value, and allowed to be treated as a constant, even though its value can be changed before final runtime compilation. Thus, a single shader can be created and distributed with specialization constants, which later on take their correct final values. In GLSL, this looks like this:
layout (constant_id = 17) const int param = 8;
This declares that param is a specialization constant (because of the constant_id), with a default value of 8. The value 17 is how param will be later referred to if the application wants to change the default through the OpenGL API, as was done earlier with glSpecializeShader().
When compiled to SPIR-V, the SPIR-V shader tracks this param as a specialization constant. When it is time to create a rendering pipeline with the shader, the correct constant value is provided with the SPIR-V shader, and it is then optimized for that value. Thus, a frequent reason to ship multiple variants of the same shader is avoided.
Deletions from GLSL for SPIR-V Generation
There are a few traditional GLSL features that SPIR-V does not support. We list these here, with suggestions about what you can do instead.
Subroutines: The OpenGL GLSL subroutine feature is not available in SPIR-V. It is possible to express similar functionality using other constructs in GLSL, including switch statements and function calls. For example:
switch (material) {
case 1: result = material1(...); break;
case 2: result = material2(...); break;
case 3: result = material3(...); break;
}
Deprecated features: Deprecated features should always be avoided, but some are fully missing when generating SPIR-V. This includes the old deprecated texturing functions, such as texture2D(), which are no longer allowed because texture2D is now reserved as a type for making a sampler2D out of a separate sampler and 2D texture. Instead, simply use the modern version, texture, and its family of texture lookup built-in functions.
The compatibility profile: Generally, features belonging only to the compatibility profile are not supported by SPIR-V, and the GLSL compatibility profile is not allowed when generating SPIR-V from GLSL. You’ll need to express your shader using features from the core profile, including those added to GLSL for SPIR-V for OpenGL, which were discussed earlier.
gl_DepthRangeParameters: SPIR-V has no built-in variable for depth-range parameters. Any such information you want to share with your shaders, you can instead share by declaring your own uniform variables and setting them explicitly through the API.
Changes to GLSL for SPIR-V Generation
gl_FragColor broadcast: When GLSL is used directly, not through SPIR-V, writing to gl_FragColor can generate a broadcast write to all color-output attachments. However, SPIR-V does not support this feature. Ideally, you will declare the output variables you want to write and explicitly write them. If you do use gl_FragColor, writing to it will write only the one color output that is attached at location 0.
Glslang
The Khronos Group provides a reference front end for GLSL that is capable of generating SPIR-V from GLSL for either OpenGL or Vulkan. Note that you must specify which API you are generating SPIR-V for, as they have different features and hence different GLSL semantics. While it is the Khronos reference front end for validating correct GLSL, it is just one example of a SPIR-V compiler and should not be considered the only way of doing this.
Glslang is maintained as an open-source project on GitHub at https://github.com/KhronosGroup/glslang.
Note that glslang is a Khronos reference for valid semantic checking of valid GLSL for direct OpenGL, or ESSL for OpenGL ES, consumption. This high status is not yet bestowed on it for SPIR-V generation, which should be considered an example implementation, not a Khronos-sanctioned reference.
What’s Inside SPIR-V?
SPIR-V is a simple pure binary form, representing a high-level intermediate language. It stores this form as a simple linear sequence of 32-bit words.
When you get a result from an offline compiler or set into an API, it will be as such a stream of 32-bit words (but you do have to multiply by four to get the byte count expected by glShaderBinary()). It is self-contained; there is no wrapper around the sequence words; simply get or set the raw sequence of words from a file or API entry point. Within this sequence, the first few words provide sanity checks about the rest, including the very first word being the SPIR-V magic number, which you can verify is 0x07230203. If you have that, but with the bytes in reverse order, you are either not looking at it one 32-bit word at a time, or some step has reversed endianness.
SPIR-V loses very little information from a shader written in a high-level language. It can retain nested control and other high-level constructs, types native to GLSL, and decorations regarding built-in variable semantics, so that no target platform is missing the information it needs to do high-performance optimizations.
Further internal details about SPIR-V are outside the scope of this book, which aims to show you how to use GLSL to generate SPIR-V that you can then distribute with your application, but not how to make SPIR-V on your own.