Qt Shader Tools Build System Integration

The type of shader is deduced from the file extension. Thus, the extension must be one of the following:

• .vert - for vertex shaders

• .frag - for fragment (pixel) shaders

• .comp - for compute shaders

The following keywords are available:

• GLSL - Requests generating source code for the given list of GLSL versions. Watch out that the list follows the comma-separated qsb syntax. For example, a compute shader will want to specify "310 es,430" here as the defaults are not suitable for it.

• NOGLSL - This argument-less keyword disables generating GLSL source. Suitable for applications that do not wish to function with OpenGL at all.

• HLSL - Requests generating source code for the given list of HLSL (shader model) versions. The qsb tool follows GLSL-style version numbers and therefore 50 corresponds to Shader Model 5.0, 51 is 5.1.

• NOHLSL - This argument-less keyword disables generating HLSL source. Suitable for applications that do not wish to function with Direct 3D at all.

• MSL - Requests generating source code for the given version of the Metal Shading Language. 12 corresponds to 1.2, 20 to 2.0.

• NOMSL - This argument-less keyword disables generating MSL source. Suitable for applications that do not wish to function with Metal at all.

The most commonly overridden setting is GLSL. For example, if the application's shaders use OpenGL 3.x features, it will likely want to specify something higher than 100 es or 120:

qt_add_shaders(exampleapp "res_gl3shaders"
    GLSL "300es,330"
    PREFIX
        "/shaders"
    FILES
       shaders/ssao.vert
       shaders/ssao.frag
       shaders/skybox.vert
       shaders/skybox.frag
)

• BATCHABLE - Specifying this single, argument-less keyword is essential for vertex shaders that are used with Qt Quick, either in a ShaderEffect or in a QSGMaterialShader. It has no effect for fragment or compute shaders, and different types can safely be included in the same list since the keyword is taken into account only for the .vert files. Equivalent to the -b argument of qsb.

• PRECOMPILE - Equivalent to the -c or -t options of qsb, depending on the platform. When building on Windows, this leads to invoking fxc from the Windows SDK to do the first phase of compilation (HLSL source to DXBC bytecode) at build time instead of at run time. The resulting .qsb file will only include the compilation results (the intermediate shader format), not the original shader source code.

• OPTIMIZED - Invokes spirv-opt (which must be available from the Vulkan SDK or elsewhere) to perform optimizations on the SPIR-V bytecode. Equivalent to the -O argument of qsb.

• DEFINES - Defines macros that are active during shader compilation. Equivalent to the -D argument of qsb. The list has the form of "name1=value1;name2=value2". Alternatively, just like FILES, the list can be separated by newlines.

• OUTPUTS - When the name of the generated .qsb file needs to be different from the source, for example because one shader file serves as the source for multiple .qsb files due to differentiating via DEFINES, this list can contain an entry for each item in FILES, specifying a file name typically ending in .qsb. The specified name is then passed in the -o argument to qsb instead of just appending .qsb to the source file name.

• DEBUGINFO - Enables generating full debug information for SPIR-V, thus enabling tools like RenderDoc to display the full source when inspecting a pipeline or when performing vertex or fragment debugging. Equivalent to the -g argument of qsb. Also has an effect for Direct 3D in case the PRECOMPILE keyword has been specified, as fxc is then instructed to include debug information in the generated intermediate bytecode.

• QUIET - Suppresses debug and warning output from qsb. Only fatal errors are printed.

• OUTPUT_TARGETS - When using qt_add_shaders with static libraries, one or more special targets will be generated. Should you wish to perform additional processing on these targets pass a value to the OUTPUT_TARGETS parameter.