Utilities » Shader conversion utility new in Git master

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

This utility is built if MAGNUM_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.

Example usage

Validate a SPIR-V file for a Vulkan 1.1 target, implicitly using AnyShaderConverter that delegates to SpirvToolsShaderConverter or any other plugin capable of SPIR-V validation depending on what's available:

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, this time delegated to GlslangShaderConverter or any other plugin capable of GLSL->SPIR-V conversion depending on what's available:

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

Full usage documentation

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

Arguments:

input — input file(s)
output — output file; ignored if --info is present, disallowed for --validate. If neither --info, --validate nor --link is present, corresponds to the ShaderTools::AbstractConverter::convertFileToFile() function.
-h, --help — display this help message and exit
--validate — validate input. Corresponds to the ShaderTools::AbstractConverter::validateFile() function.
--link — link multiple input files together. Corresponds to the ShaderTools::AbstractConverter::linkFilesToFile() function.
-C, --converter CONVERTER — shader converter plugin(s)
--plugin-dir DIR — override base plugin dir
-c, --converter-options key=val,key2=val2,… — configuration options to pass to the converter(s)
--info — print SPIR-V module info and exit
-q, --quiet — quiet output from converter plugin(s). Corresponds to the ShaderTools::ConverterFlag::Quiet flag.
-v, --verbose — verbose output from converter plugin(s). Corresponds to the ShaderTools::ConverterFlag::Verbose flag.
--warning-as-error — treat warnings as errors. Corresponds to the ShaderTools::ConverterFlag::WarningAsError flag.
-E, --preprocess-only — preprocess the input file and exit. Corresponds to the ShaderTools::ConverterFlag::PreprocessOnly flag.
-D, --define name=value — define a preprocessor macro. Corresponds to the ShaderTools::AbstractConverter::setDefinitions() function.
-U, --undefine name — undefine a preprocessor macro. Corresponds to the ShaderTools::AbstractConverter::setDefinitions() function.
-O, --optimize LEVEL — optimization level to use. Corresponds to the ShaderTools::AbstractConverter::setOptimizationLevel() function.
-g, --debug-info LEVEL — debug info level to use. Corresponds to the ShaderTools::AbstractConverter::setDebugInfoLevel() function.
--input-format glsl|spv|spvasm|hlsl|metal — input format for each converter
--output-format glsl|spv|spvasm|hlsl|metal — output format for each converter
--input-version VERSION — input format version for each converter
--output-version VERSION — output format version for each converter

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 /. Prefix the key with + to add new options or multiple options of the same name.

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.

« Scene conversion utility | Utilities