Magnum::Trade::TinyGltfImporter class

#include <MagnumPlugins/TinyGltfImporter/TinyGltfImporter.h>

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.

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 configuration option.

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

• The importer supports the KHR_lights_punctual extension

Mesh import

• Indices are imported as either MeshIndexType::UnsignedByte, MeshIndexType::UnsignedShort or MeshIndexType::UnsignedInt
• Positions are imported as VertexFormat::Vector3, VertexFormat::Vector3ub, VertexFormat::Vector3b, VertexFormat::Vector3us, VertexFormat::Vector3s, VertexFormat::Vector3ubNormalized, VertexFormat::Vector3bNormalized, VertexFormat::Vector3usNormalized or VertexFormat::Vector3sNormalized (which includes the additional types specified by KHR_mesh_quantization)
• Normals, if any, are imported as VertexFormat::Vector3, VertexFormat::Vector3bNormalized or VertexFormat::Vector3sNormalized
• Texture coordinates are imported as VertexFormat::Vector3, VertexFormat::Vector3ub, VertexFormat::Vector3b, VertexFormat::Vector3us, VertexFormat::Vector3s, VertexFormat::Vector3ubNormalized, VertexFormat::Vector3bNormalized, VertexFormat::Vector3usNormalized or VertexFormat::Vector3sNormalized (which includes the additional types specified by KHR_mesh_quantization). The data are by default Y-flipped on import unless textureCoordinateYFlipInMaterial is either explicitly enabled, or if the file contains non-normalized integer or normalized signed integer texture coordinates (which can't easily be flipped). In that case texture coordinate data are kept as-is and materials provide a texture transformation that does the Y-flip instead.
• Colors are imported as VertexFormat::Vector3, VertexFormat::Vector4, VertexFormat::Vector3ubNormalized, VertexFormat::Vector4ubNormalized, VertexFormat::Vector3usNormalized or VertexFormat::Vector4usNormalized
• Joint IDs and weights for skinning are imported as custom vertex attributes named "JOINTS_0", "JOINTS_1", etc. and "WEIGHTS_0", "WEIGHTS_1", etc. Their mapping to/from a string can be queried using meshAttributeName() and meshAttributeForName(). Joint IDs are imported as VertexFormat::Vector4ub or VertexFormat::Vector4us. Joint weights are imported as VertexFormat::Vector4, VertexFormat::Vector4ubNormalized or VertexFormat::Vector4usNormalized.
• Per-vertex object ID attribute is imported as either VertexFormat::UnsignedInt, VertexFormat::UnsignedShort or VertexFormat::UnsignedByte. By default _OBJECT_ID is the recognized name, use the objectIdAttribute configuration option to change the identifier that's being looked for.
• Multi-primitive meshes are loaded as follows, consistently with the behavior of AssimpImporter:
  • The meshCount() query returns a number of all primitives, not meshes
  • Each multi-primitive mesh is split into a sequence of MeshData instances following each other
  • meshForName() points to the first mesh in given sequence and meshName() 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
• Attribute-less meshes either with or without an index buffer are supported, however since glTF has no way of specifying vertex count for those, returned Trade::MeshData::vertexCount() is set to 0

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

• Builtin metallic/roughness material is imported always, setting MaterialType::PbrMetallicRoughness on the MaterialData. Unfortunately TinyGLTF doesn't provide a way to detect if metallic/roughness properties are actually present, so this type is set always.
• If the KHR_materials_pbrSpecularGlossiness extension is present, its properties are imported with MaterialType::PbrSpecularGlossiness present in material types.
• Additional normal, occlusion and emissive maps are imported, together with related properties
• If the KHR_materials_unlit extension is present, MaterialType::Flat is set in material types, replacing MaterialType::PbrMetallicRoughness or MaterialType::PbrSpecularGlossiness.
• If the KHR_materials_clearcoat extension is present, MaterialType::PbrClearCoat is set in material types, and a new layer with clearcoat properties is added
• Custom texture coordinate sets as well as KHR_texture_transform properties are imported on all textures.
• If the on-by-default phongMaterialFallback configuration option is enabled, the importer provides a Phong fallback for backwards compatibility:
  • MaterialType::Phong is added to material types
  • Base color and base color texture along with custom texture coordinate set and transformation, if present, is exposed as a diffuse color and texture, unless already present together with specular color / texture from the specular/glossiness material
  • All other PhongMaterialData values are is kept at their defaults

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:

  • Minification/magnification/mipmap filter: SamplerFilter::Linear, SamplerMipmap::Linear
  • Wrapping (all axes): SamplerWrapping::Repeat

• 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,..."
          }
      ]
  }