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

TinyGltf importer plugin.

Imports glTF (*.gltf) and binary glTF (*.glb) files using the TinyGLTF library.

This plugin provides the GltfImporter plugin.

Usage

This plugin depends on the Trade library and the AnyImageImporter plugin and is built if MAGNUM_WITH_TINYGLTFIMPORTER is enabled when building Magnum Plugins. To use as a dynamic plugin, load "TinyGltfImporter" 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_TINYGLTFIMPORTER ON CACHE BOOL "" FORCE)
add_subdirectory(magnum-plugins EXCLUDE_FROM_ALL)

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

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

find_package(MagnumPlugins REQUIRED TinyGltfImporter)

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

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 TinyGLTF library loads everything during initial import, meaning all external file loading callbacks are called with InputFileCallbackPolicy::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 InputFileCallbackPolicy::LoadTemporary and InputFileCallbackPolicy::Close is emitted right after the file is fully read.

Percent-encoded external file paths are not decoded before loading files. If you need to support those paths, you can intercept and decode them with a file callback.

The content of the global extensionsRequired array is ignored. If a glTF file requires an unknown extension, the import will most likely succeed, but some things might be missing or not get imported correctly.

Import of morph data is not supported at the moment.

Scene import

Animation and skin 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 configuration option. 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 configuration option. This doesn't affect spline-interpolated rotation tracks.
  • Skin skeleton property is not imported, but you can retrieve it via SkinData::importerState() — see Access to internal importer state for more information
  • 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.

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

Mesh import

Custom and unrecognized vertex attributes of allowed types are present in the imported meshes as well. Their mapping to/from a string can be queried using meshAttributeName() and meshAttributeForName(). Attributes with unsupported types (such as non-normalized integer matrices) cause the import to fail.

Material import

Texture and image import

  • Texture type is always Trade::TextureType::Texture2D, as glTF doesn't support anything else
  • Z coordinate of Trade::TextureData::wrapping() is always SamplerWrapping::Repeat, as glTF doesn't support 3D textures

  • glTF leaves the defaults of sampler properties to the application, the following defaults have been chosen for this importer:

  • The importer supports the following extensions for image types not defined in the core glTF 2.0 specification: KHR_texture_basisu for Khronos Texture 2.0 images (*.ktx2) with Basis Universal supercompression and the original provisional GOOGLE_texture_basis extension for referencing plain Basis Universal files (*.basis). There was no formal specification of the extension but the use is like below, equivalently to Basis own glTF example:

    {
    ...
    "textures": [
        {
            "extensions": {
                "GOOGLE_texture_basis": {
                    "source": 0
                }
            }
        }
    ],
    "images": [
        {
            "mimeType": "image/x-basis",
            "uri": "texture.basis"
        }
    ],
    "extensionsUsed": [
        "GOOGLE_texture_basis"
    ],
    "extensionsRequired": [
        "GOOGLE_texture_basis"
    ]
}

    While the mimeType field isn't checked by the importer, embedded data URIs for both extensions need to have their prefix set to data:application/octet-stream. TinyGLTF has a whitelist for data URI detection that doesn't know image/ktx2 or image/x-basis and would treat the URI as a filename otherwise:

    {
    ...
    "images": [
        {
            "mimeType": "image/ktx2",
            "uri": "data:application/octet-stream;base64,..."
        }
    ]
}

Plugin-specific configuration

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. For more information see
# https://blender.stackexchange.com/q/5689 and
# https://github.com/KhronosGroup/glTF-Blender-Exporter/pull/166.
mergeAnimationClips=false

# Perform Y-flip for texture coordinates in a material texture transform. By
# default texture coordinates are Y-flipped directly in the mesh data to
# avoid the need to supply texture transformation matrix to a shader,
# enabling this will cause all texture coordinate data to be unchanged and
# instead all materials will have a Y-flipping texture transformation
# present. Note that this flag has to be enabled before opening a file,
# changing it during import will have undefined behavior.
textureCoordinateYFlipInMaterial=false

# The non-standard MeshAttribute::ObjectId is by default recognized under
# this name. Change if your file uses a different identifier.
objectIdAttribute=_OBJECT_ID

# Provide basic Phong material attributes even for PBR materials in order to
# be compatible with PhongMaterialData workflows from version 2020.06 and
# before. This option will eventually become disabled by default.
phongMaterialFallback=true

See Editing plugin-specific configuration for more information and an example showing how to edit the configuration values.

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 is 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 Containers::StringView& 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.