Magnum::Trade::AbstractSceneConverter class new in 2020.06
#include <Magnum/Trade/AbstractSceneConverter.h>

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.

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

Saving a mesh to a file / data using convertToFile(const MeshData&, Containers::StringView) / convertToData(const MeshData&). This is mostly for exporting the mesh data to a common format like OBJ or PLY in order to be used with an external tool. Advertised with SceneConverterFeature::ConvertMeshToFile or SceneConverterFeature::ConvertMeshToData
Performing an operation on the mesh data itself using convert(const MeshData&), from which you get a MeshData again. This includes operations like mesh decimation or topology cleanup. Advertised with SceneConverterFeature::ConvertMesh.
Performing an operation on the mesh data in place using convertInPlace(MeshData&). This is for operations like vertex cache optimization that don't need to change the mesh topology, only modify or shuffle the data around. Advertised with SceneConverterFeature::ConvertMeshInPlace.

Usage

Scene converters are commonly implemented as plugins, which means the concrete converter implementation is loaded and instantiated through a PluginManager::Manager. Then, based on the intent and on what the particular converter supports, convertToFile(), convertToData(), convert() or convertInPlace() gets called.

As each converter has different requirements on the input data layout and vertex formats, you're expected to perform error handling on the application side — if a conversion 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.

Saving a mesh to a file

In the following example a mesh is saved to a PLY file using the AnySceneConverter plugin, together with all needed error handling. In this case we know that AnySceneConverter supports SceneConverterFeature::ConvertMeshToFile, however in a more general case it might be good to check against the reported features() first.

PluginManager::Manager<Trade::AbstractSceneConverter> manager;
Containers::Pointer<Trade::AbstractSceneConverter> converter =
    manager.loadAndInstantiate("AnySceneConverter");

Trade::MeshData mesh = …;
if(!converter || !converter->convertToFile(mesh, "mesh.ply"))
    Fatal{} << "Can't save mesh.ply with AnySceneConverter";

See Loading and using plugins for more information about general plugin usage, File format support to compare implementations of common file formats and the list of derived classes for all available scene converter plugins.

Converting mesh data

In the following snippet we use the MeshOptimizerSceneConverter to perform a set of optimizations on the mesh to make it render faster. While AnySceneConverter can detect the desired format while writing to a file, here it would have no way to know what we want and so we request the concrete plugin name directly.

PluginManager::Manager<Trade::AbstractSceneConverter> manager;
Containers::Pointer<Trade::AbstractSceneConverter> converter =
    manager.loadAndInstantiate("MeshOptimizerSceneConverter");

Containers::Optional<Trade::MeshData> optimized;
if(!converter || !(optimized = converter->convert(mesh)))
    Fatal{} << "Can't optimize the mesh with MeshOptimizerSceneConverter";

Commonly, when operating directly on the mesh data, each plugin exposes a set of configuration options to specify what actually gets done and how, and the default setup may not even do anything. See Editing plugin-specific configuration for details and a usage example.

Converting mesh data in-place

Certain operations such as buffer reordering can be performed by directly modifying the input data instead of having to allocate a copy of the whole mesh. For that, there's convertInPlace(), however compared to convert() it imposes additional requirements on the input. Depending on the converter, it might require that either the index or the vertex data are mutable, or that the mesh is interleaved and so on, so be sure to check the plugin docs before use.

An equivalent to the above operation, but performed in-place, would be the following:

if(!converter || !converter->convertInPlace(mesh))
    Fatal{} << "Can't optimize the mesh with MeshOptimizerSceneConverter";

Data dependency

The instances returned from various functions by design have no dependency on the converter instance and neither on the dynamic plugin module. In other words, you don't need to keep the converter 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.

Subclassing

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:

The doConvert(const MeshData&) function is called only if SceneConverterFeature::ConvertMesh is supported.
The doConvertInPlace(MeshData&) function is called only if SceneConverterFeature::ConvertMeshInPlace is supported.
The doConvertToData(const MeshData&) function is called only if SceneConverterFeature::ConvertMeshToData is supported.
The doConvertToFile(const MeshData&, Containers::StringView) function is called only if SceneConverterFeature::ConvertMeshToFile is supported.

Derived classes

class AnySceneConverter new in 2020.06: 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() -> Containers::StringView: Plugin interface.
static auto pluginSearchPaths() -> Containers::Array<Containers::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 Containers::StringView& 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.
void addFlags(SceneConverterFlags flags) new in Git master: Add converter flags.
void clearFlags(SceneConverterFlags flags) new in Git master: Clear 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::Optional<Containers::Array<char>>: Convert a mesh to a raw data.
auto convertToFile(const MeshData& mesh, Containers::StringView filename) -> bool new in Git master: Convert a mesh to a file.
auto convertToFile(const std::string& filename, const MeshData& mesh) -> bool deprecated in Git master: Convert a mesh to a file.

Protected functions

auto doConvertToFile(const MeshData& mesh, Containers::StringView filename) -> bool virtual: Implementation for convertToFile(const MeshData&, Containers::StringView)

Private functions

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

Function documentation

static Containers::StringView Magnum::Trade::AbstractSceneConverter::pluginInterface()

Plugin interface.

"cz.mosra.magnum.Trade.AbstractSceneConverter/0.1.2"_s

static Containers::Array<Containers::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. To avoid clearing potential future default flags by accident, prefer to use addFlags() and clearFlags() instead.

Corresponds to the -v / --verbose option in magnum-sceneconverter.

void Magnum::Trade::AbstractSceneConverter::addFlags(SceneConverterFlags flags) new in Git master

Add converter flags.

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

void Magnum::Trade::AbstractSceneConverter::clearFlags(SceneConverterFlags flags) new in Git master

Clear converter flags.

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

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. On failure prints a message to Error and returns Containers::NullOpt.

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. On failure prints a message to Error and returns false, mesh is guaranteed to stay unchanged.

Containers::Optional<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 prints a message to Error and returns Containers::NullOpt.

bool Magnum::Trade::AbstractSceneConverter::convertToFile(const MeshData& mesh, Containers::StringView filename) new in Git master

Convert a mesh to a file.

Available only if SceneConverterFeature::ConvertMeshToFile or SceneConverterFeature::ConvertMeshToData is supported. On failure prints a message to Error and returns false.

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

Convert a mesh to a file.

bool Magnum::Trade::AbstractSceneConverter::doConvertToFile(const MeshData& mesh, Containers::StringView filename) virtual protected

Implementation for convertToFile(const MeshData&, Containers::StringView)

If SceneConverterFeature::ConvertMeshToData is supported, default implementation calls doConvertToData(const MeshData&) and saves the result to given file. It is allowed to call this function from your doConvertToFile() implementation, for example when you only need to do format detection based on file extension.

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

Implementation for 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.