Magnum::Trade::GltfImporter class new in Git master

#include <MagnumPlugins/GltfImporter/GltfImporter.h>

Scene import

• Imported scenes always have SceneMappingType::UnsignedInt and are always 3D. The objectCount() returns count of all nodes in the file, while SceneData::mappingBound() returns an upper bound on node IDs contained in a particular scene.
• Nodes that are not referenced by any scene are ignored.
• All objects contained in a scene have a SceneField::Parent (of type SceneFieldType::Int). Size of this field is the count of nodes contained in the scene. The mapping is unordered and may be sparse if the file contains multiple scenes or nodes not referenced by any scene.
• All nodes that contain transformation matrices or TRS components have a SceneField::Transformation (of type SceneFieldType::Matrix4x4). This field is not present if all such nodes have TRS components, in which a matrix is considered redundant. Nodes that don't have any transformation matrix nor a TRS component don't have this field assigned.
• If any node contains a translation, a SceneField::Translation (of type SceneFieldType::Vector3) is present; if any node contains a rotation, a SceneField::Rotation (of type SceneFieldType::Quaternion) is present; if any node contains a scaling, a SceneField::Scaling (of type SceneFieldType::Vector3) is present.
• 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. While a single node can only reference a single mesh at most, in case it references a multi-primitive mesh, it's represented as several SceneField::Mesh (and SceneField::MeshMaterial) assignments. See Mesh import and Material import for further details.
• If the scene references skins, a SceneField::Skin (of type SceneFieldType::UnsignedInt) is present. A single node can only reference one skin at most. See Animation and skin import for further details.
• If the scene references cameras, a SceneField::Camera (of type SceneFieldType::UnsignedInt) is present. A single node can only reference one camera at most. See Camera import for further details.
• If the scene references lights, a SceneField::Light (of type SceneFieldType::UnsignedInt) is present. A single node can only reference one light at most. See Light import for further details.
• If node rotation quaternion is not normalized, the importer prints a warning and normalizes it. Can be disabled per-object with the normalizeQuaternions configuration option.
• Node extras are imported as custom scene fields, with names exposed through sceneFieldName() / sceneFieldForName() right upon opening the file. The extras property has to be an object, otherwise it's ignored with a warning. Boolean values are imported as SceneFieldType::Bit, numeric values are implicitly imported as SceneFieldType::Float and the type can be overriden using the [customSceneFieldTypes] configuration group, string values are imported as SceneFieldType::StringOffset32. Homogeneous arrays with boolean, numeric and string values are imported as multiple values of the same field, same approach is taken if the extras property contains the same key multiple times. Objects are processed recursively, with field names for nested keys being separated with dots. Other value types, heterogeneous arrays and values that don't have a consistent type for given key across all nodes are ignored with a warning.
• SceneField::Mesh and SceneField::MeshMaterial fields are always marked with SceneFieldFlag::MultiEntry. No other builtin fields can have multiple entries for a single object. Node extras that were parsed from an array are also marked with SceneFieldFlag::MultiEntry in order to unambiguously distinguish them from non-array values.

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 configuration option. This doesn't affect spline-interpolated rotation tracks.
• Skin skeleton property is not imported
• Morph target animations 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

• 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 are imported as VertexFormat::Vector3, VertexFormat::Vector3bNormalized or VertexFormat::Vector3sNormalized
• Tangents are imported as VertexFormat::Vector4, VertexFormat::Vector4bNormalized or VertexFormat::Vector4sNormalized
• Texture coordinates are imported as VertexFormat::Vector2, VertexFormat::Vector2ub, VertexFormat::Vector2b, VertexFormat::Vector2us, VertexFormat::Vector2s, VertexFormat::Vector2ubNormalized, VertexFormat::Vector2bNormalized, VertexFormat::Vector2usNormalized or VertexFormat::Vector2sNormalized (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
• Skin joint IDs are imported as arrays of VertexFormat::UnsignedInt, VertexFormat::UnsignedByte or VertexFormat::UnsignedShort, skin weights then as arrays of VertexFormat::Float, VertexFormat::UnsignedByteNormalized or VertexFormat::UnsignedShortNormalized. The MeshData::attributeArraySize() is currently always 4, but is reserved to change (for example representing two consecutive sets as a single array of 8 items). For backwards compatibility, unless the compatibilitySkinningAttributes configuration option or MAGNUM_BUILD_DEPRECATED is disabled, these are also exposed as custom "JOINTS" and "WEIGHTS" attributes with VertexFormat::Vector4ub / VertexFormat::Vector4us and VertexFormat::Vector4 / VertexFormat::Vector4ubNormalized / VertexFormat::Vector4usNormalized (non-array) formats, respectively, with as many instances of these as needed to cover all array items. The compatibility attributes alias the builtin ones, i.e. point to the same memory, so their presence causes no extra overhead.
• 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.
• If a builtin attribute doesn't match the above-specified types, a message is printed to Warning and it's imported as a custom attribute instead, with its name available through meshAttributeName(). Such attributes are an invalid glTF but this allows the application to import them and fix in a postprocessing step. Enable the strict configuration option to fail the import in such cases instead.
• Multi-primitive meshes are split into individual meshes, nodes that reference a multi-primitive mesh have multiple SceneField::Mesh (and SceneField::MeshMaterial) entries in the imported SceneData.
• 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
• Morph targets, if present, have their attributes imported with Trade::MeshData::attributeMorphTargetId() set to index of the morph target. Non-sparse buffers aren't supported for those at the moment.

By default, the mesh import silently allows certain features that aren't strictly valid according to the glTF specification, such as 32-bit integer VertexFormat, because they're useful in general. Enable the strict configuration option to fail the import in such cases instead.

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

• If present, builtin metallic/roughness material is imported, setting MaterialType::PbrMetallicRoughness on the MaterialData.
• 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.
• Unrecognized material extensions are imported as custom layers with a # prefix. Extension properties are imported with their raw names and types, the following of which are supported:
  • MaterialAttributeType::String
  • MaterialAttributeType::Bool
  • All numbers as MaterialAttributeType::Float to avoid inconsistency with different glTF exporters. The only exception are texture indices and coordinate sets inside textureInfo objects, which get imported as MaterialAttributeType::UnsignedInt, consistently with types of builtin *Texture and *TextureCoordinates MaterialAttribute entries.
  • Number arrays as MaterialAttributeType::Vector2 / MaterialAttributeType::Vector3 / MaterialAttributeType::Vector4. Empty arrays, arrays of size 5 or higher as well as arrays containing anything that isn't a number are ignored.
  • textureInfo objects, including all attributes handled for regular textures. Texture attributes are prefixed by the name of the object: e.g. if an extension has a someTexture property, the texture index, matrix, coordinate set and scale would be imported as someTexture, someTextureMatrix, someTextureCoordinates and someTextureScale, consistently with builtin texture-related MaterialAttribute names. Non-texture object types are ignored. If you handle any of these custom material extensions, it may make sense to enable the ignoreRequiredExtensions configuration option.
• Extras metadata is imported into the base material layer. The extras property has to be an object, otherwise it's ignored with a warning. Type support is the same as for unrecognized material extensions, except for textureInfo objects — contrary to glTF material extensions, where sub-objects can be assumed to contain texture info, the extras can contain just anything.
• 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 Trade::TextureType::Texture2D. If the experimentalKhrTextureKtx configuration option is enabled, it can be also Trade::TextureType::Texture2DArray, as described below.
• 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: MSFT_texture_dds for DirectDraw Surface images (*.dds), EXT_texture_webp for WebP images (*.webp), KHR_texture_basisu for Khronos Texture 2.0 images (*.ktx2) with Basis Universal supercompression, as well as 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"
      ]
  }

  The MIME type (if one exists) is ignored by the importer. Delegation to the correct importer alias happens via AnyImageImporter which uses the file extension or buffer content to determine the image type.

• If a texture contains and extension together with a fallback source, or multiple extensions, the image referenced by the first recognized extension appearing in the file will be picked, others ignored.