Magnum::Trade::AbstractImporter class
#include <Magnum/Trade/AbstractImporter.h>

Base for importer plugins.

Contents

Provides interface for importing generic scene data such as images, meshes or animations.

A scene file can generally have an arbitrary amount of data of particular kind and so the importer provides a set of thing(id) accessors, where the ID is from 0 to thingCount() - 1. Certain kinds of data can also reference each other via the ID (for example a material specifies the ID of a texture it uses). The following kinds of data can be imported:

Except for pure image formats that always have at least one image, in general there's no guarantee that an imported file has always a mesh, a scene or a camera. So unless the particular importer documentation says otherwise, you're expected to always check the count before attempting an import.

Usage

Importers are commonly implemented as plugins, which means the concrete importer implementation is loaded and instantiated through a PluginManager::Manager. A file is opened using either openFile(), openData() or, in rare cases, openState() amd it stays open until the importer is destroyed, close() is called or another file is opened.

With a file open you can then query the importer for particular data. Where possible, the import is performed lazily only when you actually request that particular data, and thus it can be assumed that opening a file is relatively cheap.

Since the importers deal with untrusted external data, it's needed to perform explicit error handling on the application side. There are two cases where it can fail — during opening, in which case the function returns false, and during the actual data import, in which case you get an empty Containers::Optional. In both cases the actual failure reason is printed to the error output. Everything else (IDs out of bounds, calling functions without a file open, accessing an empty optional, ...) is treated as a programmer error and will produce the usual assertions.

In the following example an image is loaded from the filesystem using the AnyImageImporter plugin, completely with all needed error handling:

PluginManager::Manager<Trade::AbstractImporter> manager;
Containers::Pointer<Trade::AbstractImporter> importer =
    manager.loadAndInstantiate("AnyImageImporter");
if(!importer || !importer->openFile("image.png"))
    Fatal{} << "Can't open image.png with AnyImageImporter";

Containers::Optional<Trade::ImageData2D> image = importer->image2D(0);
if(!image) Fatal{} << "Importing the image failed";

// use the image ...

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 importer plugins.

Loading data from memory, using file callbacks

Besides loading data directly from the filesystem using openFile() like shown above, it's possible to use openData() to import data from memory (for example from Utility::Resource). Note that the particular importer implementation has to support ImporterFeature::OpenData for this method to work:

Utility::Resource rs{"data"};
Containers::ArrayView<const char> data = rs.getRaw("image.png");
if(!importer->openData(data))
    Fatal{} << "Can't open image data with AnyImageImporter";

// import & use the image like above ...

Complex scene files often reference other files such as images and in that case you may want to intercept those references and load them in a custom way as well. For importers that advertise support for this with ImporterFeature::FileCallback this is done by specifying a file loading callback using setFileCallback(). The callback gets a filename, InputFileCallbackPolicy and an user pointer as parameters; returns a non-owning view on the loaded data or a Containers::NullOpt to indicate the file loading failed. For example, loading a scene from memory-mapped files could look like below. Note that the file loading callback affects openFile() as well — you don't have to load the top-level file manually and pass it to openData(), any importer supporting the callback feature handles that correctly.

struct Data {
    std::unordered_map<std::string,
        Containers::Array<const char, Utility::Directory::MapDeleter>> files;
} data;

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

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

        /* Load if not there yet */
        if(found == data.files.end()) found = data.files.emplace(
            filename, Utility::Directory::mapRead(filename)).first;

        return Containers::arrayView(found->second);
    }, data);

importer->openFile("scene.gltf"); // memory-maps all files

For importers that don't support ImporterFeature::FileCallback directly, the base openFile() implementation will use the file callback to pass the loaded data through to openData(), in case the importer supports at least ImporterFeature::OpenData. If the importer supports neither ImporterFeature::FileCallback nor ImporterFeature::OpenData, setFileCallback() doesn't allow the callbacks to be set.

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

Mapping between IDs and string names

Certain file formats have the ability to assign string names to objects, materials and other parts of the scene. These are not imported as part of the various Trade::MeshData etc. structures, instead the importer itself allows you to map IDs to names and vice versa. As a convenience feature, it's also possible to import data directly using their name instead of having to map the name to an IDs first. In that case the function will return an empty Containers::Optional both if the import failed or if the name doesn't exist.

Internal importer state

Some importers, especially ones that make use of well-known external libraries, expose internal state through various accessors:

Besides exposing internal state, importers that support the ImporterFeature::OpenState feature can also attach to existing importer state using openState(). See documentation of a particular importer for details about concrete types returned and accepted by these functions.

Polymorphic imported data types

Some data access functions return Containers::Pointer instead of Containers::Optional because the result might be a particular subclass of given type. Those functions are object2D() and object3D(). You can cast the abstract base to a concrete type depending on its reported type, for example:

Containers::Pointer<Trade::ObjectData3D> data = importer->object3D(12);
if(data && data->instanceType() == Trade::ObjectInstanceType3D::Mesh) {
    auto& mesh = static_cast<Trade::MeshObjectData3D&>(*data);

    materialIndex = mesh.material();
    // ...
}

Another option is making use of the Containers::pointerCast() utility, but note that in that case the original Containers::Pointer will have to be moved into a new instance, which might not be desirable.

Data dependency

The *Data instances returned from various functions by design have no dependency on the importer instance and neither on the dynamic plugin module. In other words, you don't need to keep the importer instance (or the plugin manager instance) around in order to have the *Data instances valid. Moreover, all Containers::Array instances returned through ImageData, AnimationData, MaterialData, MeshData and SkinData are only allowed to have default deleters (or be non-owning instances created from Containers::ArrayView) — this is to avoid potential dangling function pointer calls when destructing such instances after the plugin module has been unloaded.

The only exception are various importerState() functions described above, but in that case the relation is weak — these are valid only as long as the currently opened file is kept open. If the file gets closed or the importer instance deleted, the state pointers become dangling, and that's fine as long as you don't access them.

Subclassing

The plugin needs to implement the doFeatures(), doIsOpened() functions, at least one of doOpenData() / doOpenFile() / doOpenState() functions, function doClose() and one or more tuples of data access functions, based on what features are supported in given format.

In order to support ImporterFeature::FileCallback, the importer needs to properly use the callbacks to both load the top-level file in doOpenFile() and also load any external files when needed. The doOpenFile() can delegate back into the base implementation, but it should remember at least the base file path to pass correct paths to subsequent file callbacks. The doSetFileCallback() can be overridden in case it's desired to respond to file loading callback setup, but doesn't have to be.

For multi-data formats the file opening shouldn't take long and all parsing should be done in the data parsing functions instead, because the user might want to import only some data. This is obviously not the case for single-data formats like images, as the file contains all the data the user wants to import.

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

Derived classes

class AnyImageImporter
Any image importer plugin.
class AnySceneImporter
Any scene importer plugin.
class AssimpImporter
Assimp importer.
class BasisImporter new in 2019.10
Basis Universal importer plugin.
class CgltfImporter new in Git master
Cgltf importer plugin.
class DdsImporter
DDS image importer plugin.
class DevIlImageImporter
DevIL Image importer plugin.
class IcoImporter new in 2020.06
ICO importer plugin.
class JpegImporter
JPEG importer plugin.
class KtxImporter new in Git master
KTX2 image importer plugin.
class ObjImporter
OBJ importer plugin.
class OpenExrImporter new in Git master
OpenEXR importer plugin.
class OpenGexImporter
OpenGEX importer.
class PngImporter
PNG importer plugin.
class PrimitiveImporter new in 2020.06
Primitive importer plugin.
class StanfordImporter
Stanford PLY importer plugin.
class StbImageImporter
Image importer plugin using stb_image.
class StlImporter new in 2020.06
STL importer plugin.
class TgaImporter
TGA importer plugin.
class TinyGltfImporter
TinyGltf importer plugin.

Public types

using Feature = ImporterFeature deprecated in 2020.06
Features supported by an importer.
using Features = ImporterFeatures deprecated in 2020.06
Set of features supported by an importer.

Public static functions

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

Constructors, destructors, conversion operators

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

Public functions

auto features() const -> ImporterFeatures
Features supported by this importer.
auto flags() const -> ImporterFlags new in 2020.06
Importer flags.
void setFlags(ImporterFlags flags) new in 2020.06
Set importer flags.
void addFlags(ImporterFlags flags) new in Git master
Add importer flags.
void clearFlags(ImporterFlags flags) new in Git master
Clear importer flags.
auto fileCallback() -> auto
File opening callback function.
auto fileCallbackUserData() const -> void*
File opening callback user data.
void setFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, void*) callback, void* userData = nullptr)
Set file opening callback.
template<class T>
void setFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, T&) callback, T& userData)
Set file opening callback.
auto isOpened() const -> bool
Whether any file is opened.
auto openData(Containers::ArrayView<const char> data) -> bool
Open raw data.
auto openState(const void* state, const std::string& filePath = {}) -> bool
Open already loaded state.
auto openFile(const std::string& filename) -> bool
Open a file.
void close()
Close currently opened file.
auto importerState() const -> const void*
Plugin-specific access to internal importer state.

Protected functions

void doOpenFile(const std::string& filename) virtual
Implementation for openFile()

Private functions

auto doFeatures() const -> ImporterFeatures pure virtual
Implementation for features()
void doSetFlags(ImporterFlags flags) virtual
Implementation for setFlags()
void doSetFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, void*) callback, void* userData) virtual
Implementation for setFileCallback()
auto doIsOpened() const -> bool pure virtual
Implementation for isOpened()
void doOpenData(Containers::ArrayView<const char> data) virtual
Implementation for openData()
void doOpenState(const void* state, const std::string& filePath) virtual
Implementation for openState()
void doClose() pure virtual
Implementation for close()
auto doDefaultScene() const -> Int virtual
Implementation for defaultScene()
auto doSceneCount() const -> UnsignedInt virtual
Implementation for sceneCount()
auto doSceneForName(const std::string& name) -> Int virtual
Implementation for sceneForName()
auto doSceneName(UnsignedInt id) -> std::string virtual
Implementation for sceneName()
auto doScene(UnsignedInt id) -> Containers::Optional<SceneData> virtual
Implementation for scene()
auto doAnimationCount() const -> UnsignedInt virtual
Implementation for animationCount()
auto doAnimationForName(const std::string& name) -> Int virtual
Implementation for animationForName()
auto doAnimationName(UnsignedInt id) -> std::string virtual
Implementation for animationName()
auto doAnimation(UnsignedInt id) -> Containers::Optional<AnimationData> virtual
Implementation for animation()
auto doLightCount() const -> UnsignedInt virtual
Implementation for lightCount()
auto doLightForName(const std::string& name) -> Int virtual
Implementation for lightForName()
auto doLightName(UnsignedInt id) -> std::string virtual
Implementation for lightName()
auto doLight(UnsignedInt id) -> Containers::Optional<LightData> virtual
Implementation for light()
auto doCameraCount() const -> UnsignedInt virtual
Implementation for cameraCount()
auto doCameraForName(const std::string& name) -> Int virtual
Implementation for cameraForName()
auto doCameraName(UnsignedInt id) -> std::string virtual
Implementation for cameraName()
auto doCamera(UnsignedInt id) -> Containers::Optional<CameraData> virtual
Implementation for camera()
auto doObject2DCount() const -> UnsignedInt virtual
Implementation for object2DCount()
auto doObject2DForName(const std::string& name) -> Int virtual
Implementation for object2DForName()
auto doObject2DName(UnsignedInt id) -> std::string virtual
Implementation for object2DName()
auto doObject2D(UnsignedInt id) -> Containers::Pointer<ObjectData2D> virtual
Implementation for object2D()
auto doObject3DCount() const -> UnsignedInt virtual
Implementation for object3DCount()
auto doObject3DForName(const std::string& name) -> Int virtual
Implementation for object3DForName()
auto doObject3DName(UnsignedInt id) -> std::string virtual
Implementation for object3DName()
auto doObject3D(UnsignedInt id) -> Containers::Pointer<ObjectData3D> virtual
Implementation for object3D()
auto doSkin2DCount() const -> UnsignedInt virtual new in Git master
Implementation for skin2DCount()
auto doSkin2DForName(const std::string& name) -> Int virtual new in Git master
Implementation for skin2DForName()
auto doSkin2DName(UnsignedInt id) -> std::string virtual new in Git master
Implementation for skin2DName()
auto doSkin2D(UnsignedInt id) -> Containers::Optional<SkinData2D> virtual new in Git master
Implementation for skin2D()
auto doSkin3DCount() const -> UnsignedInt virtual new in Git master
Implementation for skin3DCount()
auto doSkin3DForName(const std::string& name) -> Int virtual new in Git master
Implementation for skin3DForName()
auto doSkin3DName(UnsignedInt id) -> std::string virtual new in Git master
Implementation for skin3DName()
auto doSkin3D(UnsignedInt id) -> Containers::Optional<SkinData3D> virtual new in Git master
Implementation for skin3D()
auto doMeshCount() const -> UnsignedInt virtual new in 2020.06
Implementation for meshCount()
auto doMeshLevelCount(UnsignedInt id) -> UnsignedInt virtual new in 2020.06
Implementation for meshLevelCount()
auto doMeshForName(const std::string& name) -> Int virtual new in 2020.06
Implementation for meshForName()
auto doMeshName(UnsignedInt id) -> std::string virtual new in 2020.06
Implementation for meshName()
auto doMesh(UnsignedInt id, UnsignedInt level) -> Containers::Optional<MeshData> virtual new in 2020.06
Implementation for mesh()
auto doMeshAttributeForName(const std::string& name) -> MeshAttribute virtual new in 2020.06
Implementation for meshAttributeForName()
auto doMeshAttributeName(UnsignedShort name) -> std::string virtual new in 2020.06
Implementation for meshAttributeName()
auto doMesh2DCount() const -> UnsignedInt deprecated in 2020.06 virtual
Implementation for mesh2DCount()
auto doMesh2DForName(const std::string& name) -> Int deprecated in 2020.06 virtual
Implementation for mesh2DForName()
auto doMesh2DName(UnsignedInt id) -> std::string deprecated in 2020.06 virtual
Implementation for mesh2DName()
auto doMesh2D(UnsignedInt id) -> Containers::Optional<MeshData2D> deprecated in 2020.06 virtual
Implementation for mesh2D()
auto doMesh3DCount() const -> UnsignedInt deprecated in 2020.06 virtual
Implementation for mesh3DCount()
auto doMesh3DForName(const std::string& name) -> Int deprecated in 2020.06 virtual
Implementation for mesh3DForName()
auto doMesh3DName(UnsignedInt id) -> std::string deprecated in 2020.06 virtual
Implementation for mesh3DName()
auto doMesh3D(UnsignedInt id) -> Containers::Optional<MeshData3D> deprecated in 2020.06 virtual
Implementation for mesh3D()
auto doMaterialCount() const -> UnsignedInt virtual
Implementation for materialCount()
auto doMaterialForName(const std::string& name) -> Int virtual
Implementation for materialForName()
auto doMaterialName(UnsignedInt id) -> std::string virtual
Implementation for materialName()
auto doMaterial(UnsignedInt id) -> Containers::Optional<MaterialData> virtual
Implementation for material()
auto doTextureCount() const -> UnsignedInt virtual
Implementation for textureCount()
auto doTextureForName(const std::string& name) -> Int virtual
Implementation for textureForName()
auto doTextureName(UnsignedInt id) -> std::string virtual
Implementation for textureName()
auto doTexture(UnsignedInt id) -> Containers::Optional<TextureData> virtual
Implementation for texture()
auto doImage1DCount() const -> UnsignedInt virtual
Implementation for image1DCount()
auto doImage1DLevelCount(UnsignedInt id) -> UnsignedInt virtual new in 2020.06
Implementation for image1DLevelCount()
auto doImage1DForName(const std::string& name) -> Int virtual
Implementation for image1DForName()
auto doImage1DName(UnsignedInt id) -> std::string virtual
Implementation for image1DName()
auto doImage1D(UnsignedInt id, UnsignedInt level) -> Containers::Optional<ImageData1D> virtual
Implementation for image1D()
auto doImage2DCount() const -> UnsignedInt virtual
Implementation for image2DCount()
auto doImage2DLevelCount(UnsignedInt id) -> UnsignedInt virtual new in 2020.06
Implementation for image2DLevelCount()
auto doImage2DForName(const std::string& name) -> Int virtual
Implementation for image2DForName()
auto doImage2DName(UnsignedInt id) -> std::string virtual
Implementation for image2DName()
auto doImage2D(UnsignedInt id, UnsignedInt level) -> Containers::Optional<ImageData2D> virtual
Implementation for image2D()
auto doImage3DCount() const -> UnsignedInt virtual
Implementation for image3DCount()
auto doImage3DLevelCount(UnsignedInt id) -> UnsignedInt virtual new in 2020.06
Implementation for image3DLevelCount()
auto doImage3DForName(const std::string& name) -> Int virtual
Implementation for image3DForName()
auto doImage3DName(UnsignedInt id) -> std::string virtual
Implementation for image3DName()
auto doImage3D(UnsignedInt id, UnsignedInt level) -> Containers::Optional<ImageData3D> virtual
Implementation for image3D()
auto doImporterState() const -> const void* virtual
Implementation for importerState()

Data accessors

Each function tuple provides access to given data.

auto defaultScene() const -> Int
Default scene.
auto sceneCount() const -> UnsignedInt
Scene count.
auto sceneForName(const std::string& name) -> Int
Scene for given name.
auto sceneName(UnsignedInt id) -> std::string
Scene name.
auto scene(UnsignedInt id) -> Containers::Optional<SceneData>
Scene.
auto scene(const std::string& name) -> Containers::Optional<SceneData> new in 2020.06
Scene for given name.
auto animationCount() const -> UnsignedInt
Animation count.
auto animationForName(const std::string& name) -> Int
Animation for given name.
auto animationName(UnsignedInt id) -> std::string
Animation name.
auto animation(UnsignedInt id) -> Containers::Optional<AnimationData>
Animation.
auto animation(const std::string& name) -> Containers::Optional<AnimationData> new in 2020.06
Animation for given name.
auto lightCount() const -> UnsignedInt
Light count.
auto lightForName(const std::string& name) -> Int
Light for given name.
auto lightName(UnsignedInt id) -> std::string
Light name.
auto light(UnsignedInt id) -> Containers::Optional<LightData>
Light.
auto light(const std::string& name) -> Containers::Optional<LightData> new in 2020.06
Light for given name.
auto cameraCount() const -> UnsignedInt
Camera count.
auto cameraForName(const std::string& name) -> Int
Camera for given name.
auto cameraName(UnsignedInt id) -> std::string
Camera name.
auto camera(UnsignedInt id) -> Containers::Optional<CameraData>
Camera.
auto camera(const std::string& name) -> Containers::Optional<CameraData> new in 2020.06
Camera for given name.
auto object2DCount() const -> UnsignedInt
Two-dimensional object count.
auto object2DForName(const std::string& name) -> Int
Two-dimensional object for given name.
auto object2DName(UnsignedInt id) -> std::string
Two-dimensional object name.
auto object2D(UnsignedInt id) -> Containers::Pointer<ObjectData2D>
Two-dimensional object.
auto object2D(const std::string& name) -> Containers::Pointer<ObjectData2D> new in 2020.06
Two-dimensional object for given name.
auto object3DCount() const -> UnsignedInt
Three-dimensional object count.
auto object3DForName(const std::string& name) -> Int
Three-dimensional object for given name.
auto object3DName(UnsignedInt id) -> std::string
Three-dimensional object name.
auto object3D(UnsignedInt id) -> Containers::Pointer<ObjectData3D>
Three-dimensional object.
auto object3D(const std::string& name) -> Containers::Pointer<ObjectData3D> new in 2020.06
Three-dimensional object for given name.
auto skin2DCount() const -> UnsignedInt new in Git master
Two-dimensional skin count.
auto skin2DForName(const std::string& name) -> Int new in Git master
Two-dimensional skin for given name.
auto skin2DName(UnsignedInt id) -> std::string new in Git master
Two-dimensional skin name.
auto skin2D(UnsignedInt id) -> Containers::Optional<SkinData2D> new in Git master
Two-dimensional skin.
auto skin2D(const std::string& name) -> Containers::Optional<SkinData2D> new in Git master
Two-dimensional skin for given name.
auto skin3DCount() const -> UnsignedInt new in Git master
Three-dimensional skin count.
auto skin3DForName(const std::string& name) -> Int new in Git master
Three-dimensional skin for given name.
auto skin3DName(UnsignedInt id) -> std::string new in Git master
Three-dimensional skin name.
auto skin3D(UnsignedInt id) -> Containers::Optional<SkinData3D> new in Git master
Three-dimensional skin.
auto skin3D(const std::string& name) -> Containers::Optional<SkinData3D> new in Git master
Three-dimensional object for given name.
auto meshCount() const -> UnsignedInt new in 2020.06
Mesh count.
auto meshLevelCount(UnsignedInt id) -> UnsignedInt new in 2020.06
Mesh level count.
auto meshForName(const std::string& name) -> Int new in 2020.06
Mesh for given name.
auto meshName(UnsignedInt id) -> std::string new in 2020.06
Mesh name.
auto mesh(UnsignedInt id, UnsignedInt level = 0) -> Containers::Optional<MeshData> new in 2020.06
Mesh.
auto mesh(const std::string& name, UnsignedInt level = 0) -> Containers::Optional<MeshData> new in 2020.06
Mesh for given name.
auto meshAttributeForName(const std::string& name) -> MeshAttribute new in 2020.06
Mesh attribute for given name.
auto meshAttributeName(MeshAttribute name) -> std::string new in 2020.06
String name for given custom mesh attribute.
auto mesh2DCount() const -> UnsignedInt deprecated in 2020.06
Two-dimensional mesh count.
auto mesh2DForName(const std::string& name) -> Int deprecated in 2020.06
Two-dimensional mesh ID for given name.
auto mesh2DName(UnsignedInt id) -> std::string deprecated in 2020.06
Two-dimensional mesh name.
auto mesh2D(UnsignedInt id) -> Containers::Optional<MeshData2D> deprecated in 2020.06
Two-dimensional mesh.
auto mesh3DCount() const -> UnsignedInt deprecated in 2020.06
Three-dimensional mesh count.
auto mesh3DForName(const std::string& name) -> Int deprecated in 2020.06
Three-dimensional mesh ID for given name.
auto mesh3DName(UnsignedInt id) -> std::string deprecated in 2020.06
Three-dimensional mesh name.
auto mesh3D(UnsignedInt id) -> Containers::Optional<MeshData3D> deprecated in 2020.06
Three-dimensional mesh.
auto materialCount() const -> UnsignedInt
Material count.
auto materialForName(const std::string& name) -> Int
Material for given name.
auto materialName(UnsignedInt id) -> std::string
Material name.
auto material(UnsignedInt id) -> Containers::Optional<MaterialData>
Material.
auto material(const std::string& name) -> Containers::Optional<MaterialData> new in 2020.06
Material for given name.
auto textureCount() const -> UnsignedInt
Texture count.
auto textureForName(const std::string& name) -> Int
Texture for given name.
auto textureName(UnsignedInt id) -> std::string
Texture name.
auto texture(UnsignedInt id) -> Containers::Optional<TextureData>
Texture.
auto texture(const std::string& name) -> Containers::Optional<TextureData> new in 2020.06
Texture for given name.
auto image1DCount() const -> UnsignedInt
One-dimensional image count.
auto image1DLevelCount(UnsignedInt id) -> UnsignedInt new in 2020.06
One-dimensional image mip level count.
auto image1DForName(const std::string& name) -> Int
One-dimensional image for given name.
auto image1DName(UnsignedInt id) -> std::string
One-dimensional image name.
auto image1D(UnsignedInt id, UnsignedInt level = 0) -> Containers::Optional<ImageData1D>
One-dimensional image.
auto image1D(const std::string& name, UnsignedInt level = 0) -> Containers::Optional<ImageData1D> new in 2020.06
One-dimensional image for given name.
auto image2DCount() const -> UnsignedInt
Two-dimensional image count.
auto image2DLevelCount(UnsignedInt id) -> UnsignedInt new in 2020.06
Two-dimensional image mip level count.
auto image2DForName(const std::string& name) -> Int
Two-dimensional image for given name.
auto image2DName(UnsignedInt id) -> std::string
Two-dimensional image name.
auto image2D(UnsignedInt id, UnsignedInt level = 0) -> Containers::Optional<ImageData2D>
Two-dimensional image.
auto image2D(const std::string& name, UnsignedInt level = 0) -> Containers::Optional<ImageData2D> new in 2020.06
Two-dimensional image for given name.
auto image3DCount() const -> UnsignedInt
Three-dimensional image count.
auto image3DLevelCount(UnsignedInt id) -> UnsignedInt new in 2020.06
Three-dimensional image mip level count.
auto image3DForName(const std::string& name) -> Int
Three-dimensional image for given name.
auto image3DName(UnsignedInt id) -> std::string
Three-dimensional image name.
auto image3D(UnsignedInt id, UnsignedInt level = 0) -> Containers::Optional<ImageData3D>
Three-dimensional image.
auto image3D(const std::string& name, UnsignedInt level = 0) -> Containers::Optional<ImageData3D> new in 2020.06
Three-dimensional image for given name.

Typedef documentation

typedef ImporterFeature Magnum::Trade::AbstractImporter::Feature

Features supported by an importer.

typedef ImporterFeatures Magnum::Trade::AbstractImporter::Features

Set of features supported by an importer.

Function documentation

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

Plugin interface.

"cz.mosra.magnum.Trade.AbstractImporter/0.3.3"

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

Plugin search paths.

Looks into magnum/importers/ or magnum-d/importers/ 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::AbstractImporter::setFlags(ImporterFlags flags) new in 2020.06

Set importer flags.

It's expected that this function is called before a file is opened. Some flags can be set only if the importer supports particular features, see documentation of each ImporterFlag 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-imageconverter, magnum-sceneconverter and magnum-player.

void Magnum::Trade::AbstractImporter::addFlags(ImporterFlags flags) new in Git master

Add importer flags.

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

void Magnum::Trade::AbstractImporter::clearFlags(ImporterFlags flags) new in Git master

Clear importer flags.

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

auto Magnum::Trade::AbstractImporter::fileCallback()

File opening callback function.

void* Magnum::Trade::AbstractImporter::fileCallbackUserData() const

File opening callback user data.

void Magnum::Trade::AbstractImporter::setFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, void*) callback, void* userData = nullptr)

Set file opening callback.

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

In case the importer doesn't support ImporterFeature::FileCallback but supports at least ImporterFeature::OpenData, a file opened through openFile() will be internally loaded through the provided callback and then passed to openData(). First the file is loaded with InputFileCallbackPolicy::LoadTemporary passed to the callback, then the returned memory view is passed to openData() (sidestepping the potential openFile() implementation of that particular importer) and after that the callback is called again with InputFileCallbackPolicy::Close because the semantics of openData() don't require the data to be alive after. In case you need a different behavior, use openData() directly.

In case callback is nullptr, the current callback (if any) is reset. This function expects that the importer supports either ImporterFeature::FileCallback or ImporterFeature::OpenData. If an importer supports neither, callbacks can't be used.

It's expected that this function is called before a file is opened. It's also expected that the loaded data are kept in scope for as long as the importer needs them, based on the value of InputFileCallbackPolicy. Documentation of particular importers provides more information about the expected callback behavior.

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

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

template<class T>
void Magnum::Trade::AbstractImporter::setFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, T&) callback, T& userData)

Set file opening callback.

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

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

bool Magnum::Trade::AbstractImporter::openData(Containers::ArrayView<const char> data)

Open raw data.

Closes previous file, if it was opened, and tries to open given raw data. Available only if ImporterFeature::OpenData is supported. Returns true on success, false otherwise. The data is not expected to be alive after the function exits.

bool Magnum::Trade::AbstractImporter::openState(const void* state, const std::string& filePath = {})

Open already loaded state.

Parameters
state Pointer to importer-specific state
filePath Base file directory for opening external data like textures and materials.

Closes previous file, if it was opened, and tries to open given state. Available only if ImporterFeature::OpenState is supported. Returns true on success, false otherwise.

See documentation of a particular plugin for more information about type and contents of the state parameter.

bool Magnum::Trade::AbstractImporter::openFile(const std::string& filename)

Open a file.

Closes previous file, if it was opened, and tries to open given file. Returns true on success, false otherwise. If file loading callbacks are set via setFileCallback() and ImporterFeature::OpenData is supported, this function uses the callback to load the file and passes the memory view to openData() instead. See setFileCallback() for more information.

void Magnum::Trade::AbstractImporter::close()

Close currently opened file.

On particular implementations an explicit call to this function may result in freed memory. This call is also done automatically when the importer gets destructed or when another file is opened.

const void* Magnum::Trade::AbstractImporter::importerState() const

Plugin-specific access to internal importer state.

The importer might provide access to its internal data structures for currently opened document through this function. See documentation of a particular plugin for more information about returned type and contents. Returns nullptr by default. Expects that a file is opened.

void Magnum::Trade::AbstractImporter::doOpenFile(const std::string& filename) virtual protected

Implementation for openFile()

If ImporterFeature::OpenData is supported, default implementation opens the file and calls doOpenData() with its contents. It is allowed to call this function from your doOpenFile() implementation — in particular, this implementation will also correctly handle callbacks set through setFileCallback().

This function is not called when file callbacks are set through setFileCallback() and ImporterFeature::FileCallback is not supported — instead, file is loaded though the callback and data passed through to doOpenData().

void Magnum::Trade::AbstractImporter::doSetFlags(ImporterFlags flags) virtual private

Implementation for setFlags()

Useful when the importer 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 openFile() and others, where the user is expected to do error handling anyway.

void Magnum::Trade::AbstractImporter::doSetFileCallback(Containers::Optional<Containers::ArrayView<const char>>(*)(const std::string&, InputFileCallbackPolicy, void*) callback, void* userData) virtual private

Implementation for setFileCallback()

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

Int Magnum::Trade::AbstractImporter::doDefaultScene() const virtual private

Implementation for defaultScene()

Default implementation returns -1. This function isn't expected to fail — if an import error occus (for example because the default scene index is out of bounds), it should be handled already during file opening.

UnsignedInt Magnum::Trade::AbstractImporter::doSceneCount() const virtual private

Implementation for sceneCount()

Default implementation returns 0. This function isn't expected to fail — if an import error occus, it should be handled preferably during doScene() (with correct scene count reported), and if not possible, already during file opening.

Int Magnum::Trade::AbstractImporter::doSceneForName(const std::string& name) virtual private

Implementation for sceneForName()

Default implementation returns -1.

std::string Magnum::Trade::AbstractImporter::doSceneName(UnsignedInt id) virtual private

Implementation for sceneName()

Default implementation returns an empty string.

UnsignedInt Magnum::Trade::AbstractImporter::doAnimationCount() const virtual private

Implementation for animationCount()

Default implementation returns 0. This function isn't expected to fail — if an import error occus, it should be handled preferably during doAnimation() (with correct animation count reported), and if not possible, already during file opening.

Int Magnum::Trade::AbstractImporter::doAnimationForName(const std::string& name) virtual private

Implementation for animationForName()

Default implementation returns -1.

std::string Magnum::Trade::AbstractImporter::doAnimationName(UnsignedInt id) virtual private

Implementation for animationName()

Default implementation returns an empty string.

UnsignedInt Magnum::Trade::AbstractImporter::doLightCount() const virtual private

Implementation for lightCount()

Default implementation returns 0. This function isn't expected to fail — if an import error occus, it should be handled preferably during doLight() (with correct light count reported), and if not possible, already during file opening.

Int Magnum::Trade::AbstractImporter::doLightForName(const std::string& name) virtual private

Implementation for lightForName()

Default implementation returns -1.

std::string Magnum::Trade::AbstractImporter::doLightName(UnsignedInt id) virtual private

Implementation for lightName()

Default implementation returns an empty string.

UnsignedInt Magnum::Trade::AbstractImporter::doCameraCount() const virtual private

Implementation for cameraCount()

Default implementation returns 0. This function isn't expected to fail — if an import error occus, it should be handled preferably during doCamera() (with correct camera count reported), and if not possible, already during file opening.

Int Magnum::Trade::AbstractImporter::doCameraForName(const std::string& name) virtual private

Implementation for cameraForName()

Default implementation returns -1.

std::string Magnum::Trade::AbstractImporter::doCameraName(UnsignedInt id) virtual private

Implementation for cameraName()

Default implementation returns an empty string.

UnsignedInt Magnum::Trade::AbstractImporter::doObject2DCount() const virtual private

Implementation for object2DCount()

Default implementation returns 0. This function isn't expected to fail — if an import error occus, it should be handled preferably during doObject2D() (with correct object count reported), and if not possible, already during file opening.

Int Magnum::Trade::AbstractImporter::doObject2DForName(const std::string& name) virtual private

Implementation for object2DForName()

Default implementation returns -1.

std::string Magnum::Trade::AbstractImporter::doObject2DName(UnsignedInt id) virtual private

Implementation for object2DName()

Default implementation returns an empty string.

UnsignedInt Magnum::Trade::AbstractImporter::doObject3DCount() const virtual private

Implementation for object3DCount()

Default implementation returns 0. This function isn't expected to fail — if an import error occus, it should be handled preferably during doObject3D() (with correct object count reported), and if not possible, already during file opening.

Int Magnum::Trade::AbstractImporter::doObject3DForName(const std::string& name) virtual private

Implementation for object3DForName()

Default implementation returns -1.

std::string Magnum::Trade::AbstractImporter::doObject3DName(UnsignedInt id) virtual private

Implementation for object3DName()

Default implementation returns an empty string.

UnsignedInt Magnum::Trade::AbstractImporter::doSkin2DCount() const virtual private new in Git master

Implementation for skin2DCount()

Default implementation returns 0. This function isn't expected to fail — if an import error occus, it should be handled preferably during doSkin2D() (with correct skin count reported), and if not possible, already during file opening.

Int Magnum::Trade::AbstractImporter::doSkin2DForName(const std::string& name) virtual private new in Git master

Implementation for skin2DForName()

Default implementation returns -1.

std::string Magnum::Trade::AbstractImporter::doSkin2DName(UnsignedInt id) virtual private new in Git master

Implementation for skin2DName()

Default implementation returns an empty string.

UnsignedInt Magnum::Trade::AbstractImporter::doSkin3DCount() const virtual private new in Git master

Implementation for skin3DCount()

Default implementation returns 0. This function isn't expected to fail — if an import error occus, it should be handled preferably during doSkin3D() (with correct skin count reported), and if not possible, already during file opening.

Int Magnum::Trade::AbstractImporter::doSkin3DForName(const std::string& name) virtual private new in Git master

Implementation for skin3DForName()

Default implementation returns -1.

std::string Magnum::Trade::AbstractImporter::doSkin3DName(UnsignedInt id) virtual private new in Git master

Implementation for skin3DName()

Default implementation returns an empty string.

UnsignedInt Magnum::Trade::AbstractImporter::doMeshCount() const virtual private new in 2020.06

Implementation for meshCount()

Default implementation returns 0. This function isn't expected to fail — if an import error occus, it should be handled preferably during doMesh() (with correct mesh count reported), and if not possible, already during file opening.

UnsignedInt Magnum::Trade::AbstractImporter::doMeshLevelCount(UnsignedInt id) virtual private new in 2020.06

Implementation for meshLevelCount()

Default implementation returns 1. Similarly to all other *Count() functions, this function isn't expected to fail — if an import error occus, this function should return 1 and the error state should be returned from mesh() instead.

Deliberately not const to allow plugins cache decoded data.

Int Magnum::Trade::AbstractImporter::doMeshForName(const std::string& name) virtual private new in 2020.06

Implementation for meshForName()

Default implementation returns -1.

std::string Magnum::Trade::AbstractImporter::doMeshName(UnsignedInt id) virtual private new in 2020.06

Implementation for meshName()

Default implementation returns an empty string.

MeshAttribute Magnum::Trade::AbstractImporter::doMeshAttributeForName(const std::string& name) virtual private new in 2020.06

Implementation for meshAttributeForName()

Default implementation returns an invalid (zero) value.

std::string Magnum::Trade::AbstractImporter::doMeshAttributeName(UnsignedShort name) virtual private new in 2020.06

Implementation for meshAttributeName()

Receives the custom ID extracted via meshAttributeCustom(MeshAttribute). Default implementation returns an empty string.

UnsignedInt Magnum::Trade::AbstractImporter::doMesh2DCount() const virtual private

Implementation for mesh2DCount()

Default implementation returns 0. There weren't any importers in existence known to implement 2D mesh import, so unlike doMesh3DCount() this function doesn't delegate to doMeshCount().

Int Magnum::Trade::AbstractImporter::doMesh2DForName(const std::string& name) virtual private

Implementation for mesh2DForName()

Default implementation returns -1. There weren't any importers in existence known to implement 2D mesh import, so unlike doMesh3DForName() this function doesn't delegate to doMeshForName().

std::string Magnum::Trade::AbstractImporter::doMesh2DName(UnsignedInt id) virtual private

Implementation for mesh2DName()

Default implementation returns an empty string. There weren't any importers in existence known to implement 2D mesh import, so unlike doMesh3DName() this function doesn't delegate to doMeshName().

Containers::Optional<MeshData2D> Magnum::Trade::AbstractImporter::doMesh2D(UnsignedInt id) virtual private

Implementation for mesh2D()

There weren't any importers in existence known to implement 2D mesh import, so unlike doMesh3D() this function doesn't delegate to doMesh().

UnsignedInt Magnum::Trade::AbstractImporter::doMesh3DCount() const virtual private

Implementation for mesh3DCount()

Default implementation returns doMeshCount() for backwards compatibility.

Int Magnum::Trade::AbstractImporter::doMesh3DForName(const std::string& name) virtual private

Implementation for mesh3DForName()

Default implementation returns doMeshForName() for backwards compatibility.

std::string Magnum::Trade::AbstractImporter::doMesh3DName(UnsignedInt id) virtual private

Implementation for mesh3DName()

Default implementation returns doMeshName() for backwards compatibility.

Containers::Optional<MeshData3D> Magnum::Trade::AbstractImporter::doMesh3D(UnsignedInt id) virtual private

Implementation for mesh3D()

Default implementation returns doMesh() converted to MeshData3D for backwards compatibility.

UnsignedInt Magnum::Trade::AbstractImporter::doMaterialCount() const virtual private

Implementation for materialCount()

Default implementation returns 0. This function isn't expected to fail — if an import error occus, it should be handled preferably during doMaterial() (with correct material count reported), and if not possible, already during file opening.

Int Magnum::Trade::AbstractImporter::doMaterialForName(const std::string& name) virtual private

Implementation for materialForName()

Default implementation returns -1.

std::string Magnum::Trade::AbstractImporter::doMaterialName(UnsignedInt id) virtual private

Implementation for materialName()

Default implementation returns an empty string.

UnsignedInt Magnum::Trade::AbstractImporter::doTextureCount() const virtual private

Implementation for textureCount()

Default implementation returns 0. This function isn't expected to fail — if an import error occus, it should be handled preferably during doTexture() (with correct texture count reported), and if not possible, already during file opening.

Int Magnum::Trade::AbstractImporter::doTextureForName(const std::string& name) virtual private

Implementation for textureForName()

Default implementation returns -1.

std::string Magnum::Trade::AbstractImporter::doTextureName(UnsignedInt id) virtual private

Implementation for textureName()

Default implementation returns an empty string.

UnsignedInt Magnum::Trade::AbstractImporter::doImage1DCount() const virtual private

Implementation for image1DCount()

Default implementation returns 0. This function isn't expected to fail — if an import error occus, it should be handled preferably during doImage1D() (with correct image count reported), and if not possible, already during file opening.

UnsignedInt Magnum::Trade::AbstractImporter::doImage1DLevelCount(UnsignedInt id) virtual private new in 2020.06

Implementation for image1DLevelCount()

Default implementation returns 1. See doImage2DLevelCount() for expected implementation behavior.

Int Magnum::Trade::AbstractImporter::doImage1DForName(const std::string& name) virtual private

Implementation for image1DForName()

Default implementation returns -1.

std::string Magnum::Trade::AbstractImporter::doImage1DName(UnsignedInt id) virtual private

Implementation for image1DName()

Default implementation returns an empty string.

UnsignedInt Magnum::Trade::AbstractImporter::doImage2DCount() const virtual private

Implementation for image2DCount()

Default implementation returns 0. This function isn't expected to fail — if an import error occus, it should be handled preferably during doImage2D() (with correct image count reported), and if not possible, already during file opening.

UnsignedInt Magnum::Trade::AbstractImporter::doImage2DLevelCount(UnsignedInt id) virtual private new in 2020.06

Implementation for image2DLevelCount()

Default implementation returns 1. Similarly to all other *Count() functions, this function isn't expected to fail — if an import error occus, this function should return 1 and the error state should be returned from image2D() instead; if a file really contains a zero-level image, the implementation should exclude that image from doImage2DCount() instead of returning 0 here.

Deliberately not const to allow plugins cache decoded data.

Int Magnum::Trade::AbstractImporter::doImage2DForName(const std::string& name) virtual private

Implementation for image2DForName()

Default implementation returns -1.

std::string Magnum::Trade::AbstractImporter::doImage2DName(UnsignedInt id) virtual private

Implementation for image2DName()

Default implementation returns an empty string.

UnsignedInt Magnum::Trade::AbstractImporter::doImage3DCount() const virtual private

Implementation for image3DCount()

Default implementation returns 0. This function isn't expected to fail — if an import error occus, it should be handled preferably during doImage3D() (with correct image count reported), and if not possible, already during file opening.

UnsignedInt Magnum::Trade::AbstractImporter::doImage3DLevelCount(UnsignedInt id) virtual private new in 2020.06

Implementation for image3DLevelCount()

Default implementation returns 1. See doImage2DLevelCount() for expected implementation behavior.

Int Magnum::Trade::AbstractImporter::doImage3DForName(const std::string& name) virtual private

Implementation for image3DForName()

Default implementation returns -1.

std::string Magnum::Trade::AbstractImporter::doImage3DName(UnsignedInt id) virtual private

Implementation for image3DName()

Default implementation returns an empty string.

Int Magnum::Trade::AbstractImporter::defaultScene() const

Default scene.

Returns Scene ID from range [0, sceneCount()) or -1 if there's no default scene

Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::sceneCount() const

Scene count.

Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::sceneForName(const std::string& name)

Scene for given name.

Returns Scene ID from range [0, sceneCount()) or -1 if no scene for given name exists

Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::sceneName(UnsignedInt id)

Scene name.

Parameters
id Scene ID, from range [0, sceneCount()).

If the scene has no name or the importer doesn't support scene names, returns an empty string. Expects that a file is opened.

Containers::Optional<SceneData> Magnum::Trade::AbstractImporter::scene(UnsignedInt id)

Scene.

Parameters
id Scene ID, from range [0, sceneCount()).

Returns given scene or Containers::NullOpt if import failed. Expects that a file is opened.

Containers::Optional<SceneData> Magnum::Trade::AbstractImporter::scene(const std::string& name) new in 2020.06

Scene for given name.

A convenience API combining sceneForName() and scene(UnsignedInt). If sceneForName() returns -1, prints an error message and returns Containers::NullOpt, otherwise propagates the result from scene(UnsignedInt). Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::animationCount() const

Animation count.

Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::animationForName(const std::string& name)

Animation for given name.

Returns Animation ID from range [0, animationCount()) or -1 if no animation for given name exists

Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::animationName(UnsignedInt id)

Animation name.

Parameters
id Animation ID, from range [0, animationCount()).

Expects that a file is opened. If the animation has no name or the importer doesn't support animation names, returns an empty string.

Containers::Optional<AnimationData> Magnum::Trade::AbstractImporter::animation(UnsignedInt id)

Animation.

Parameters
id Animation ID, from range [0, animationCount()).

Returns given animation or Containers::NullOpt if importing failed. Expects that a file is opened.

Containers::Optional<AnimationData> Magnum::Trade::AbstractImporter::animation(const std::string& name) new in 2020.06

Animation for given name.

A convenience API combining animationForName() and animation(UnsignedInt). If animationForName() returns -1, prints an error message and returns Containers::NullOpt, otherwise propagates the result from animation(UnsignedInt). Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::lightCount() const

Light count.

Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::lightForName(const std::string& name)

Light for given name.

Returns Light ID from range [0, lightCount()) or -1 if no light for given name exists

Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::lightName(UnsignedInt id)

Light name.

Parameters
id Light ID, from range [0, lightCount()).

Expects that a file is opened. If the light has no name or the importer doesn't support light names, returns an empty string.

Containers::Optional<LightData> Magnum::Trade::AbstractImporter::light(UnsignedInt id)

Light.

Parameters
id Light ID, from range [0, lightCount()).

Returns given light or Containers::NullOpt if importing failed. Expects that a file is opened.

Containers::Optional<LightData> Magnum::Trade::AbstractImporter::light(const std::string& name) new in 2020.06

Light for given name.

A convenience API combining lightForName() and light(UnsignedInt). If lightForName() returns -1, prints an error message and returns Containers::NullOpt, otherwise propagates the result from light(UnsignedInt). Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::cameraCount() const

Camera count.

Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::cameraForName(const std::string& name)

Camera for given name.

Returns Camera ID from range [0, cameraCount()) or -1 if no camera for given name exists

Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::cameraName(UnsignedInt id)

Camera name.

Parameters
id Camera ID, from range [0, cameraCount()).

Expects that a file is opened. If the camera has no name or the importer doesn't support camera names, returns an empty string.

Containers::Optional<CameraData> Magnum::Trade::AbstractImporter::camera(UnsignedInt id)

Camera.

Parameters
id Camera ID, from range [0, cameraCount()).

Returns given camera or Containers::NullOpt if importing failed. Expects that a file is opened.

Containers::Optional<CameraData> Magnum::Trade::AbstractImporter::camera(const std::string& name) new in 2020.06

Camera for given name.

A convenience API combining cameraForName() and camera(UnsignedInt). If cameraForName() returns -1, prints an error message and returns Containers::NullOpt, otherwise propagates the result from camera(UnsignedInt). Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::object2DCount() const

Two-dimensional object count.

Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::object2DForName(const std::string& name)

Two-dimensional object for given name.

Returns Object ID from range [0, object2DCount()) or -1 if no object for given name exists

Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::object2DName(UnsignedInt id)

Two-dimensional object name.

Parameters
id Object ID, from range [0, object2DCount()).

Expects that a file is opened. If the object has no name or the importer doesn't support object names, returns an empty string.

Containers::Pointer<ObjectData2D> Magnum::Trade::AbstractImporter::object2D(UnsignedInt id)

Two-dimensional object.

Parameters
id Object ID, from range [0, object2DCount()).

Returns given object or nullptr if importing failed. Expects that a file is opened.

Containers::Pointer<ObjectData2D> Magnum::Trade::AbstractImporter::object2D(const std::string& name) new in 2020.06

Two-dimensional object for given name.

A convenience API combining object2DForName() and object2D(UnsignedInt). If object2DForName() returns -1, prints an error message and returns nullptr, otherwise propagates the result from object2D(UnsignedInt). Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::object3DCount() const

Three-dimensional object count.

Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::object3DForName(const std::string& name)

Three-dimensional object for given name.

Returns Object ID from range [0, object3DCount()) or -1 if no object for given name exists

Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::object3DName(UnsignedInt id)

Three-dimensional object name.

Parameters
id Object ID, from range [0, object3DCount()).

Expects that a file is opened. If the object has no name or the importer doesn't support object names, returns an empty string.

Containers::Pointer<ObjectData3D> Magnum::Trade::AbstractImporter::object3D(UnsignedInt id)

Three-dimensional object.

Parameters
id Object ID, from range [0, object3DCount()).

Returns given object or nullptr if importing failed. Expects that a file is opened.

Containers::Pointer<ObjectData3D> Magnum::Trade::AbstractImporter::object3D(const std::string& name) new in 2020.06

Three-dimensional object for given name.

A convenience API combining object3DForName() and object3D(UnsignedInt). If object3DForName() returns -1, prints an error message and returns nullptr, otherwise propagates the result from object3D(UnsignedInt). Expects that a file is opened.

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

Two-dimensional skin count.

Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::skin2DForName(const std::string& name) new in Git master

Two-dimensional skin for given name.

Returns Skin ID from range [0, skin2DCount()) or -1 if no skin for given name exists

Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::skin2DName(UnsignedInt id) new in Git master

Two-dimensional skin name.

Parameters
id Skin ID, from range [0, skin2DCount()).

If the skin has no name or the importer doesn't support skin names, returns an empty string. Expects that a file is opened.

Containers::Optional<SkinData2D> Magnum::Trade::AbstractImporter::skin2D(UnsignedInt id) new in Git master

Two-dimensional skin.

Parameters
id Skin ID, from range [0, skin2DCount()).

Returns given skin or Containers::NullOpt if importing failed. Expects that a file is opened.

Containers::Optional<SkinData2D> Magnum::Trade::AbstractImporter::skin2D(const std::string& name) new in Git master

Two-dimensional skin for given name.

A convenience API combining skin2DForName() and skin2D(UnsignedInt). If skin2DForName() returns -1, prints an error message and returns Containers::NullOpt, otherwise propagates the result from skin2D(UnsignedInt). Expects that a file is opened.

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

Three-dimensional skin count.

Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::skin3DForName(const std::string& name) new in Git master

Three-dimensional skin for given name.

Returns Skin ID from range [0, skin3DCount()) or -1 if no skin for given name exists

Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::skin3DName(UnsignedInt id) new in Git master

Three-dimensional skin name.

Parameters
id Skin ID, from range [0, skin3DCount()).

If the skin has no name or the importer doesn't support skin names, returns an empty string. Expects that a file is opened.

Containers::Optional<SkinData3D> Magnum::Trade::AbstractImporter::skin3D(UnsignedInt id) new in Git master

Three-dimensional skin.

Parameters
id Skin ID, from range [0, skin3DCount()).

Returns given skin or Containers::NullOpt if importing failed. Expects that a file is opened.

Containers::Optional<SkinData3D> Magnum::Trade::AbstractImporter::skin3D(const std::string& name) new in Git master

Three-dimensional object for given name.

A convenience API combining skin3DForName() and skin3D(UnsignedInt). If skin3DForName() returns -1, prints an error message and returns Containers::NullOpt, otherwise propagates the result from skin3D(UnsignedInt). Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::meshCount() const new in 2020.06

Mesh count.

Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::meshLevelCount(UnsignedInt id) new in 2020.06

Mesh level count.

Parameters
id Mesh ID, from range [0, meshCount()).

Always returns at least one level, import failures are deferred to mesh(). Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::meshForName(const std::string& name) new in 2020.06

Mesh for given name.

Returns Mesh ID from range [0, meshCount()) or -1 if no mesh for given name exists

Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::meshName(UnsignedInt id) new in 2020.06

Mesh name.

Parameters
id Mesh ID, from range [0, meshCount()).

If the mesh has no name or the importer doesn't support mesh names, returns an empty string. Expects that a file is opened.

Containers::Optional<MeshData> Magnum::Trade::AbstractImporter::mesh(UnsignedInt id, UnsignedInt level = 0) new in 2020.06

Mesh.

Parameters
id Mesh ID, from range [0, meshCount()).
level Mesh level, from range [0, meshLevelCount())

Returns given mesh or Containers::NullOpt if importing failed. The level parameter allows access to additional data and is largely left as importer-specific — for example allowing access to per-instance, per-face or per-edge data. Expects that a file is opened.

Containers::Optional<MeshData> Magnum::Trade::AbstractImporter::mesh(const std::string& name, UnsignedInt level = 0) new in 2020.06

Mesh for given name.

A convenience API combining meshForName() and mesh(UnsignedInt, UnsignedInt). If meshForName() returns -1, prints an error message and returns Containers::NullOpt, otherwise propagates the result from mesh(UnsignedInt, UnsignedInt). Expects that a file is opened.

MeshAttribute Magnum::Trade::AbstractImporter::meshAttributeForName(const std::string& name) new in 2020.06

Mesh attribute for given name.

If the name is not recognized, returns a zero (invalid) MeshAttribute, otherwise returns a custom mesh attribute. Note that the value returned by this function may depend on whether a file is opened or not and also be different for different files — see documentation of a particular importer for more information.

std::string Magnum::Trade::AbstractImporter::meshAttributeName(MeshAttribute name) new in 2020.06

String name for given custom mesh attribute.

Given a custom name returned by mesh() in a MeshData, returns a string identifier. If a string representation is not available or name is not recognized, returns an empty string. Expects that name is custom. Note that the value returned by this function may depend on whether a file is opened or not and also be different for different files — see documentation of a particular importer for more information.

UnsignedInt Magnum::Trade::AbstractImporter::mesh2DCount() const

Two-dimensional mesh count.

Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::mesh2DForName(const std::string& name)

Two-dimensional mesh ID for given name.

If no mesh for given name exists, returns -1. Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::mesh2DName(UnsignedInt id)

Two-dimensional mesh name.

Parameters
id Mesh ID, from range [0, mesh2DCount()).

Expects that a file is opened.

Containers::Optional<MeshData2D> Magnum::Trade::AbstractImporter::mesh2D(UnsignedInt id)

Two-dimensional mesh.

Parameters
id Mesh ID, from range [0, mesh2DCount()).

Returns given mesh or Containers::NullOpt if importing failed. Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::mesh3DCount() const

Three-dimensional mesh count.

Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::mesh3DForName(const std::string& name)

Three-dimensional mesh ID for given name.

If no mesh for given name exists, returns -1. Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::mesh3DName(UnsignedInt id)

Three-dimensional mesh name.

Parameters
id Mesh ID, from range [0, mesh3DCount()).

Expects that a file is opened.

Containers::Optional<MeshData3D> Magnum::Trade::AbstractImporter::mesh3D(UnsignedInt id)

Three-dimensional mesh.

Parameters
id Mesh ID, from range [0, mesh3DCount()).

Returns given mesh or Containers::NullOpt if importing failed. Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::materialCount() const

Material count.

Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::materialForName(const std::string& name)

Material for given name.

Returns Material ID from range [0, materialCount()) or -1 if no material for given name exists

Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::materialName(UnsignedInt id)

Material name.

Parameters
id Material ID, from range [0, materialCount()).

If the material has no name or the importer doesn't support material names, returns an empty string. Expects that a file is opened.

Containers::Optional<MaterialData> Magnum::Trade::AbstractImporter::material(UnsignedInt id)

Material.

Parameters
id Material ID, from range [0, materialCount()).

Returns given material or Containers::NullOpt if importing failed. Expects that a file is opened.

Containers::Optional<MaterialData> Magnum::Trade::AbstractImporter::material(const std::string& name) new in 2020.06

Material for given name.

A convenience API combining materialForName() and material(UnsignedInt). If materialForName() returns -1, prints an error message and returns Containers::NullOpt, otherwise propagates the result from material(UnsignedInt). Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::textureCount() const

Texture count.

Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::textureForName(const std::string& name)

Texture for given name.

Returns Texture ID from range [0, textureCount()) or -1 if no texture for given name exists

Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::textureName(UnsignedInt id)

Texture name.

Parameters
id Texture ID, from range [0, textureCount()).

If the texture has no name or the importer doesn't support texture names, returns an empty string. Expects that a file is opened.

Containers::Optional<TextureData> Magnum::Trade::AbstractImporter::texture(UnsignedInt id)

Texture.

Parameters
id Texture ID, from range [0, textureCount()).

Returns given texture or Containers::NullOpt if importing failed. Expects that a file is opened.

Containers::Optional<TextureData> Magnum::Trade::AbstractImporter::texture(const std::string& name) new in 2020.06

Texture for given name.

A convenience API combining textureForName() and texture(UnsignedInt). If textureForName() returns -1, prints an error message and returns Containers::NullOpt, otherwise propagates the result from texture(UnsignedInt). Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::image1DCount() const

One-dimensional image count.

Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::image1DLevelCount(UnsignedInt id) new in 2020.06

One-dimensional image mip level count.

Parameters
id Image ID, from range [0, image1DCount())

Always returns at least one level, import failures are deferred to image1D(). Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::image1DForName(const std::string& name)

One-dimensional image for given name.

Returns Image ID from range [0, image1DCount()) or -1 if no image for given name exists

Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::image1DName(UnsignedInt id)

One-dimensional image name.

Parameters
id Image ID, from range [0, image1DCount()).

If the image has no name or the importer doesn't support image names, returns an empty string. Expects that a file is opened.

Containers::Optional<ImageData1D> Magnum::Trade::AbstractImporter::image1D(UnsignedInt id, UnsignedInt level = 0)

One-dimensional image.

Parameters
id Image ID, from range [0, image1DCount()).
level Mip level, from range [0, image1DLevelCount())

Returns given image or Containers::NullOpt if importing failed. Expects that a file is opened.

Containers::Optional<ImageData1D> Magnum::Trade::AbstractImporter::image1D(const std::string& name, UnsignedInt level = 0) new in 2020.06

One-dimensional image for given name.

A convenience API combining image1DForName() and image1D(UnsignedInt, UnsignedInt). If image1DForName() returns -1, prints an error message and returns Containers::NullOpt, otherwise propagates the result from image1D(UnsignedInt, UnsignedInt). Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::image2DCount() const

Two-dimensional image count.

Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::image2DLevelCount(UnsignedInt id) new in 2020.06

Two-dimensional image mip level count.

Parameters
id Image ID, from range [0, image2DCount()).

Always returns at least one level, import failures are deferred to image2D(). Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::image2DForName(const std::string& name)

Two-dimensional image for given name.

Returns Image ID from range [0, image2DCount()) or -1 if no image for given name exists

Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::image2DName(UnsignedInt id)

Two-dimensional image name.

Parameters
id Image ID, from range [0, image2DCount()).

If the image has no name or the importer doesn't support image names, returns an empty string. Expects that a file is opened.

Containers::Optional<ImageData2D> Magnum::Trade::AbstractImporter::image2D(UnsignedInt id, UnsignedInt level = 0)

Two-dimensional image.

Parameters
id Image ID, from range [0, image2DCount()).
level Mip level, from range [0, image2DLevelCount())

Returns given image or Containers::NullOpt if importing failed. Expects that a file is opened.

Containers::Optional<ImageData2D> Magnum::Trade::AbstractImporter::image2D(const std::string& name, UnsignedInt level = 0) new in 2020.06

Two-dimensional image for given name.

A convenience API combining image2DForName() and image2D(UnsignedInt, UnsignedInt). If image2DForName() returns -1, prints an error message and returns Containers::NullOpt, otherwise propagates the result from image2D(UnsignedInt, UnsignedInt). Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::image3DCount() const

Three-dimensional image count.

Expects that a file is opened.

UnsignedInt Magnum::Trade::AbstractImporter::image3DLevelCount(UnsignedInt id) new in 2020.06

Three-dimensional image mip level count.

Parameters
id Image ID, from range [0, image3DCount())

Always returns at least one level, import failures are deferred to image3D(). Expects that a file is opened.

Int Magnum::Trade::AbstractImporter::image3DForName(const std::string& name)

Three-dimensional image for given name.

Returns Image ID from range [0, image3DCount()) or -1 if no image for given name exists

Expects that a file is opened.

std::string Magnum::Trade::AbstractImporter::image3DName(UnsignedInt id)

Three-dimensional image name.

Parameters
id Image ID, from range [0, image3DCount()).

If the image has no name or the importer doesn't support image names, returns an empty string. Expects that a file is opened.

Containers::Optional<ImageData3D> Magnum::Trade::AbstractImporter::image3D(UnsignedInt id, UnsignedInt level = 0)

Three-dimensional image.

Parameters
id Image ID, from range [0, image3DCount()).
level Mip level, from range [0, image3DLevelCount())

Returns given image or Containers::NullOpt if importing failed. Expects that a file is opened.

Containers::Optional<ImageData3D> Magnum::Trade::AbstractImporter::image3D(const std::string& name, UnsignedInt level = 0) new in 2020.06

Three-dimensional image for given name.

A convenience API combining image3DForName() and image3D(UnsignedInt, UnsignedInt). If image3DForName() returns -1, prints an error message and returns Containers::NullOpt, otherwise propagates the result from image3D(UnsignedInt, UnsignedInt). Expects that a file is opened.