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 provides a direct and a batch interface, with implementations advertising support for a subset of them via features(). The direct interface has three main kinds of operation:

The batch interface allows converting a whole scene consisting of multiple meshes, materials, images, ... instead of a single mesh. Similarly, it has two main kinds of operation:

The actual data is then supplied to the converter in between the begin and end calls using various add() overloads and related APIs. Support for particular data types is then advertised with SceneConverterFeature::AddScenes, AddMeshes, AddCameras, AddImages2D etc.

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, either a single-mesh conversion with convert() and related functions is performed, or a whole-scene conversion with begin(), various add() APIs and end() is done.

As each converter has different requirements on the input data, their layout and 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.

Converting a single 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 a single 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 a single 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";

Converting multiple data

While the operations shown above are convenient enough for simple cases involving just a single mesh, general conversion of a whole scene needs much more than that. Such conversion is done in a batch way — first initializing the conversion of desired kind using begin(), beginData() or beginFile(), adding particular data using add(), and finalizing the conversion together with getting the output back using end(), endData() or endFile().

A common scenario is that you have an AbstractImporter instance containing an imported file, and you want to convert it to another format. While it's possible to go through all imported meshes, images, textures materials, etc. and add them one by one, there's a convenience addImporterContents() that passes everything through, and addSupportedImporterContents() that passes through only data actually supported by the converter, printing a warning for the rest. In the following example, a COLLADA file is converted to a glTF using GltfSceneConverter delegated from AnySceneConverter:

PluginManager::Manager<Trade::AbstractImporter> importerManager;
Containers::Pointer<Trade::AbstractImporter> importer =
    importerManager.loadAndInstantiate("AnySceneImporter");
if(!importer || importer->openFile("file.dae"))
    Fatal{} << "Can't open the input file";

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

if(!converter->beginFile("file.gltf") ||
   !converter->addSupportedImporterContents(*importer) ||
   !converter->endFile())
    Fatal{} << "Can't save the output file";

This API takes an optional second parameter, SceneContents, allowing you to selectively perform operations on certain data types while still making use of the convenience passthrough for the rest. The following snippet will remove duplicates from all meshes before saving them to the output:

if(!converter->beginFile("file.gltf"))
    Fatal{} << "Can't begin the output file";

/* Add meshes manually, removing duplicates in each in the process */
for(UnsignedInt i = 0; i != importer->meshCount(); ++i) {
    Containers::Optional<Trade::MeshData> mesh = importer->mesh(i);
    if(!mesh ||
       !converter->add(MeshTools::removeDuplicates(*mesh), importer->meshName(i)))
        Fatal{} << "Can't add mesh" << i;
}

/* Add the rest of the input file and finish */
if(!converter->addSupportedImporterContents(*importer, ~Trade::SceneContent::Meshes) ||
   !converter->endFile())
    Fatal{} << "Can't save the output file";

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(), doConvertToFile() functions based on what single-mesh conversion features are supported, or pairs of doBegin() / doEnd(), doBeginData() / doEndData(), doBeginFile() / doEndFile() functions and one or more doAdd() functions based on what multiple-data features are supported.

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

For user convenience it's possible to use a single-mesh converter through the multi-mesh interface as well as use a multi-mesh converter through the single-mesh interface. The base class can proxy one to the other and does all necessary edge-case checks:

Derived classes

class AnySceneConverter new in 2020.06
Any scene converter plugin.
class GltfSceneConverter new in Git master
glTF 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.
auto isConverting() const -> bool new in Git master
Whether any conversion is in progress.
void abort() new in Git master
Abort any in-progress conversion.
auto begin() -> bool new in Git master
Begin converting a scene.
auto end() -> Containers::Pointer<AbstractImporter> new in Git master
End converting a scene.
auto beginData() -> bool new in Git master
Begin converting a scene to raw data.
auto endData() -> Containers::Optional<Containers::Array<char>> new in Git master
End converting a scene to raw data.
auto beginFile(Containers::StringView filename) -> bool new in Git master
Begin converting a scene to a file.
auto endFile() -> bool new in Git master
End converting a scene to raw data.
auto sceneCount() const -> UnsignedInt new in Git master
Count of added scenes.
auto add(const SceneData& data, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a scene.
void setSceneFieldName(SceneField field, Containers::StringView name) new in Git master
Set name of a custom scene field.
void setObjectName(UnsignedLong object, Containers::StringView name) new in Git master
Set object name.
void setDefaultScene(UnsignedInt id) new in Git master
Set default scene.
auto animationCount() const -> UnsignedInt new in Git master
Count of added animations.
auto add(const AnimationData& animation, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add an animation.
void setAnimationTrackTargetName(AnimationTrackTarget target, Containers::StringView name) new in Git master
Set name of a custom animation track target.
auto lightCount() const -> UnsignedInt new in Git master
Count of added lights.
auto add(const LightData& light, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a light.
auto cameraCount() const -> UnsignedInt new in Git master
Count of added cameras.
auto add(const CameraData& camera, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a camera.
auto skin2DCount() const -> UnsignedInt new in Git master
Count of added 2D skins.
auto add(const SkinData2D& skin, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a 2D skin.
auto skin3DCount() const -> UnsignedInt new in Git master
Count of added 3D skins.
auto add(const SkinData3D& skin, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a 3D skin.
auto meshCount() const -> UnsignedInt new in Git master
Count of added meshes.
auto add(const MeshData& mesh, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a mesh.
auto add(const Containers::Iterable<const MeshData>& meshLevels, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a set of mesh levels.
void setMeshAttributeName(MeshAttribute attribute, Containers::StringView name) new in Git master
Set name of a custom mesh attribute.
auto materialCount() const -> UnsignedInt new in Git master
Count of added materials.
auto add(const MaterialData& material, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a material.
auto textureCount() const -> UnsignedInt new in Git master
Count of added textures.
auto add(const TextureData& texture, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a texture.
auto image1DCount() const -> UnsignedInt new in Git master
Count of added 1D images.
auto add(const ImageData1D& image, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a 1D image.
auto add(const ImageView1D& image, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
auto add(const CompressedImageView1D& image, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
auto add(const Containers::Iterable<const ImageData1D>& imageLevels, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a set of 1D image levels.
auto add(const Containers::Iterable<const ImageView1D>& imageLevels, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
auto add(const Containers::Iterable<const CompressedImageView1D>& imageLevels, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
auto image2DCount() const -> UnsignedInt new in Git master
Count of added 2D images.
auto add(const ImageData2D& image, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a 2D image.
auto add(const ImageView2D& image, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
auto add(const CompressedImageView2D& image, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
auto add(const Containers::Iterable<const ImageData2D>& imageLevels, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a set of 2D image levels.
auto add(const Containers::Iterable<const ImageView2D>& imageLevels, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
auto add(const Containers::Iterable<const CompressedImageView2D>& imageLevels, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
auto image3DCount() const -> UnsignedInt new in Git master
Count of added 3D images.
auto add(const ImageData3D& image, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a 3D image.
auto add(const ImageView3D& image, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
auto add(const CompressedImageView3D& image, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
auto add(const Containers::Iterable<const ImageData3D>& imageLevels, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
Add a set of 3D image levels.
auto add(const Containers::Iterable<const ImageView3D>& imageLevels, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
auto add(const Containers::Iterable<const CompressedImageView3D>& imageLevels, Containers::StringView name = {}) -> Containers::Optional<UnsignedInt> new in Git master
auto addImporterContents(AbstractImporter& importer, SceneContents contents = ~SceneContents{}) -> bool new in Git master
Add importer contents.
auto addSupportedImporterContents(AbstractImporter& importer, SceneContents contents = ~SceneContents{}) -> bool new in Git master
Add supported importer contents.

Protected functions

auto doConvertToFile(const MeshData& mesh, Containers::StringView filename) -> bool virtual
Implementation for convertToFile(const MeshData&, Containers::StringView)
auto doBeginFile(Containers::StringView filename) -> bool virtual new in Git master
Implementation for beginFile()
auto doEndFile(Containers::StringView filename) -> bool virtual new in Git master
Implementation for endFile()

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&)
void doAbort() virtual new in Git master
Implementation for abort()
auto doBegin() -> bool virtual new in Git master
Implementation for begin()
auto doEnd() -> Containers::Pointer<AbstractImporter> virtual new in Git master
Implementation for end()
auto doBeginData() -> bool virtual new in Git master
Implementation for beginData()
auto doEndData() -> Containers::Optional<Containers::Array<char>> virtual new in Git master
Implementation for endData()
auto doAdd(UnsignedInt id, const SceneData& scene, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const SceneData&, Containers::StringView)
void doSetSceneFieldName(SceneField field, Containers::StringView name) virtual new in Git master
Implementation for setSceneFieldName()
void doSetObjectName(UnsignedLong object, Containers::StringView name) virtual new in Git master
Implementation for setObjectName()
void doSetDefaultScene(UnsignedInt id) virtual new in Git master
Implementation for setDefaultScene()
auto doAdd(UnsignedInt id, const AnimationData& animation, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const AnimationData&, Containers::StringView)
void doSetAnimationTrackTargetName(AnimationTrackTarget target, Containers::StringView name) virtual new in Git master
Implementation for setAnimationTrackTargetName()
auto doAdd(UnsignedInt id, const LightData& light, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const LightData&, Containers::StringView)
auto doAdd(UnsignedInt id, const CameraData& camera, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const CameraData&, Containers::StringView)
auto doAdd(UnsignedInt id, const SkinData2D& skin, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const SkinData2D&, Containers::StringView)
auto doAdd(UnsignedInt id, const SkinData3D& skin, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const SkinData3D&, Containers::StringView)
auto doAdd(UnsignedInt id, const MeshData& mesh, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const MeshData&, Containers::StringView)
auto doAdd(UnsignedInt id, const Containers::Iterable<const MeshData>& meshLevels, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const Containers::Iterable<const MeshData>&, Containers::StringView)
void doSetMeshAttributeName(MeshAttribute attribute, Containers::StringView name) virtual new in Git master
Implementation for setMeshAttributeName()
auto doAdd(UnsignedInt id, const MaterialData& material, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const MaterialData&, Containers::StringView)
auto doAdd(UnsignedInt id, const TextureData& texture, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const TextureData&, Containers::StringView)
auto doAdd(UnsignedInt id, const ImageData1D& image, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const ImageData1D&, Containers::StringView)
auto doAdd(UnsignedInt id, const Containers::Iterable<const ImageData1D>& imageLevels, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const Containers::Iterable<const ImageData1D>&, Containers::StringView)
auto doAdd(UnsignedInt id, const ImageData2D& image, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const ImageData2D&, Containers::StringView)
auto doAdd(UnsignedInt id, const Containers::Iterable<const ImageData2D>& imageLevels, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const Containers::Iterable<const ImageData2D>&, Containers::StringView)
auto doAdd(UnsignedInt id, const ImageData3D& image, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const ImageData3D&, Containers::StringView)
auto doAdd(UnsignedInt id, const Containers::Iterable<const ImageData3D>& imageLevels, Containers::StringView name) -> bool virtual new in Git master
Implementation for add(const Containers::Iterable<const ImageData3D>&, Containers::StringView)

Function documentation

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

Plugin interface.

"cz.mosra.magnum.Trade.AbstractSceneConverter/0.2.2"

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.

If a (batch) conversion is currently in progress, calls abort() first. On failure prints a message to Error and returns Containers::NullOpt.

Expects that SceneConverterFeature::ConvertMesh is supported. If SceneConverterFeature::AddMeshes is supported instead, you have to use begin(), add(const MeshData&, Containers::StringView) and retrieve the output from the importer returned by end() — in such case the process can also return zero or more than one mesh instead of always exactly one.

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

Convert a mesh in-place.

If a (batch) conversion is currently in progress, calls abort() first. On failure prints a message to Error and returns false, mesh is guaranteed to stay unchanged.

Expects that SceneConverterFeature::ConvertMeshInPlace is supported.

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

Convert a mesh to a raw data.

If (batch) conversion is currently in progress, calls abort() first. On failure prints a message to Error and returns Containers::NullOpt.

Expects that SceneConverterFeature::ConvertMeshToData is supported. If not and both SceneConverterFeature::ConvertMultipleToData and SceneConverterFeature::AddMeshes is supported instead, delegates to a sequence of beginData(), add(const MeshData&, Containers::StringView) and endData().

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

Convert a mesh to a file.

If a (batch) conversion is currently in progress, calls abort() first. On failure prints a message to Error and returns false.

Expects that SceneConverterFeature::ConvertMeshToFile is supported. If not and both SceneConverterFeature::ConvertMultipleToFile and SceneConverterFeature::AddMeshes is supported instead, delegates to a sequence of beginFile(), add(const MeshData&, Containers::StringView) and endFile().

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

Convert a mesh to a file.

bool Magnum::Trade::AbstractSceneConverter::isConverting() const new in Git master

Whether any conversion is in progress.

Returns true if any conversion started by begin(), beginData() or beginFile() has not ended yet and abort() wasn't called; false otherwise.

void Magnum::Trade::AbstractSceneConverter::abort() new in Git master

Abort any in-progress conversion.

On particular implementations an explicit call to this function may result in freed memory. If no conversion is currently in progress, does nothing. After this function is called, isConverting() returns false.

bool Magnum::Trade::AbstractSceneConverter::begin() new in Git master

Begin converting a scene.

If a conversion is currently in progress, calls abort() first. The converted output of data supplied via various add() and set*() APIs is returned via an importer instance upon calling end(). On failure prints a message to Error and returns false.

Expects that SceneConverterFeature::ConvertMultiple is supported. If not and SceneConverterFeature::ConvertMesh is supported instead, sets up internal state in order to delegate add(const MeshData&, Containers::StringView) to convert(const MeshData&) and return the result from end().

Containers::Pointer<AbstractImporter> Magnum::Trade::AbstractSceneConverter::end() new in Git master

End converting a scene.

Expects that begin() was called before. The returned AbstractImporter may contain arbitrary amounts of data depending on the particular converter plugin. On failure prints a message to Error and returns nullptr.

If SceneConverterFeature::ConvertMultiple is not supported and SceneConverterFeature::ConvertMesh is supported instead, returns an importer exposing a single mesh that was converted via the add(const MeshData&, Containers::StringView) call, which delegated to convert(const MeshData&). To simplify data ownership logic, the mesh can be extracted from the returned importer only once, subsequent calls to AbstractImporter::mesh() will fail. If no mesh was added, prints a message to Error and returns nullptr.

bool Magnum::Trade::AbstractSceneConverter::beginData() new in Git master

Begin converting a scene to raw data.

If a conversion is currently in progress, calls abort() first. The converted output of data supplied via various add() and set*() APIs is returned upon calling endData(). On failure prints a message to Error and returns false.

Expects that SceneConverterFeature::ConvertMultipleToData is supported. If not and SceneConverterFeature::ConvertMeshToData is supported instead, sets up internal state in order to delegate add(const MeshData&, Containers::StringView) to convertToData(const MeshData&) and return the result from endData().

Containers::Optional<Containers::Array<char>> Magnum::Trade::AbstractSceneConverter::endData() new in Git master

End converting a scene to raw data.

Expects that beginData() was called before. On failure prints a message to Error and returns Containers::NullOpt.

If SceneConverterFeature::ConvertMultipleToData is not supported and SceneConverterFeature::ConvertMeshToData is supported instead, returns data converted via the add(const MeshData&, Containers::StringView) call, which delegated to convertToData(const MeshData&). If no mesh was added, prints a message to Error and returns Containers::NullOpt.

bool Magnum::Trade::AbstractSceneConverter::beginFile(Containers::StringView filename) new in Git master

Begin converting a scene to a file.

If a conversion is currently in progress, calls abort() first. The converted output of data supplied via various add() and set*() APIs is returned upon calling endFile(). On failure prints a message to Error and returns false.

Expects that SceneConverterFeature::ConvertMultipleToFile is supported. If not and SceneConverterFeature::ConvertMeshToFile is supported instead, sets up internal state in order to delegate add(const MeshData&, Containers::StringView) to convertToFile(const MeshData&, Containers::StringView) and return the result from endFile().

bool Magnum::Trade::AbstractSceneConverter::endFile() new in Git master

End converting a scene to raw data.

Expects that beginData() was called before. On failure prints a message to Error and returns false.

If SceneConverterFeature::ConvertMultipleToFile is not supported and SceneConverterFeature::ConvertMeshToFile is supported instead, returns a result of the add(const MeshData&, Containers::StringView) call, which delegated to convertToFile(const MeshData&, Containers::StringView). If no mesh was added, prints a message to Error and returns Containers::NullOpt.

UnsignedInt Magnum::Trade::AbstractSceneConverter::sceneCount() const new in Git master

Count of added scenes.

Count of scenes successfully added with add(const SceneData&, Containers::StringView) since the initial begin(), beginData() or beginFile() call. Expects that a conversion is currently in progress. If SceneConverterFeature::AddScenes is not supported, returns 0.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const SceneData& data, Containers::StringView name = {}) new in Git master

Add a scene.

Expects that a conversion is currently in progress and SceneConverterFeature::AddScenes is supported. The returned ID is implicitly equal to sceneCount() before calling this function and can be subsequently used in functions like setDefaultScene(). On failure prints a message to Error and returns Containers::NullOpt — the count of added animations doesn't change in that case.

If the converter doesn't support scene naming, name is ignored.

Because a scene directly or indirectly references majority of other data, it's recommended to be added only after all data it uses are added as well. Particular converter plugins may have looser requirements, but adding it last guarantees that the conversion process doesn't fail due to the scene referencing yet-unknown data.

void Magnum::Trade::AbstractSceneConverter::setSceneFieldName(SceneField field, Containers::StringView name) new in Git master

Set name of a custom scene field.

Expects that a conversion is currently in progress, SceneConverterFeature::AddScenes is supported and field is a custom field. The field name will get used only for scene data added after this function has been called. If the converter doesn't support custom scene fields or doesn't support naming them, the call is ignored.

void Magnum::Trade::AbstractSceneConverter::setObjectName(UnsignedLong object, Containers::StringView name) new in Git master

Set object name.

Expects that a conversion is currently in progress, SceneConverterFeature::AddScenes is supported and field is a custom field. The object name will get used only for scene data added after this function has been called. If the converter doesn't support naming objects, the call is ignored.

void Magnum::Trade::AbstractSceneConverter::setDefaultScene(UnsignedInt id) new in Git master

Set default scene.

Expects that a conversion is currently in progress, SceneConverterFeature::AddScenes is supported and sceneCount() is greater than id. If the converter doesn't support multiple scenes or default scene selection, the call is ignored.

UnsignedInt Magnum::Trade::AbstractSceneConverter::animationCount() const new in Git master

Count of added animations.

Count of animations successfully added with add(const AnimationData&, Containers::StringView) since the initial begin(), beginData() or beginFile() call. Expects that a conversion is currently in progress. If SceneConverterFeature::AddAnimations is not supported, returns 0.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const AnimationData& animation, Containers::StringView name = {}) new in Git master

Add an animation.

Expects that a conversion is currently in progress and SceneConverterFeature::AddAnimations is supported. The returned ID is implicitly equal to animationCount() before calling this function. On failure prints a message to Error and returns Containers::NullOpt — the count of added animations doesn't change in that case.

If the converter doesn't support animation naming, name is ignored.

void Magnum::Trade::AbstractSceneConverter::setAnimationTrackTargetName(AnimationTrackTarget target, Containers::StringView name) new in Git master

Set name of a custom animation track target.

Expects that a conversion is currently in progress, SceneConverterFeature::AddAnimations is supported and target is a custom target. The target name will get used only for animation data added after this function has been called. If the converter doesn't support custom animation track target or doesn't support naming them, the call is ignored.

UnsignedInt Magnum::Trade::AbstractSceneConverter::lightCount() const new in Git master

Count of added lights.

Count of lights successfully added with add(const LightData&, Containers::StringView) since the initial begin(), beginData() or beginFile() call. Expects that a conversion is currently in progress. If SceneConverterFeature::AddLights is not supported, returns 0.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const LightData& light, Containers::StringView name = {}) new in Git master

Add a light.

Expects that a conversion is currently in progress and SceneConverterFeature::AddLights is supported. The returned ID is implicitly equal to lightCount() before calling this function and can be subsequently used to for example reference a light from a SceneData passed to add(const SceneData&, Containers::StringView). On failure prints a message to Error and returns Containers::NullOpt — the count of added lights doesn't change in that case.

If the converter doesn't support light naming, name is ignored.

UnsignedInt Magnum::Trade::AbstractSceneConverter::cameraCount() const new in Git master

Count of added cameras.

Count of cameras successfully added with add(const CameraData&, Containers::StringView) since the initial begin(), beginData() or beginFile() call. Expects that a conversion is currently in progress. If SceneConverterFeature::AddCameras is not supported, returns 0.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const CameraData& camera, Containers::StringView name = {}) new in Git master

Add a camera.

Expects that a conversion is currently in progress and SceneConverterFeature::AddCameras is supported. The returned ID is implicitly equal to cameraCount() before calling this function and can be subsequently used to for example reference a camera from a SceneData passed to add(const SceneData&, Containers::StringView). On failure prints a message to Error and returns Containers::NullOpt — the count of added cameras doesn't change in that case.

If the converter doesn't support camera naming, name is ignored.

UnsignedInt Magnum::Trade::AbstractSceneConverter::skin2DCount() const new in Git master

Count of added 2D skins.

Count of skins successfully added with add(const SkinData2D&, Containers::StringView) since the initial begin(), beginData() or beginFile() call. Expects that a conversion is currently in progress. If SceneConverterFeature::AddSkins2D is not supported, returns 0.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const SkinData2D& skin, Containers::StringView name = {}) new in Git master

Add a 2D skin.

Expects that a conversion is currently in progress and SceneConverterFeature::AddSkins2D is supported. The returned ID is implicitly equal to skin2DCount() before calling this function. On failure prints a message to Error and returns Containers::NullOpt — the count of added skins doesn't change in that case.

If the converter doesn't support skin naming, name is ignored.

UnsignedInt Magnum::Trade::AbstractSceneConverter::skin3DCount() const new in Git master

Count of added 3D skins.

Count of skins successfully added with add(const SkinData3D&, Containers::StringView) since the initial begin(), beginData() or beginFile() call. Expects that a conversion is currently in progress. If SceneConverterFeature::AddSkins3D is not supported, returns 0.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const SkinData3D& skin, Containers::StringView name = {}) new in Git master

Add a 3D skin.

Expects that a conversion is currently in progress and SceneConverterFeature::AddSkins3D is supported. The returned ID is implicitly equal to skin3DCount() before calling this function. On failure prints a message to Error and returns Containers::NullOpt — the count of added skins doesn't change in that case.

If the converter doesn't support skin naming, name is ignored.

UnsignedInt Magnum::Trade::AbstractSceneConverter::meshCount() const new in Git master

Count of added meshes.

Count of meshes successfully added with add(const MeshData&, Containers::StringView) or add(const Containers::Iterable<const MeshData>&, Containers::StringView) since the initial begin(), beginData() or beginFile() call. Expects that a conversion is currently in progress. If SceneConverterFeature::AddMeshes is not supported and only the singular ConvertMesh, ConvertMeshToData or ConvertMeshToFile is supported, returns always either 0 or 1. Otherwise returns 0.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const MeshData& mesh, Containers::StringView name = {}) new in Git master

Add a mesh.

Expects that a conversion is currently in progress and either SceneConverterFeature::AddMeshes, ConvertMesh, ConvertMeshToData or ConvertMeshToFile is supported. The returned ID is implicitly equal to meshCount() before calling this function and can be subsequently used to for example reference a mesh from a SceneData passed to add(const SceneData&, Containers::StringView). On failure prints a message to Error and returns Containers::NullOpt — the count of added meshes doesn't change in that case.

If the converter doesn't support mesh naming, name is ignored.

If only the singular SceneConverterFeature::ConvertMesh, ConvertMeshToData or ConvertMeshToFile is supported, the function can be called only exactly once to successfully produce an output, and the process is equivalent to convert(const MeshData&), convertToData(const MeshData&) or convertToFile(const MeshData&, Containers::StringView), with the name ignored.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const Containers::Iterable<const MeshData>& meshLevels, Containers::StringView name = {}) new in Git master

Add a set of mesh levels.

Expects that a conversion is currently in progress and SceneConverterFeature::MeshLevels together with AddMeshes is supported. The returned ID is implicitly equal to meshCount() before calling this function and can be subsequently used to for example reference a mesh from a SceneData passed to add(const SceneData&, Containers::StringView); all levels together are treated as a single mesh. On failure prints a message to Error and returns Containers::NullOpt — the count of added meshes doesn't change in that case.

If the converter doesn't support mesh naming, name is ignored.

void Magnum::Trade::AbstractSceneConverter::setMeshAttributeName(MeshAttribute attribute, Containers::StringView name) new in Git master

Set name of a custom mesh attribute.

Expects that either a batch conversion is currently in progress and SceneConverterFeature::AddMeshes is supported, or that at least one of SceneConverterFeature::ConvertMesh, ConvertMeshInPlace, ConvertMeshToData or ConvertMeshToFile is supported. The attribute is expected to be custom. The name will get used only for mesh data added or converted after this function has been called. If the converter doesn't support custom mesh attributes or doesn't support naming them, the call is ignored.

UnsignedInt Magnum::Trade::AbstractSceneConverter::materialCount() const new in Git master

Count of added materials.

Count of materials successfully added with add(const MaterialData&, Containers::StringView) since the initial begin(), beginData() or beginFile() call. Expects that a conversion is currently in progress. If SceneConverterFeature::AddMaterials is not supported, returns 0.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const MaterialData& material, Containers::StringView name = {}) new in Git master

Add a material.

Expects that a conversion is currently in progress and SceneConverterFeature::AddMaterials is supported. The returned ID is implicitly equal to materialCount() before calling this function and can be subsequently used to for example reference a material from a SceneData passed to add(const SceneData&, Containers::StringView). On failure prints a message to Error and returns Containers::NullOpt — the count of added materials doesn't change in that case.

If the converter doesn't support material naming, name is ignored.

Because a material directly or indirectly references textures and images, it's recommended to be added only after all data it uses are added as well. Particular converter plugins may have looser requirements, but adding it last guarantees that the conversion process doesn't fail due to the material referencing yet-unknown data.

UnsignedInt Magnum::Trade::AbstractSceneConverter::textureCount() const new in Git master

Count of added textures.

Count of textures successfully added with add(const TextureData&, Containers::StringView) since the initial begin(), beginData() or beginFile() call. Expects that a conversion is currently in progress. If SceneConverterFeature::AddTextures is not supported, returns 0.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const TextureData& texture, Containers::StringView name = {}) new in Git master

Add a texture.

Expects that a conversion is currently in progress and SceneConverterFeature::AddTextures is supported. The returned ID is implicitly equal to textureCount() before calling this function and can be subsequently used to for example reference a texture from a MaterialData passed to add(const MaterialData&, Containers::StringView). On failure prints a message to Error and returns Containers::NullOpt — the count of added textures doesn't change in that case.

If the converter doesn't support texture naming, name is ignored.

Because a texture references an image, it's recommended to be added only after the image it uses is added as well. Particular converter plugins may have looser requirements, but adding it last guarantees that the conversion process doesn't fail due to the texture referencing yet-unknown data.

UnsignedInt Magnum::Trade::AbstractSceneConverter::image1DCount() const new in Git master

Count of added 1D images.

Count of images successfully added with add(const ImageData1D&, Containers::StringView) or add(const Containers::Iterable<const ImageData1D>&, Containers::StringView) and overloads since the initial begin(), beginData() or beginFile() call. Expects that a conversion is currently in progress. If neither SceneConverterFeature::AddImages1D nor AddCompressedImages1D is supported, returns 0.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const ImageData1D& image, Containers::StringView name = {}) new in Git master

Add a 1D image.

Expects that a conversion is currently in progress and either SceneConverterFeature::AddImages1D or AddCompressedImages1D is supported based on whether image is compressed. The image is expected to not be nullptr and to have a non-zero size. The returned ID is implicitly equal to image1DCount() before calling this function and can be subsequently used to for example reference an image from a TextureData passed to add(const TextureData&, Containers::StringView). On failure prints a message to Error and returns Containers::NullOpt — the count of added images doesn't change in that case.

If the converter doesn't support image naming, name is ignored.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const ImageView1D& image, Containers::StringView name = {}) new in Git master

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

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const CompressedImageView1D& image, Containers::StringView name = {}) new in Git master

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

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const Containers::Iterable<const ImageData1D>& imageLevels, Containers::StringView name = {}) new in Git master

Add a set of 1D image levels.

The imageLevels are expected to have at least one image, with the images either all uncompressed or all compressed, none having nullptr data or zero size in any dimension, and all sharing the same pixel format and layout flags. Expects that a conversion is currently in progress and SceneConverterFeature::ImageLevels together with either AddImages1D or AddCompressedImages1D is supported based on whether imageLevels are compressed. The returned ID is implicitly equal to image1DCount() before calling this function and can be subsequently used to for example reference an image from a TextureData passed to add(const TextureData&, Containers::StringView); all levels together are treated as a single image. On failure prints a message to Error and returns Containers::NullOpt — the count of added images doesn't change in that case.

If the converter doesn't support image naming, name is ignored.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const Containers::Iterable<const ImageView1D>& imageLevels, Containers::StringView name = {}) new in Git master

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

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const Containers::Iterable<const CompressedImageView1D>& imageLevels, Containers::StringView name = {}) new in Git master

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

UnsignedInt Magnum::Trade::AbstractSceneConverter::image2DCount() const new in Git master

Count of added 2D images.

Count of images successfully added with add(const ImageData2D&, Containers::StringView) or add(const Containers::Iterable<const ImageData2D>&, Containers::StringView) and overloads since the initial begin(), beginData() or beginFile() call. Expects that a conversion is currently in progress. If neither SceneConverterFeature::AddImages2D nor AddCompressedImages2D is supported, returns 0.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const ImageData2D& image, Containers::StringView name = {}) new in Git master

Add a 2D image.

Expects that a conversion is currently in progress and either SceneConverterFeature::AddImages2D or AddCompressedImages2D is supported based on whether image is compressed. The image is expected to not be nullptr and to have a non-zero size. The returned ID is implicitly equal to image2DCount() before calling this function and can be subsequently used to for example reference an image from a TextureData passed to add(const TextureData&, Containers::StringView). On failure prints a message to Error and returns Containers::NullOpt — the count of added images doesn't change in that case.

If the converter doesn't support image naming, name is ignored.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const ImageView2D& image, Containers::StringView name = {}) new in Git master

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

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const CompressedImageView2D& image, Containers::StringView name = {}) new in Git master

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

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const Containers::Iterable<const ImageData2D>& imageLevels, Containers::StringView name = {}) new in Git master

Add a set of 2D image levels.

The imageLevels are expected to have at least one image, with the images either all uncompressed or all compressed, none having nullptr data or zero size in any dimension, and all sharing the same pixel format and layout flags. Expects that a conversion is currently in progress and SceneConverterFeature::ImageLevels together with either AddImages2D or AddCompressedImages2D is supported based on whether imageLevels are compressed. The returned ID is implicitly equal to image2DCount() before calling this function and can be subsequently used to for example reference an image from a TextureData passed to add(const TextureData&, Containers::StringView); all levels together are treated as a single image. On failure prints a message to Error and returns Containers::NullOpt — the count of added images doesn't change in that case.

If the converter doesn't support image naming, name is ignored.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const Containers::Iterable<const ImageView2D>& imageLevels, Containers::StringView name = {}) new in Git master

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

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const Containers::Iterable<const CompressedImageView2D>& imageLevels, Containers::StringView name = {}) new in Git master

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

UnsignedInt Magnum::Trade::AbstractSceneConverter::image3DCount() const new in Git master

Count of added 3D images.

Count of images successfully added with add(const ImageData3D&, Containers::StringView) or add(const Containers::Iterable<const ImageData3D>&, Containers::StringView) and overloads since the initial begin(), beginData() or beginFile() call. Expects that a conversion is currently in progress. If neither SceneConverterFeature::AddImages3D nor AddCompressedImages3D is supported, returns 0.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const ImageData3D& image, Containers::StringView name = {}) new in Git master

Add a 3D image.

Expects that a conversion is currently in progress and either SceneConverterFeature::AddImages3D or AddCompressedImages3D is supported based on whether image is compressed. The image is expected to not be nullptr and to have a non-zero size. The returned ID is implicitly equal to image3DCount() before calling this function and can be subsequently used to for example reference an image from a TextureData passed to add(const TextureData&, Containers::StringView). On failure prints a message to Error and returns Containers::NullOpt — the count of added images doesn't change in that case.

If the converter doesn't support image naming, name is ignored.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const ImageView3D& image, Containers::StringView name = {}) new in Git master

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

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const CompressedImageView3D& image, Containers::StringView name = {}) new in Git master

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

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const Containers::Iterable<const ImageData3D>& imageLevels, Containers::StringView name = {}) new in Git master

Add a set of 3D image levels.

The imageLevels are expected to have at least one image, with the images either all uncompressed or all compressed, none having nullptr data or zero size in any dimension, and all sharing the same pixel format and layout flags. Expects that a conversion is currently in progress and SceneConverterFeature::ImageLevels together with either AddImages3D or AddCompressedImages3D is supported based on whether imageLevels are compressed. The returned ID is implicitly equal to image3DCount() before calling this function and can be subsequently used to for example reference an image from a TextureData passed to add(const TextureData&, Containers::StringView); all levels together are treated as a single image. On failure prints a message to Error and returns Containers::NullOpt — the count of added images doesn't change in that case.

If the converter doesn't support image naming, name is ignored.

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const Containers::Iterable<const ImageView3D>& imageLevels, Containers::StringView name = {}) new in Git master

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

Containers::Optional<UnsignedInt> Magnum::Trade::AbstractSceneConverter::add(const Containers::Iterable<const CompressedImageView3D>& imageLevels, Containers::StringView name = {}) new in Git master

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

bool Magnum::Trade::AbstractSceneConverter::addImporterContents(AbstractImporter& importer, SceneContents contents = ~SceneContents{}) new in Git master

Add importer contents.

Adds all contents from the importer as described in particular SceneContent value documentation. If any data causes a conversion error, the function immediately returns false, leaving the conversion in an in-progress state, same as any other add*() function.

Expects that a conversion is currently in progress and importer is opened. The union of contents and sceneContentsFor(const AbstractImporter&) for importer is expected to be a subset of sceneContentsFor(const AbstractSceneConverter&) for this converter — i.e., there shouldn't be any data that the converter doesn't support. Any contents that are not in sceneContentsFor(const AbstractImporter&) for importer are ignored. If you want to add just contents supported by the coverter and ignore the rest with a warning, use addSupportedImporterContents() instead.

Additionally, if contents contains SceneContent::MeshLevels / ImageLevels, the importer has multi-level meshes / images, but SceneConverterFeature::MeshLevels / ImageLevels is not supported, the function prints a message to Error and returns false. Similarly, if contents contains SceneContent::Images1D / Images2D / Images3D, the importer has compressed images, but SceneConverterFeature::AddCompressedImages1D / AddCompressedImages2D / AddCompressedImages3D isn't supported (or, conversely, the importer has uncompressed images but SceneConverterFeature::AddImages1D / AddImages2D / AddImages3D isn't supported), the function prints a message to Error and returns false. These cause a runtime error instead of an assertion because checking the prerequisites upfront could be prohibitively expensive due to having to load and parse image and other data more than once.

bool Magnum::Trade::AbstractSceneConverter::addSupportedImporterContents(AbstractImporter& importer, SceneContents contents = ~SceneContents{}) new in Git master

Add supported importer contents.

Compared to addImporterContents(), data not supported by the converter (i.e., contents that are in sceneContentsFor(const AbstractImporter&) for importer but are not in sceneContentsFor(const AbstractSceneConverter&) for the converter) are ignored with a message printed to Warning.

In case of SceneContent::MeshLevels / ImageLevels, if the converter doesn't support SceneConverterFeature::MeshLevels / ImageLevels, only the base level is added. The only case that still causes a failure is if the importer contains compressed images but converter supports only uncompressed and vice versa, same as with addImporterContents().

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.

Otherwise, if both SceneConverterFeature::ConvertMultipleToFile and SceneConverterFeature::AddMeshes is supported, default implementation calls beginData(), add(const MeshData&, Containers::StringView) and returns the output of endData(), or Containers::NullOpt if any of those failed.

bool Magnum::Trade::AbstractSceneConverter::doBeginFile(Containers::StringView filename) virtual protected new in Git master

Implementation for beginFile()

If SceneConverterFeature::ConvertMultipleToData is supported, default implementation delegates to doBeginData().

It is allowed to call this function from your doBeginFile() implementation, for example when you only need to do format detection based on file extension.

The filename string is guaranteed to stay in scope until a call to doEndFile(). It's not guaranteed to be Containers::StringViewFlag::Global or Containers::StringViewFlag::NullTerminated, however.

bool Magnum::Trade::AbstractSceneConverter::doEndFile(Containers::StringView filename) virtual protected new in Git master

Implementation for endFile()

Receives the same filename as was passed to doBeginFile() earlier. Expected to save the output data and reset the internal state for a potential new conversion to happen.

If SceneConverterFeature::ConvertMultipleToData is supported, default implementation calls doEndData() and saves the result to given file.

It is allowed to call this function from your doEndFile() 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.

Containers::Optional<Containers::Array<char>> Magnum::Trade::AbstractSceneConverter::doConvertToData(const MeshData& mesh) virtual private

Implementation for convertToData(const MeshData&)

If both SceneConverterFeature::ConvertMultipleToData and SceneConverterFeature::AddMeshes is supported, default implementation calls beginData(), add(const MeshData&, Containers::StringView) and returns the output of endData(), or Containers::NullOpt if any of those failed.

void Magnum::Trade::AbstractSceneConverter::doAbort() virtual private new in Git master

Implementation for abort()

Default implementation does nothing.

Containers::Pointer<AbstractImporter> Magnum::Trade::AbstractSceneConverter::doEnd() virtual private new in Git master

Implementation for end()

Expected to return an importer instance owning all output data and reset the internal state for a potential new conversion to happen.

Containers::Optional<Containers::Array<char>> Magnum::Trade::AbstractSceneConverter::doEndData() virtual private new in Git master

Implementation for endData()

Expected to return the output data and reset the internal state for a potential new conversion to happen.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const SceneData& scene, Containers::StringView name) virtual private new in Git master

Implementation for add(const SceneData&, Containers::StringView)

The id is equal to sceneCount() at the time this function is called.

void Magnum::Trade::AbstractSceneConverter::doSetSceneFieldName(SceneField field, Containers::StringView name) virtual private new in Git master

Implementation for setSceneFieldName()

The field is always custom. Default implementation does nothing.

void Magnum::Trade::AbstractSceneConverter::doSetObjectName(UnsignedLong object, Containers::StringView name) virtual private new in Git master

Implementation for setObjectName()

Default implementation does nothing.

void Magnum::Trade::AbstractSceneConverter::doSetDefaultScene(UnsignedInt id) virtual private new in Git master

Implementation for setDefaultScene()

Default implementation does nothing.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const AnimationData& animation, Containers::StringView name) virtual private new in Git master

Implementation for add(const AnimationData&, Containers::StringView)

The id is equal to animationCount() at the time this function is called.

void Magnum::Trade::AbstractSceneConverter::doSetAnimationTrackTargetName(AnimationTrackTarget target, Containers::StringView name) virtual private new in Git master

Implementation for setAnimationTrackTargetName()

The target is always custom. Default implementation does nothing.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const LightData& light, Containers::StringView name) virtual private new in Git master

Implementation for add(const LightData&, Containers::StringView)

The id is equal to lightCount() at the time this function is called.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const CameraData& camera, Containers::StringView name) virtual private new in Git master

Implementation for add(const CameraData&, Containers::StringView)

The id is equal to cameraCount() at the time this function is called.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const SkinData2D& skin, Containers::StringView name) virtual private new in Git master

Implementation for add(const SkinData2D&, Containers::StringView)

The id is equal to skin2DCount() at the time this function is called.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const SkinData3D& skin, Containers::StringView name) virtual private new in Git master

Implementation for add(const SkinData3D&, Containers::StringView)

The id is equal to skin3DCount() at the time this function is called.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const MeshData& mesh, Containers::StringView name) virtual private new in Git master

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

The id is equal to meshCount() at the time this function is called.

If SceneConverterFeature::AddMeshes together with MeshLevels is supported, default implementation calls doAdd(UnsignedInt, const Containers::Iterable<const MeshData>&, Containers::StringView) with just the single mesh.

Otherwise, if SceneConverterFeature::ConvertMesh, ConvertMeshToData or ConvertMeshToFile is supported, default implementation delegates to doConvert(const MeshData&), doConvertToData(const MeshData&) or doConvertToFile(const MeshData&, Containers::StringView) and remembers the result to return it from doEnd(), doEndData() or doEndFile(). If the delegated-to function fails, returns false and the subsequent doEnd(), doEndData() or doEndFile() call prints a message to Error and returns a nullptr, Containers::NullOpt or false. Since the delegation operates just on a single mesh at a time, if this function is called more than once after a begin(), beginData() or beginFile(), prints a message to Error and returns false.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const Containers::Iterable<const MeshData>& meshLevels, Containers::StringView name) virtual private new in Git master

Implementation for add(const Containers::Iterable<const MeshData>&, Containers::StringView)

The id is equal to meshCount() at the time this function is called.

void Magnum::Trade::AbstractSceneConverter::doSetMeshAttributeName(MeshAttribute attribute, Containers::StringView name) virtual private new in Git master

Implementation for setMeshAttributeName()

The attribute is always custom. Default implementation does nothing.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const MaterialData& material, Containers::StringView name) virtual private new in Git master

Implementation for add(const MaterialData&, Containers::StringView)

The id is equal to materialCount() at the time this function is called.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const TextureData& texture, Containers::StringView name) virtual private new in Git master

Implementation for add(const TextureData&, Containers::StringView)

The id is equal to textureCount() at the time this function is called.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const ImageData1D& image, Containers::StringView name) virtual private new in Git master

Implementation for add(const ImageData1D&, Containers::StringView)

The id is equal to image1DCount() at the time this function is called. If add(const ImageView1D&, Containers::StringView) or add(const CompressedImageView1D&, Containers::StringView) was called, receives the view wrapped in a non-owning ImageData1D instance.

If SceneConverterFeature::ImageLevels is supported, default implementation calls doAdd(UnsignedInt, const Containers::Iterable<const ImageData1D>&, Containers::StringView) with just the single image.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const Containers::Iterable<const ImageData1D>& imageLevels, Containers::StringView name) virtual private new in Git master

Implementation for add(const Containers::Iterable<const ImageData1D>&, Containers::StringView)

The id is equal to image1DCount() at the time this function is called. If add(const Containers::Iterable<const ImageView1D>&, Containers::StringView) or add(const Containers::Iterable<const CompressedImageView1D>&, Containers::StringView) was called, receives the views wrapped in non-owning ImageData1D instances.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const ImageData2D& image, Containers::StringView name) virtual private new in Git master

Implementation for add(const ImageData2D&, Containers::StringView)

The id is equal to image2DCount() at the time this function is called. If add(const ImageView2D&, Containers::StringView) or add(const CompressedImageView2D&, Containers::StringView) was called, receives the view wrapped in a non-owning ImageData2D instance.

If SceneConverterFeature::ImageLevels is supported, default implementation calls doAdd(UnsignedInt, const Containers::Iterable<const ImageData2D>&, Containers::StringView) with just the single image.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const Containers::Iterable<const ImageData2D>& imageLevels, Containers::StringView name) virtual private new in Git master

Implementation for add(const Containers::Iterable<const ImageData2D>&, Containers::StringView)

The id is equal to image2DCount() at the time this function is called. If add(const Containers::Iterable<const ImageView2D>&, Containers::StringView) or add(const Containers::Iterable<const CompressedImageView2D>&, Containers::StringView) was called, receives the views wrapped in non-owning ImageData2D instances.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const ImageData3D& image, Containers::StringView name) virtual private new in Git master

Implementation for add(const ImageData3D&, Containers::StringView)

The id is equal to image3DCount() at the time this function is called. If add(const ImageView3D&, Containers::StringView) or add(const CompressedImageView3D&, Containers::StringView) was called, receives the view wrapped in a non-owning ImageData3D instance.

If SceneConverterFeature::ImageLevels is supported, default implementation calls doAdd(UnsignedInt, const Containers::Iterable<const ImageData3D>&, Containers::StringView) with just the single image.

bool Magnum::Trade::AbstractSceneConverter::doAdd(UnsignedInt id, const Containers::Iterable<const ImageData3D>& imageLevels, Containers::StringView name) virtual private new in Git master

Implementation for add(const Containers::Iterable<const ImageData3D>&, Containers::StringView)

The id is equal to image3DCount() at the time this function is called. If add(const Containers::Iterable<const ImageView3D>&, Containers::StringView) or add(const Containers::Iterable<const CompressedImageView3D>&, Containers::StringView) was called, receives the views wrapped in non-owning ImageData3D instances.