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

TinyGltf importer plugin.

Contents

Imports glTF and binary glTF using the TinyGLTF library.

This plugin depends on the Trade library and is built if WITH_TINYGLTFIMPORTER is enabled when building Magnum Plugins. To use as a dynamic plugin, you need to load the "TinyGltfImporter" plugin from MAGNUM_PLUGINS_IMPORTER_DIR. To use as a static plugin or as a dependency of another plugin with CMake, you need to request the TinyGltfImporter component of the MagnumPlugins package and link to the MagnumPlugins::TinyGltfImporter target. See Downloading and building plugins, Plugin usage with CMake and Loading and using plugins for more information.

This plugin provides GltfImporter and GlbImporter plugins.

Behavior and limitations

The plugin supports Feature::OpenData and Feature::FileCallback features. The tiny_gltf library loads everything during initial import, meaning all external file loading callbacks are called with ImporterFileCallbackPolicy::LoadTemporary and the resources can be safely freed right after the openData() / openFile() function exits. In case of images, the files are loaded on-demand inside image2D() calls with ImporterFileCallbackPolicy::LoadTemporary and ImporterFileCallbackPolicy::Close is emitted right after the file is fully read.

Import of skeleton, skin and morph data is not supported at the moment.

Animation import

  • Linear quaternion rotation tracks are postprocessed in order to make it possible to use the faster Math::lerp() / Math::slerp() functions instead of Math::lerpShortestPath() / Math::slerpShortestPath(). Can be disabled per-animation with the optimizeQuaternionShortestPath option, see below. This doesn't affect spline-interpolated rotation tracks.
  • If linear quaternion rotation tracks are not normalized, the importer prints a warning and normalizes them. Can be disabled per-animation with the normalizeQuaternions option, see below. This doesn't affect spline-interpolated rotation tracks.
  • Skinning and morph targets are not supported
  • Animation tracks are always imported with Animation::Extrapolation::Constant, because glTF doesn't support anything else
  • It's possible to request all animation clips to be merged into one using the mergeAnimationClips option in order to for example preserve cinematic animations when using the Blender glTF exporter (as it otherwise outputs a separate clip for each object). When this option is enabled, animationCount() always report either 0 or 1 and the merged animation has no name. With this option enabled, however, it can happen that multiple conflicting tracks affecting the same node are merged in the same clip, causing the animation to misbehave.

Scene and object import

  • If no "scene" property is present and the file contains at least one scene, defaultScene() returns 0 instead of -1. According to the glTF 2.0 specification the importer is free to not render anything, but the suggested behavior would break even some official sample models.
  • In case object transformation is set via separate translation/rotation/scaling properties in the source file, ObjectData3D is created with ObjectFlag3D::HasTranslationRotationScaling and these separate properties accessible
  • If object rotation quaternion is not normalized, the importer prints a warning and normalizes it. Can be disabled per-object with the normalizeQuaternions option, see below.

Camera import

  • Cameras in glTF are specified with vertical FoV and vertical:horizontal aspect ratio, these values are recalculated for horizontal FoV and horizontal:vertical aspect ratio as is common in Magnum

Light import

  • Currently, the importer only supports the historical KHR_lights_cmn extension, supported by the original Khronos Blender glTF Exporter.
    • Light properties besides light type are not imported.
    • Light intensity is not yet supported due to glTF extension draft state.

Mesh import

  • Meshes with interleaved vertex data/buffer views are not supported.
  • Multi-primitive meshes are loaded as follows:
    • The mesh3DCount() query returns a number of all primitives, not meshes
    • Each multi-primitive mesh is split into a sequence of MeshData3D instances following each other
    • mesh3DForName() points to the first mesh in given sequence and mesh3DName() returns the same name for all meshes in given sequence
    • The object3DCount() query returns a number of all nodes extended with number of extra nodes for each additional mesh primitive
    • Each node referencing a multi-primitive mesh is split into a sequence of MeshObjectData3D instances following each other; the extra nodes being a direct and immediate children of the first one with an identity transformation
    • object3DForName() points to the first object containing the first primitive, object3DName() returns the same name for all objects in given sequence
    • AnimationData instances returned by animation() have their AnimationData::trackTarget() values patched to account for the extra nodes, always pointing to the first object in the sequence and thus indirectly affecting transformations of the extra nodes represented as its children

Material import

  • Subset of all material specs is currently imported as PhongMaterialData
  • Ambient color is always 0x000000_rgbf (never a texture)
  • For the Metallic/Roughness material spec (in core, default):
    • The baseColorTexture field is used for diffuse texture, if present. Otherwise, baseColorFactor is used for diffuse color, if present. Otherwise, 0xffffff_rgbf is used.
    • Specular color is always 0xffffff_rgbf (never a texture)
    • Shininess is always 1.0f
  • For the Specular/Glossiness material spec (KHR_materials_pbrSpecularGlossiness extension):
    • The diffuseTexture field is used for diffuse texture, if present. Otherwise, diffuseFactor is used for diffuse color, if present. Otherwise, 0xffffff_rgbf is used.
    • The specularGlossinessTexture field is used for a specular texture, if present (note that only the RGB channels should be used and the alpha channel — containing glossiness — should be ignored). Otherwise, specularFactor is used for specular color, if present. Otherwise, 0xffffff_rgbf is used.
    • Shininess is always 1.0f
  • For the Blinn/Phong material spec (draft KHR_materials_cmnBlinnPhong extension):
    • The diffuseTexture field is used for diffuse texture, if present. Otherwise, diffuseFactor is used for diffuse color, if present. Otherwise, 0xffffff_rgbf is used.
    • The specularShininessTexture field is used for specular texture, if present (note that only the RGB channels should be used and the alpha channel — containing snininess — should be ignored). Otherwise, specularFactor is used for diffuse color, if present. Otherwise, 0xffffff_rgbf is used.
    • The snininessFactor field is used for snininess, if present. Otherwise 1.0f is used.

Texture import

Plugin-specific config

It's possible to tune various output options through configuration(). See below for all options and their default values.

[configuration]

# Optimize imported linearly-interpolated quaternion animation tracks to
# ensure shortest path is always chosen. This can be controlled separately for
# each animation import.
optimizeQuaternionShortestPath=true

# Normalize transformation quaternions and linearly-interpolated quaternion
# animation tracks, if they are not already. Note that spline-interpolated
# quaternion animation tracks are not patched. This can be controlled
# separately for each object/animation import.
normalizeQuaternions=true

# Merge all animations into a single clip. Useful for preserving cinematic
# animations when using the Blender glTF exporter, as it exports animation of
# every object as a separate clip. See https://blender.stackexchange.com/q/5689
# and https://github.com/KhronosGroup/glTF-Blender-Exporter/pull/166 for more
# information.
mergeAnimationClips=false

Access to internal importer state

Access to the underlying TinyGLTF structures it is provided through importer-specific data accessors:

The TinyGLTF header is installed alsongside the plugin and accessible like this:

#include <MagnumExternal/TinyGLTF/tiny_gltf.h>

Base classes

class AbstractImporter
Base for importer plugins.

Constructors, destructors, conversion operators

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

Public functions

auto importerState() const -> const tinygltf::Model*
Importer state.

Function documentation

Magnum::Trade::TinyGltfImporter::TinyGltfImporter() explicit

Default constructor.

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

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

Constructor.

The plugin needs access to plugin manager for importing images.

const tinygltf::Model* Magnum::Trade::TinyGltfImporter::importerState() const

Importer state.

See class documentation for more information.