class new in 2020.06
AbstractSceneConverterBase 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::
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::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::
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::
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::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::
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::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::
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::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::
If SceneConverterFeature::
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.