Magnum::ShaderTools::AbstractConverter class new in Git master
#include <Magnum/ShaderTools/AbstractConverter.h>

Base for shader converter plugins.

Provides functionality for validating and converting shader code between different representations or performing optimizations and other operations on them.

The interface supports three main kinds of operation, with implementations advertising support for a subset of them via features():

Usage

Shader converters are most commonly implemented as plugins, which means the concrete converter implementation is loaded and instantiated through a PluginManager::Manager. See Loading and using plugins for more information about general plugin usage, File format support to compare implementations for common file formats and the list of derived classes for all available shader converter plugins.

As each converter has different requirements on the source, its format and options set, you're expected to perform error handling on the application side — if a conversion or linking fails, you get an empty Containers::Optional or false and a reason printed to Error. Everything else (using a feature not implemented in the converter, ...) is treated as a programmer error and will produce the usual assertions.

Shader validation

As is common with other plugin interfaces, the AnyShaderConverter will detect a shader format based on file extension, load an appropriate validator plugin for given format and validate it:

PluginManager::Manager<ShaderTools::AbstractConverter> manager;
Containers::Pointer<ShaderTools::AbstractConverter> converter =
    manager.loadAndInstantiate("AnyShaderConverter");

Containers::Pair<bool, Containers::String> validMessage;
if(converter) validMessage =
    converter->validateFile(ShaderTools::Stage::Unspecified, "file.spv");
if(!converter || !validMessage.first())
    Error{} << "Validation failed:" << validMessage.second();
else if(!validMessage.second().isEmpty())
    Warning{} << "Validation succeeded with warnings:" << validMessage.second();
else
    Debug{} << "Validation passed";

In most cases, the validation result depends on the format version and target environment used. Formats and versions set by setInputFormat() / setOutputFormat() get propagated by AnyShaderConverter to the particular plugin, however the interpretation is plugin-specific, so be sure to read their docs.

Shader conversion and linking

The following example shows converting a GLSL shader to SPIR-V together with setting preprocessor defines and treating any warnings as errors. This time it's not using AnyShaderConverter but instead asking for a plugin using the GlslToSpirvShaderConverter alias (which maps for example to GlslangShaderConverter) — since we're operating directly on data, the plugin would have no chance to know the desired input / output format otherwise. Same goes for the shader stage, which has to be supplied explicitly:

Containers::Pointer<ShaderTools::AbstractConverter> converter =
    manager.loadAndInstantiate("GlslToSpirvShaderConverter");

/* Using CORRADE_LINE_STRING will make the compiler report line info that
   matches the source */
Containers::StringView glsl = "#line " CORRADE_LINE_STRING "\n" R"GLSL(
#version 450 core

layout(binding=0) uniform Material {
    vec4 color;
};

#ifdef TEXTURED
layout(binding=1) uniform sampler2D colorTexture;
layout(location=0) in vec2 textureCoordinates;
#endif

layout(location=0) out vec4 fragmentColor;

void main() {
    fragmentColor = color
        #ifdef TEXTURED
        *texture(colorTexture, textureCoordinates)
        #endif
        ;
}
)GLSL";

converter->setDefinitions({
    {"TEXTURED", ""}
});
Containers::Optional<Containers::Array<char>> spirv =
    converter->convertDataToData(ShaderTools::Stage::Fragment, glsl);

Loading shaders from memory, using file callbacks

Besides loading shaders directly from the filesystem using validateFile() / convertFileToFile() / linkFilesToFile() like shown above, it's possible to use validateData(), convertDataToData(), linkDataToData() and variants to load data from memory. Note that the particular converter implementation has to support ConverterFeature::ValidateData / ConverterFeature::ConvertData / ConverterFeature::LinkData for this method to work.

Textual shader sources sometimes #include other sources and in that case you may want to intercept those references and load them in a custom way as well. For converters that advertise support for this with ConverterFeature::InputFileCallback this is done by specifying an input file callback using setInputFileCallback(). The callback gets a filename, InputFileCallbackPolicy and an user pointer as parameters; returns a non-owning view on the loaded data or a Containers::NullOpt to indicate the file loading failed. For example, validating a shader from compiled-in resources could look like below. Note that the input file callback affects validateFile() / convertFileToFile() / convertFileToData() / linkFilesToFile() / linkFilesToData() as well — you don't have to load the top-level file manually and pass it to validateData() / convertDataToData() / linkDataToData(), any converter supporting the callback feature handles that correctly.

struct Data {
    std::unordered_map<std::string, Containers::Optional<
        Containers::Array<char>>> files;
} data;

converter->setInputFileCallback([](const std::string& filename,
    InputFileCallbackPolicy policy, Data& data)
        -> Containers::Optional<Containers::ArrayView<const char>>
    {
        auto found = data.files.find(filename);

        /* Discard the loaded file, if not needed anymore */
        if(policy == InputFileCallbackPolicy::Close) {
            if(found != data.files.end()) data.files.erase(found);
            return {};
        }

        /* Extract from an archive if not there yet. If the extraction fails,
           remember that to not attempt to extract the same file again next
           time. */
        if(found == data.files.end()) found = data.files.emplace(
            filename, extract("shaders.zip", filename)).first;

        if(!found->second) return {};
        return Containers::ArrayView<const char>{*found->second};
    }, data);

/* extracted from a ZIP */
auto result = converter->validateFile(ShaderTools::Stage::Fragment, "ssao.frag");

For converters that don't support ConverterFeature::InputFileCallback directly, the base validateFile() / convertFileToFile() / convertFileToData() / linkFilesToFile() / linkFilesToData() implementations will use the file callback to pass the loaded data through to validateData() / convertDataToData() / linkDataToData(), in case the converter supports at least ConverterFeature::ValidateData / ConverterFeature::ConvertData / ConverterFeature::LinkData. If the converter supports none of ConverterFeature::InputFileCallback, ConverterFeature::ValidateData, ConverterFeature::ConvertData or ConverterFeature::LinkData, setInputFileCallback() doesn't allow the callbacks to be set.

The input file callback signature is the same for ShaderTools::AbstractConverter, Trade::AbstractImporter and Text::AbstractFont to allow code reuse.

Data dependency

The instances returned from various functions by design have no dependency on the importer instance and neither on the dynamic plugin module. In other words, you don't need to keep the importer instance (or the plugin manager instance) around in order to have the returned data valid — all returned Corrade::Containers::String and Corrade::Containers::Array instances are only allowed to have default deleters and this is to avoid potential dangling function pointer calls when destructing such instances after the plugin module has been unloaded.

Subclassing

The plugin needs to implement the doFeatures() function and one or more of doValidateData(), doValidateFile(), doConvertDataToData(), doConvertFileToData(), doConvertFileToFile(), doLinkDataToData(), doLinkFilesToData() or doLinkFilesToFile() functions based on what features are supported.

You don't need to do most of the redundant sanity checks, these things are checked by the implementation:

Derived classes

class AnyConverter new in Git master
Any shader converter plugin.
class GlslangConverter new in Git master
Glslang shader converter plugin.
class SpirvToolsConverter new in Git master
SPIRV-Tools shader converter plugin.

Public static functions

static auto pluginInterface() -> Containers::StringView
Plugin interface.
static auto pluginSearchPaths() -> Containers::Array<Containers::String>
Plugin search paths.

Constructors, destructors, conversion operators

AbstractConverter() explicit
Default constructor.
AbstractConverter(PluginManager::Manager<AbstractConverter>& manager) explicit
Constructor with access to plugin manager.
AbstractConverter(PluginManager::AbstractManager& manager, const Containers::StringView& plugin) explicit
Plugin manager constructor.

Public functions

auto features() const -> ConverterFeatures
Features supported by this converter.
auto flags() const -> ConverterFlags
Converter flags.
void setFlags(ConverterFlags flags)
Set converter flags.
void addFlags(ConverterFlags flags) new in Git master
Add converter flags.
void clearFlags(ConverterFlags flags) new in Git master
Clear converter flags.
auto inputFileCallback() -> auto
Input file callback function.
auto inputFileCallbackUserData() const -> void*
Input file callback user data.
void setInputFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, void*) callback, void* userData = nullptr)
Set input file callback.
template<class T>
void setInputFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, T&) callback, T& userData)
Set file opening callback.
void setInputFormat(Format format, Containers::StringView version = {})
Set input format version.
void setOutputFormat(Format format, Containers::StringView version = {})
Set output format version.
void setDefinitions(Containers::ArrayView<const Containers::Pair<Containers::StringView, Containers::StringView>> definitions)
Set preprocessor definitions.
void setDefinitions(std::initializer_list<Containers::Pair<Containers::StringView, Containers::StringView>> definitions)
void setOptimizationLevel(Containers::StringView level)
Set optimization level.
void setDebugInfoLevel(Containers::StringView level)
Set debug info level.
auto validateData(Stage stage, Containers::ArrayView<const void> data) -> Containers::Pair<bool, Containers::String>
Validate a shader.
auto validateFile(Stage stage, Containers::StringView filename) -> Containers::Pair<bool, Containers::String>
Validate a shader.
auto convertDataToData(Stage stage, Containers::ArrayView<const void> data) -> Containers::Optional<Containers::Array<char>>
Convert shader data to a data.
auto convertDataToFile(Stage stage, Containers::ArrayView<const void> data, Containers::StringView filename) -> bool
Convert shader data to a file.
auto convertFileToFile(Stage stage, Containers::StringView from, Containers::StringView to) -> bool
Convert shader file to a file.
auto convertFileToData(Stage stage, Containers::StringView filename) -> Containers::Optional<Containers::Array<char>>
Convert shader data to a file.
auto linkDataToData(Containers::ArrayView<const Containers::Pair<Stage, Containers::ArrayView<const void>>> data) -> Containers::Optional<Containers::Array<char>>
Link shader data together to a data.
auto linkDataToData(std::initializer_list<Containers::Pair<Stage, Containers::ArrayView<const void>>> data) -> Containers::Optional<Containers::Array<char>>
auto linkDataToFile(Containers::ArrayView<const Containers::Pair<Stage, Containers::ArrayView<const void>>> data, Containers::StringView filename) -> bool
Link shader data together to a file.
auto linkDataToFile(std::initializer_list<Containers::Pair<Stage, Containers::ArrayView<const void>>> data, Containers::StringView filename) -> bool
auto linkFilesToFile(Containers::ArrayView<const Containers::Pair<Stage, Containers::StringView>> from, Containers::StringView to) -> bool
Link shader files together to a file.
auto linkFilesToFile(std::initializer_list<Containers::Pair<Stage, Containers::StringView>> from, Containers::StringView to) -> bool
auto linkFilesToData(Containers::ArrayView<const Containers::Pair<Stage, Containers::StringView>> filenames) -> Containers::Optional<Containers::Array<char>>
Link shader files together to a data.
auto linkFilesToData(std::initializer_list<Containers::Pair<Stage, Containers::StringView>> filenames) -> Containers::Optional<Containers::Array<char>>

Protected functions

auto doValidateFile(Stage stage, Containers::StringView filename) -> Containers::Pair<bool, Containers::String> virtual
Implementation for validateFile()
auto doConvertFileToFile(Stage stage, Containers::StringView from, Containers::StringView to) -> bool virtual
Implementation for convertFileToFile()
auto doConvertFileToData(Stage stage, Containers::StringView filename) -> Containers::Optional<Containers::Array<char>> virtual
Implementation for convertFileToData()
auto doLinkFilesToFile(Containers::ArrayView<const Containers::Pair<Stage, Containers::StringView>> from, Containers::StringView to) -> bool virtual
Implementation for linkFilesToFile()
auto doLinkFilesToData(Containers::ArrayView<const Containers::Pair<Stage, Containers::StringView>> filenames) -> Containers::Optional<Containers::Array<char>> virtual
Implementation for linkFilesToData()

Private functions

auto doFeatures() const -> ConverterFeatures pure virtual
Implementation for features()
void doSetFlags(ConverterFlags flags) virtual
Implementation for setFlags()
void doSetInputFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, void*) callback, void* userData) virtual
Implementation for setInputFileCallback()
void doSetInputFormat(Format format, Containers::StringView version) pure virtual
Implementation for setInputFormat()
void doSetOutputFormat(Format format, Containers::StringView version) pure virtual
Implementation for setOutputFormat()
void doSetDefinitions(Containers::ArrayView<const Containers::Pair<Containers::StringView, Containers::StringView>> definitions) virtual
Implementation for setDefinitions()
void doSetOptimizationLevel(Containers::StringView level) virtual
Implementation for setOptimizationLevel()
void doSetDebugInfoLevel(Containers::StringView level) virtual
Implementation for setDebugInfoLevel()
auto doValidateData(Stage stage, Containers::ArrayView<const char> data) -> Containers::Pair<bool, Containers::String> virtual
Implementation for validateData()
auto doConvertDataToData(Stage stage, Containers::ArrayView<const char> data) -> Containers::Optional<Containers::Array<char>> virtual
Implementation for convertDataToData()
auto doLinkDataToData(Containers::ArrayView<const Containers::Pair<Stage, Containers::ArrayView<const char>>> data) -> Containers::Optional<Containers::Array<char>> virtual
Implementation for linkDataToData()

Function documentation

static Containers::StringView Magnum::ShaderTools::AbstractConverter::pluginInterface()

Plugin interface.

"cz.mosra.magnum.ShaderTools.AbstractConverter/0.1.1"

static Containers::Array<Containers::String> Magnum::ShaderTools::AbstractConverter::pluginSearchPaths()

Plugin search paths.

Looks into magnum/shaderconverters/ or magnum-d/shaderconverters/ next to the dynamic ShaderTools library, next to the executable and elsewhere according to the rules documented in Corrade::PluginManager::implicitPluginSearchPaths(). The search directory can be also hardcoded using the MAGNUM_PLUGINS_DIR CMake variables, see Downloading and building for more information.

Not defined on platforms without dynamic plugin support.

void Magnum::ShaderTools::AbstractConverter::setFlags(ConverterFlags flags)

Set converter flags.

Some flags can be set only if the converter supports particular features, see documentation of each ConverterFlag for more information. By default no flags are set. To avoid clearing potential future default flags by accident, prefer to use addFlags() and clearFlags() instead.

Corresponds to the -q / --quiet, -v / --verbose, --warning-as-error and -E / --preprocess-only options in magnum-shaderconverter.

void Magnum::ShaderTools::AbstractConverter::addFlags(ConverterFlags flags) new in Git master

Add converter flags.

Calls setFlags() with the existing flags ORed with flags. Useful for preserving the defaults.

void Magnum::ShaderTools::AbstractConverter::clearFlags(ConverterFlags flags) new in Git master

Clear converter flags.

Calls setFlags() with the existing flags ANDed with inverse of flags. Useful for removing default flags.

auto Magnum::ShaderTools::AbstractConverter::inputFileCallback()

Input file callback function.

void* Magnum::ShaderTools::AbstractConverter::inputFileCallbackUserData() const

Input file callback user data.

void Magnum::ShaderTools::AbstractConverter::setInputFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, void*) callback, void* userData = nullptr)

Set input file callback.

In case the converter supports ConverterFeature::InputFileCallback, files opened through validateFile(), convertFileToData(), convertFileToFile(), linkFilesToData() and linkFilesToFile() will be loaded through the provided callback. Besides that, all external files referenced by the top-level file will be loaded through the callback function as well, usually on demand. The callback function gets a filename, InputFileCallbackPolicy and the userData pointer as input and returns a non-owning view on the loaded data as output or a Corrade::Containers::NullOpt if loading failed — because empty files might also be valid in some circumstances, nullptr can't be used to indicate a failure.

In case the converter doesn't support ConverterFeature::InputFileCallback but supports at least ConverterFeature::ValidateData / ConverterFeature::ConvertData / ConverterFeature::LinkData, a file opened through validateFile(), convertFileToData(), convertFileToFile(), linkFilesToData() or linkFilesToFile() will be internally loaded through the provided callback and then passed to validateData(), convertDataToData() or linkDataToData(). First the file is loaded with InputFileCallbackPolicy::LoadTemporary passed to the callback, then the returned memory view is passed to validateData() / convertDataToData() / linkDataToData() (sidestepping the potential validateFile() / convertFileToFile() / convertFileToData() / linkFilesToFile() / linkFilesToData() implementation of that particular converter) and after that the callback is called again with InputFileCallbackPolicy::Close. In case you need a different behavior, use validateData() / convertDataToData() / linkDataToData() directly.

In case callback is nullptr, the current callback (if any) is reset. This function expects that the converter supports either ConverterFeature::InputFileCallback or at least one of ConverterFeature::ValidateData, ConverterFeature::ConvertData, ConverterFeature::LinkData. If a converter supports neither, callbacks can't be used.

Following is an example of setting up an input file callback for fetching compiled-in resources from Corrade::Utility::Resource. See the overload below for a more convenient type-safe way to pass the user data pointer.

converter->setInputFileCallback([](const std::string& filename,
    InputFileCallbackPolicy, void*) {
        Utility::Resource rs("data");
        return Containers::optional(rs.getRaw(filename));
    });

template<class T>
void Magnum::ShaderTools::AbstractConverter::setInputFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, T&) callback, T& userData)

Set file opening callback.

Equivalent to calling the above with a lambda wrapper that casts void* back to T* and dereferences it in order to pass it to callback. Example usage — this reuses an existing Corrade::Utility::Resource instance to avoid a potentially slow resource group lookup every time:

const Utility::Resource rs{"data"};
converter->setInputFileCallback([](const std::string& filename,
    InputFileCallbackPolicy, const Utility::Resource& rs) {
        return Containers::optional(rs.getRaw(filename));
    }, rs);

void Magnum::ShaderTools::AbstractConverter::setInputFormat(Format format, Containers::StringView version = {})

Set input format version.

Format::Unspecified and an empty version is always accepted, other values are interpreted in a plugin-specific way. If a format/version combination is not supported or recognized, the following validateData(), validateFile(), convertDataToData(), convertDataToFile(), convertFileToFile(), convertFileToData(), linkDataToData(), linkDataToFile(), linkFilesToFile() or linkFilesToData() call will fail.

The format parameter corresponds to the --input-format option in magnum-shaderconverter, version to --input-version.

void Magnum::ShaderTools::AbstractConverter::setOutputFormat(Format format, Containers::StringView version = {})

Set output format version.

Format::Unspecified and an empty version is always accepted, other values are interpreted in a plugin-specific way. If a format/version combination is not supported or recognized, the following validateData(), validateFile(), convertDataToData(), convertDataToFile(), convertFileToFile(), convertFileToData(), linkDataToData(), linkDataToFile(), linkFilesToFile() or linkFilesToData() call will fail.

The format parameter corresponds to the --output-format option in magnum-shaderconverter, version to --output-version.

void Magnum::ShaderTools::AbstractConverter::setDefinitions(Containers::ArrayView<const Containers::Pair<Containers::StringView, Containers::StringView>> definitions)

Set preprocessor definitions.

Available only if ConverterFeature::Preprocess is supported. First string is macro name, second its value. If the second string is empty (but not nullptr), it's the same as #define without a value; if the second string is nullptr, it's the same as #undef.

Calling this function replaces the previous set, calling it with an empty list will reset the definitions back to initial state.

Corresponds to the -D / --define and -U / --undefine options in magnum-shaderconverter.

void Magnum::ShaderTools::AbstractConverter::setDefinitions(std::initializer_list<Containers::Pair<Containers::StringView, Containers::StringView>> definitions)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void Magnum::ShaderTools::AbstractConverter::setOptimizationLevel(Containers::StringView level)

Set optimization level.

Available only if ConverterFeature::Optimize is supported. Interpreted in a plugin-specific way, if it's not recognized the following convertDataToData(), convertDataToFile(), convertFileToFile(), convertFileToData(), linkDataToData(), linkDataToFile(), linkFilesToFile() or linkFilesToData() call will fail.

Has no effect for validateData() or validateFile().

Corresponds to the -O / --optimize option in magnum-shaderconverter.

void Magnum::ShaderTools::AbstractConverter::setDebugInfoLevel(Containers::StringView level)

Set debug info level.

Available only if ConverterFeature::DebugInfo is supported. Interpreted in a plugin-specific way, if it's not recognized the following convertDataToData(), convertDataToFile(), convertFileToFile(), convertFileToData(), linkDataToData(), linkDataToFile(), linkFilesToFile() or linkFilesToData() call will fail.

Has no effect for validateData() or validateFile().

Corresponds to the -g / --debug-info option in magnum-shaderconverter.

Containers::Pair<bool, Containers::String> Magnum::ShaderTools::AbstractConverter::validateData(Stage stage, Containers::ArrayView<const void> data)

Validate a shader.

Available only if ConverterFeature::ValidateData is supported. Returns

  • true and an empty string if validation passes without warnings,
  • true and a non-empty string if validation passes with warnings, and
  • false if validation doesn't pass. If an external error occurs (for example a referenced file not being found), it may also happen that the returned string is empty and a message is printed to Error instead.

Containers::Pair<bool, Containers::String> Magnum::ShaderTools::AbstractConverter::validateFile(Stage stage, Containers::StringView filename)

Validate a shader.

Available only if ConverterFeature::ValidateFile or ConverterFeature::ValidateData is supported. Returns

  • true and an empty string if validation passes without warnings,
  • true and a non-empty string if validation passes with warnings, and
  • false if validation doesn't pass. If an external error occurs (for example when a file cannot be read), it may also happen that the returned string is empty and a message is printed to Error instead.

Corresponds to the --validate option in magnum-shaderconverter.

Containers::Optional<Containers::Array<char>> Magnum::ShaderTools::AbstractConverter::convertDataToData(Stage stage, Containers::ArrayView<const void> data)

Convert shader data to a data.

Available only if ConverterFeature::ConvertData is supported. On failure prints a message to Error and returns nullptr.

bool Magnum::ShaderTools::AbstractConverter::convertDataToFile(Stage stage, Containers::ArrayView<const void> data, Containers::StringView filename)

Convert shader data to a file.

Available only if ConverterFeature::ConvertData is supported. On failure prints a message to Error and returns false.

bool Magnum::ShaderTools::AbstractConverter::convertFileToFile(Stage stage, Containers::StringView from, Containers::StringView to)

Convert shader file to a file.

Available only if ConverterFeature::ConvertFile or ConverterFeature::ConvertData is supported. On failure prints a message to Error and returns false.

Corresponds to the default behavior of magnum-shaderconverter when neither --validate nor --link is specified.

Containers::Optional<Containers::Array<char>> Magnum::ShaderTools::AbstractConverter::convertFileToData(Stage stage, Containers::StringView filename)

Convert shader data to a file.

Available only if ConverterFeature::ConvertData is supported. On failure prints a message to Error and returns Containers::NullOpt.

Containers::Optional<Containers::Array<char>> Magnum::ShaderTools::AbstractConverter::linkDataToData(Containers::ArrayView<const Containers::Pair<Stage, Containers::ArrayView<const void>>> data)

Link shader data together to a data.

Available only if ConverterFeature::LinkData is supported. On failure prints a message to Error and returns Containers::NullOpt. Can't be called if ConverterFlag::PreprocessOnly is set — in that case convertDataToData() has to be used instead.

Containers::Optional<Containers::Array<char>> Magnum::ShaderTools::AbstractConverter::linkDataToData(std::initializer_list<Containers::Pair<Stage, Containers::ArrayView<const void>>> data)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool Magnum::ShaderTools::AbstractConverter::linkDataToFile(Containers::ArrayView<const Containers::Pair<Stage, Containers::ArrayView<const void>>> data, Containers::StringView filename)

Link shader data together to a file.

Available only if ConverterFeature::LinkData is supported. On failure prints a message to Error and returns false. Can't be called if ConverterFlag::PreprocessOnly is set — in that case convertDataToFile() has to be used instead.

bool Magnum::ShaderTools::AbstractConverter::linkDataToFile(std::initializer_list<Containers::Pair<Stage, Containers::ArrayView<const void>>> data, Containers::StringView filename)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

bool Magnum::ShaderTools::AbstractConverter::linkFilesToFile(Containers::ArrayView<const Containers::Pair<Stage, Containers::StringView>> from, Containers::StringView to)

Link shader files together to a file.

Available only if ConverterFeature::LinkFile or ConverterFeature::LinkData is supported. On failure prints a message to Error and returns false. Can't be called if ConverterFlag::PreprocessOnly is set — in that case convertFileToFile() has to be used instead.

Corresponds to the --link option in magnum-shaderconverter.

bool Magnum::ShaderTools::AbstractConverter::linkFilesToFile(std::initializer_list<Containers::Pair<Stage, Containers::StringView>> from, Containers::StringView to)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Containers::Optional<Containers::Array<char>> Magnum::ShaderTools::AbstractConverter::linkFilesToData(Containers::ArrayView<const Containers::Pair<Stage, Containers::StringView>> filenames)

Link shader files together to a data.

Available only if ConverterFeature::LinkData is supported. On failure prints a message to Error and returns Containers::NullOpt. Can't be called if ConverterFlag::PreprocessOnly is set — in that case convertFileToData() has to be used instead.

Containers::Optional<Containers::Array<char>> Magnum::ShaderTools::AbstractConverter::linkFilesToData(std::initializer_list<Containers::Pair<Stage, Containers::StringView>> filenames)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Containers::Pair<bool, Containers::String> Magnum::ShaderTools::AbstractConverter::doValidateFile(Stage stage, Containers::StringView filename) virtual protected

Implementation for validateFile()

If ConverterFeature::ValidateData is supported, default implementation opens the file and calls doValidateData() with its contents. It is allowed to call this function from your doValidateFile() implementation — in particular, this implementation will also correctly handle callbacks set through setInputFileCallback().

This function is not called when file callbacks are set through setInputFileCallback() and ConverterFeature::InputFileCallback is not supported — instead, file is loaded though the callback and data passed through to doValidateData().

bool Magnum::ShaderTools::AbstractConverter::doConvertFileToFile(Stage stage, Containers::StringView from, Containers::StringView to) virtual protected

Implementation for convertFileToFile()

If ConverterFeature::ConvertData is supported, default implementation opens the file and calls doConvertDataToData() with its contents, then saving the output to a file. It is allowed to call this function from your doConvertFileToFile() implementation — in particular, this implementation will also correctly handle callbacks set through setInputFileCallback().

This function is not called when file callbacks are set through setInputFileCallback() and ConverterFeature::InputFileCallback is not supported — instead, file is loaded though the callback and data passed through to doConvertDataToData().

Containers::Optional<Containers::Array<char>> Magnum::ShaderTools::AbstractConverter::doConvertFileToData(Stage stage, Containers::StringView filename) virtual protected

Implementation for convertFileToData()

Default implementation opens the file and calls doConvertDataToData() with its contents — you only need to implement this if you need to do extra work with file inputs. It is allowed to call this function from your doConvertFileToData() implementation — in particular, this implementation will also correctly handle callbacks set through setInputFileCallback().

This function is not called when file callbacks are set through setInputFileCallback() and ConverterFeature::InputFileCallback is not supported — instead, file is loaded though the callback and data passed through to doConvertDataToData().

bool Magnum::ShaderTools::AbstractConverter::doLinkFilesToFile(Containers::ArrayView<const Containers::Pair<Stage, Containers::StringView>> from, Containers::StringView to) virtual protected

Implementation for linkFilesToFile()

If ConverterFeature::LinkData is supported, default implementation opens all files and calls linkDataToData() with their contents It is allowed to call this function from your doLinkFilesToFile() implementation — in particular, this implementation will also correctly handle callbacks set through setInputFileCallback().

This function is not called when file callbacks are set through setInputFileCallback() and ConverterFeature::InputFileCallback is not supported — instead, file is loaded though the callback and data passed through to doLinkDataToData().

Containers::Optional<Containers::Array<char>> Magnum::ShaderTools::AbstractConverter::doLinkFilesToData(Containers::ArrayView<const Containers::Pair<Stage, Containers::StringView>> filenames) virtual protected

Implementation for linkFilesToData()

Default implementation opens all files and calls doLinkDataToData() with their contents — you only need to implement this if you need to do extra work with file inputs. It is allowed to call this function from your doLinkFilesToData() implementation — in particular, this implementation will also correctly handle callbacks set through setInputFileCallback().

This function is not called when file callbacks are set through setInputFileCallback() and ConverterFeature::InputFileCallback is not supported — instead, file is loaded though the callback and data passed through to doConvertDataToData().

ConverterFeatures Magnum::ShaderTools::AbstractConverter::doFeatures() const pure virtual private

Implementation for features()

Has to be implemented always, the implementation is expected to support at least one feature.

void Magnum::ShaderTools::AbstractConverter::doSetFlags(ConverterFlags flags) virtual private

Implementation for setFlags()

Useful when the converter needs to modify some internal state on flag setup. Default implementation does nothing and this function doesn't need to be implemented — the flags are available through flags().

To reduce the amount of error checking on user side, this function isn't expected to fail — if a flag combination is invalid / unsuported, error reporting should be delayed to various conversion functions, where the user is expected to do error handling anyway.

void Magnum::ShaderTools::AbstractConverter::doSetInputFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, void*) callback, void* userData) virtual private

Implementation for setInputFileCallback()

Useful when the converter needs to modify some internal state on callback setup. Default implementation does nothing and this function doesn't need to be implemented — the callback function and user data pointer are available through inputFileCallback() and inputFileCallbackUserData().

void Magnum::ShaderTools::AbstractConverter::doSetInputFormat(Format format, Containers::StringView version) pure virtual private

Implementation for setInputFormat()

Has to be implemented always. To simplify error handling on user side, this function isn't expected to fail — if the format/version combination isn't recognized, the following validateData(), validateFile(), convertDataToData(), convertDataToFile(), convertFileToFile(), convertFileToData(), linkDataToData(), linkDataToFile(), linkFilesToFile() or linkFilesToData() should fail instead.

void Magnum::ShaderTools::AbstractConverter::doSetOutputFormat(Format format, Containers::StringView version) pure virtual private

Implementation for setOutputFormat()

Has to be implemented always. To simplify error handling on user side, this function isn't expected to fail — if the format/version combination isn't recognized, the following validateData(), validateFile(), convertDataToData(), convertDataToFile(), convertFileToFile(), convertFileToData(), linkDataToData(), linkDataToFile(), linkFilesToFile() or linkFilesToData() should fail instead.

void Magnum::ShaderTools::AbstractConverter::doSetDefinitions(Containers::ArrayView<const Containers::Pair<Containers::StringView, Containers::StringView>> definitions) virtual private

Implementation for setDefinitions()

Has to be implemented if ConverterFeature::Preprocess is supported. This function isn't expected to fail.

void Magnum::ShaderTools::AbstractConverter::doSetOptimizationLevel(Containers::StringView level) virtual private

Implementation for setOptimizationLevel()

Has to be implemented if ConverterFeature::Optimize is supported. To simplify error handling on user side, this function isn't expected to fail — if the level isn't recognized, the following convertDataToData(), convertDataToFile(), convertFileToFile(), convertFileToData(), linkDataToData(), linkDataToFile(), linkFilesToFile() or linkFilesToData() should fail instead.

void Magnum::ShaderTools::AbstractConverter::doSetDebugInfoLevel(Containers::StringView level) virtual private

Implementation for setDebugInfoLevel()

Has to be implemented if ConverterFeature::DebugInfo is supported. To simplify error handling on user side, this function isn't expected to fail — if the level isn't recognized, the following convertDataToData(), convertDataToFile(), convertFileToFile(), convertFileToData(), linkDataToData(), linkDataToFile(), linkFilesToFile() or linkFilesToData() should fail instead.

Containers::Pair<bool, Containers::String> Magnum::ShaderTools::AbstractConverter::doValidateData(Stage stage, Containers::ArrayView<const char> data) virtual private

Implementation for validateData()

Has to be implemented if ConverterFeature::ValidateData is supported. While validateData() uses a void view in order to accept any type, this function gets it cast to char for more convenience.

Containers::Optional<Containers::Array<char>> Magnum::ShaderTools::AbstractConverter::doConvertDataToData(Stage stage, Containers::ArrayView<const char> data) virtual private

Implementation for convertDataToData()

Has to be implemented if ConverterFeature::ConvertData is supported. While convertDataToData() uses a void view in order to accept any type, this function gets it cast to char for more convenience.

Containers::Optional<Containers::Array<char>> Magnum::ShaderTools::AbstractConverter::doLinkDataToData(Containers::ArrayView<const Containers::Pair<Stage, Containers::ArrayView<const char>>> data) virtual private

Implementation for linkDataToData()

Has to be implemented if ConverterFeature::LinkData is supported. While linkDataToData() uses a void view in order to accept any type, this function gets it cast to char for more convenience.