Magnum::Trade::AbstractSceneConverter class new in 2020.06

Base for scene converter plugins.

Provides functionality for converting meshes and other scene data between various formats or performing optimizations and other operations on them. See Loading and using plugins for more information and *SceneConverter classes in the Trade namespace for available scene converter plugins.

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 *Data instances valid. Moreover, all Corrade::Containers::Array instances returned through MeshData and others are only allowed to have default deleters — this is to avoid potential dangling function pointer calls when destructing such instances after the plugin module has been unloaded.


The plugin needs to implement the doFeatures() function and one or more of doConvert(), doConvertInPlace(), doConvertToData() or doConvertToFile() 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 AnySceneConverter
Any scene converter plugin.
class MeshOptimizerSceneConverter new in 2020.06
MeshOptimizer converter plugin.
class StanfordSceneConverter new in 2020.06
Stanford PLY converter plugin.

Public static functions

static auto pluginInterface() -> std::string
Plugin interface.
static auto pluginSearchPaths() -> std::vector<std::string>
Plugin search paths.

Constructors, destructors, conversion operators

AbstractSceneConverter() explicit
Default constructor.
AbstractSceneConverter(PluginManager::Manager<AbstractSceneConverter>& manager) explicit
Constructor with access to plugin manager.
AbstractSceneConverter(PluginManager::AbstractManager& manager, const std::string& plugin) explicit
Plugin manager constructor.

Public functions

auto features() const -> SceneConverterFeatures
Features supported by this converter.
auto flags() const -> SceneConverterFlags
Converter flags.
void setFlags(SceneConverterFlags flags)
Set converter flags.
auto convert(const MeshData& mesh) -> Containers::Optional<MeshData>
Convert a mesh.
auto convertInPlace(MeshData& mesh) -> bool
Convert a mesh in-place.
auto convertToData(const MeshData& mesh) -> Containers::Array<char>
Convert a mesh to a raw data.
auto convertToFile(const std::string& filename, const MeshData& mesh) -> bool
Convert a mesh to a file.

Private functions

auto doFeatures() const -> SceneConverterFeatures pure virtual
Implementation of features()
void doSetFlags(SceneConverterFlags flags) virtual
Implementation for setFlags()
auto doConvert(const MeshData& mesh) -> Containers::Optional<MeshData> virtual
Implementation of convert(const MeshData&)
auto doConvertInPlace(MeshData& mesh) -> bool virtual
Implementation of convertInPlace(MeshData&)
auto doConvertToData(const MeshData& mesh) -> Containers::Array<char> virtual
Implementation of convertToData(const MeshData&)
auto doConvertToFile(const std::string& filename, const MeshData& mesh) -> bool virtual
Implementation of convertToFile(const std::string&, const MeshData&)

Function documentation

static std::string Magnum::Trade::AbstractSceneConverter::pluginInterface()

Plugin interface.


static std::vector<std::string> Magnum::Trade::AbstractSceneConverter::pluginSearchPaths()

Plugin search paths.

Looks into magnum/sceneconverters/ or magnum-d/sceneconverters/ next to the dynamic Trade 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::Trade::AbstractSceneConverter::setFlags(SceneConverterFlags flags)

Set converter flags.

Some flags can be set only if the converter supports particular features, see documentation of each SceneConverterFlag for more information. By default no flags are set.

Containers::Optional<MeshData> Magnum::Trade::AbstractSceneConverter::convert(const MeshData& mesh)

Convert a mesh.

Depending on the plugin, can perform for example vertex format conversion, overdraw optimization or decimation / subdivision. Available only if SceneConverterFeature::ConvertMesh is supported.

bool Magnum::Trade::AbstractSceneConverter::convertInPlace(MeshData& mesh)

Convert a mesh in-place.

Depending on the plugin, can perform for example index buffer reordering for better vertex cache use or overdraw optimization. Available only if SceneConverterFeature::ConvertMeshInPlace is supported. Returns true if the operation succeeded. On failure the function prints an error message and returns false, mesh is guaranteed to stay unchanged.

Containers::Array<char> Magnum::Trade::AbstractSceneConverter::convertToData(const MeshData& mesh)

Convert a mesh to a raw data.

Depending on the plugin, can convert the mesh to a file format that can be saved to disk. Available only if SceneConverterFeature::ConvertMeshToData is supported. On failure the function prints an error message and returns nullptr.

bool Magnum::Trade::AbstractSceneConverter::convertToFile(const std::string& filename, const MeshData& mesh)

Convert a mesh to a file.

Available only if SceneConverterFeature::ConvertMeshToFile or SceneConverterFeature::ConvertMeshToData is supported. Returns true on success, prints an error message and returns false otherwise.

SceneConverterFeatures Magnum::Trade::AbstractSceneConverter::doFeatures() const pure virtual private

Implementation of features()

The implementation is expected to support at least one feature.

void Magnum::Trade::AbstractSceneConverter::doSetFlags(SceneConverterFlags 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.

bool Magnum::Trade::AbstractSceneConverter::doConvertToFile(const std::string& filename, const MeshData& mesh) virtual private

Implementation of convertToFile(const std::string&, const MeshData&)

If SceneConverterFeature::ConvertMeshToData is supported, default implementation calls doConvertToData(const MeshData&) and saves the result to given file.