Utilities » Shader conversion utility new in Git master

Converts, compiles, optimizes and links shaders of different formats.

This utility is built if both WITH_SHADERTOOLS and WITH_SHADERCONVERTER is enabled when building Magnum. To use this utility with CMake, you need to request the shaderconverter component of the Magnum package and use the Magnum::shaderconverter target for example in a custom command:

find_package(Magnum REQUIRED shaderconverter)

add_custom_command(OUTPUT ... COMMAND Magnum::shaderconverter ...)

See Downloading and building, Usage with CMake and the ShaderTools namespace for more information.


magnum-shaderconverter [-h|--help] [--validate] [--link]
    [-C|--converter NAME]... [--plugin-dir DIR]
    [-c|--converter-options key=val,key2=val2,…]... [--info] [-q|--quiet]
    [-v|--verbose] [--warning-as-error] [-E|--preprocess-only]
    [-D|--define name=value]... [-U|--undefine name]... [-O|--optimize LEVEL]
    [-g|--debug-info LEVEL] [--input-format glsl|spv|spvasm|hlsl|metal]...
    [--output-format glsl|spv|spvasm|hlsl|metal]...
    [--input-version VERSION]... [--output-version VERSION]...
    [--] input... output


If --validate is given, the utility will validate the input file using passed --converter (or AnyShaderConverter if none is specified), print the validation log on output and exit with a non-zero code if the validation fails. If --link is given, the utility will link all files together using passed --converter (or AnyShaderConverter if none is specified) and save it to output. If neither is specified, the utility will convert the input file using (one or more) passed --converter (or AnyShaderConverter if none is specified) and save it to output.

The -c / --converter-options argument accept a comma-separated list of key/value pairs to set in the converter plugin configuration. If the = character is omitted, it's equivalent to saying key=true; configuration subgroups are delimited with /. It's possible to specify the -C / --converter option (and correspondingly also -c / --converter-options, --input-format, --output-format, --input-version and --output-version) multiple times in order to chain more converters together. All converters in the chain have to support the ShaderTools::ConverterFeature::ConvertData feature, if there's just one converter it's enough for it to support ShaderTools::ConverterFeature::ConvertFile. If no -C / --converter is specified, AnyShaderConverter is used.

The -D / --define, -U / --undefine, -O / --optimize, -g / --debug-info, -E / --preprocess-only arguments apply only to the first converter. Split the conversion to multiple passes if you need to pass those to converters later in the chain.

Values accepted by -O / --optimize, -g / --debug-info, --input-format, --output-format, --input-version and --output-version are converter-specific, see documentation of a particular converter for more information.

Example usage

Validate a SPIR-V file for a Vulkan 1.1 target, using SpirvToolsShaderConverter picked by AnyShaderConverter:

magnum-shaderconverter --validate --output-version vulkan1.1 shader.spv

Converting a GLSL 4.10 file to a SPIR-V, supplying various preprocessor definitions, treating warnings as errors and targeting OpenGL instead of the (default) Vulkan, using GlslangShaderConverter picked again by AnyShaderConverter:

magnum-shaderconverter phong.frag -DDIFFUSE_TEXTURE -DNORMAL_TEXTURE --input-version "410 core" --output-version opengl4.5 --warning-as-error phong.frag.spv