Magnum::Trade::OpenGexImporter class
#include <MagnumPlugins/OpenGexImporter/OpenGexImporter.h>

OpenGEX importer.

Imports the OpenDDL-based OpenGEX format.

Supports importing of scene, object, camera, mesh, texture and image data.

Usage

This plugin depends on the Trade and OpenDdl libraries and the AnyImageImporter plugin. It is built if MAGNUM_WITH_OPENGEXIMPORTER is enabled when building Magnum Plugins. To use as a dynamic plugin, load "OpenGexImporter" via Corrade::PluginManager::Manager.

Additionally, if you're using Magnum as a CMake subproject, bundle the magnum-plugins repository and do the following:

set(MAGNUM_WITH_ANYIMAGEIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum EXCLUDE_FROM_ALL)

set(MAGNUM_WITH_OPENGEXIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

# So the dynamically loaded plugin gets built implicitly
add_dependencies(your-app MagnumPlugins::OpenGexImporter)

To use as a static plugin or as a dependency of another plugin with CMake, put FindMagnumPlugins.cmake into your modules/ directory, request the OpenGexImporter component of the MagnumPlugins package and link to the MagnumPlugins::OpenGexImporter target:

find_package(MagnumPlugins REQUIRED OpenGexImporter)

# ...
target_link_libraries(your-app PRIVATE MagnumPlugins::OpenGexImporter)

See Downloading and building plugins, Plugin usage with CMake, Loading and using plugins and File format support for more information.

Behavior and limitations

The plugin supports ImporterFeature::OpenData and ImporterFeature::FileCallback features. The importer fully loads the top-level file during initial import, meaning there is at most one InputFileCallbackPolicy::LoadTemporary callback followed by InputFileCallbackPolicy::Close and the data can freed right after the openData() / openFile() function exits. In case of images, the files are loaded on-demand inside image2D() calls with InputFileCallbackPolicy::LoadTemporary and InputFileCallbackPolicy::Close is emitted right after the file is fully read.

Import of animation data is not supported at the moment.
half data type results in parsing error.
On OpenGL ES, usage of double type and on WebGL additionally also usage of 64bit integer types results in parsing error.

While the importer doesn't recognize any ImporterFlag itself, all ImporterFlags are propagated to image importer plugins the importer delegates to.

Scene import

OpenGEX supports only a single scene and has no way to assign a scene name.
Imported scenes always have SceneMappingType::UnsignedInt, with SceneData::mappingBound() equal to objectCount(). The scene is always 3D.
All reported objects have a SceneField::Parent (of type SceneFieldType::Int), SceneField::ImporterState (of type SceneFieldType::Pointer, see Access to internal importer state below) and SceneField::Transformation (of type SceneFieldType::Matrix4x4). These three fields share the same object mapping with SceneFieldFlag::ImplicitMapping set.
OpenGEX supports separate TRS components for representing a node transformation, however it allows them to be in any order and repeat count. Which is, to be mild, an extremely annoying and mostly useless overcomplication. For this reason the transformations are always concatenated to a single matrix, without exposing any particular components.
Object-only transformations are not supported.
If the scene references meshes, a SceneField::Mesh (of type SceneFieldType::UnsignedInt) is present. If any of the referenced meshes have assigned materials, SceneField::MeshMaterial (of type SceneFieldType::Int) is present as well. Both have SceneFieldFlag::OrderedMapping set. Additional material references after the first one for given geometry node are ignored, thus a single node can only reference either a single mesh at most. See Mesh import and Material import for further details.
If the scene references cameras, a SceneField::Camera (of type SceneFieldType::UnsignedInt) is present, with SceneFieldFlag::OrderedMapping set. See Camera import for further details.
If the scene references lights, a SceneField::Light (of type SceneFieldType::UnsignedInt) is present, with SceneFieldFlag::OrderedMapping set. See Light import for further details.
An OpenGEX node can reference only either a single mesh, or a single camera, or a single light at most, the file format doesn't allow nodes with e.g. multiple cameras or a camera and a light.
Geometry node visibility, shadow and motion blur properties are ignored.

Camera import

Camera type is always CameraType::Perspective3D
Default FoV for cameras that don't have it specified is 35.0_degf
Default near and far plane for cameras that don't have it specified is 0.01f and 100.0f
Aspect ratio is ignored and hardcoded to 1.0f

Light import

Light attenuation properties are not yet supported.
Light textures are not yet supported.

Mesh import

Quads are not supported.
Additional mesh LoDs after the first one are ignored.
w coordinate for vertex positions and normals is ignored if present.
Positions and normals are always imported as VertexFormat::Vector3, texture coordinates as VertexFormat::Vector2. Positions and normals of a different component count than 3 and texture coordinates of a different component count than 2 are not supported. Only floats are supported, doubles not.
Indices are imported as either MeshIndexType::UnsignedByte, MeshIndexType::UnsignedShort or MeshIndexType::UnsignedInt. 64-bit indices are not supported.

The imported mesh always has at least one vertex attribute, but positions are not required to be present. Indices are optional as well.

Material import

Alpha mode is always MaterialAlphaMode::Opaque and alpha mask always 0.5f
Two-sided property is ignored, always set to false
All materials are imported as Trade::PhongMaterialData with ambient color always set to 0x000000ff_rgbaf.
emission, opacity and transparency attributes are not supported.
normal textures are not supported.

Texture import

Texture coordinate transformation is ignored.
Textures using other than the first coordinate set are not supported.
Texture type is always Trade::TextureType::Texture2D, wrapping is always SamplerWrapping::ClampToEdge, minification and magnification is SamplerFilter::Linear and mipmap selection is SamplerMipmap::Linear.
If multiple textures have the same image filename string, given image is present in the image list only once. Note that only a simple string comparison is used without any path normalization.

Access to internal importer state

Generic importer for OpenDDL files is implemented in the OpenDdl::Document class available as part of this plugin and access to it is provided through importer-specific data accessors:

Calling importerState() returns pointer to parsed OpenDdl::Document
Calling *importerState() on data class instances returned from this importer return pointer to OpenDdl::Structure of these types:
- MaterialData::importerState() returns OpenGex::Material structure
- CameraData::importerState() returns OpenGex::CameraObject structure
- TextureData::importerState() returns OpenGex::Texture structure
- MeshData::importerState() returns OpenGex::GeometryObject structure
- SceneData objects have a SceneField::ImporterState returning an OpenGex::Node, OpenGex::BoneNode, OpenGex::GeometryNode, OpenGex::CameraNode or OpenGex::LightNode structure

Base classes

class AbstractImporter: Base for importer plugins.

Constructors, destructors, conversion operators

OpenGexImporter() explicit: Default constructor.
OpenGexImporter(PluginManager::Manager<AbstractImporter>& manager) explicit: Constructor.
OpenGexImporter(PluginManager::AbstractManager& manager, const Containers::StringView& plugin) explicit: Plugin manager constructor.

Public functions

auto importerState() const -> const OpenDdl::Document*: Importer state.

Function documentation

Magnum::Trade::OpenGexImporter::OpenGexImporter() explicit

Default constructor.

In case you want to open images, use OpenGexImporter(PluginManager::Manager<AbstractImporter>&) instead.

Magnum::Trade::OpenGexImporter::OpenGexImporter(PluginManager::Manager<AbstractImporter>& manager) explicit

Constructor.

The plugin needs access to plugin manager for importing images.

const OpenDdl::Document* Magnum::Trade::OpenGexImporter::importerState() const

Importer state.