Magnum::Trade::GltfSceneConverter class new in Git master
#include <MagnumPlugins/GltfSceneConverter/GltfSceneConverter.h>

glTF converter plugin

Exports full scenes to either *.gltf files with an external *.bin buffer or to a self-contained *.glb. You can use GltfImporter to import scenes in this format.

Usage

This plugin depends on the Trade library and is built if WITH_GLTFSCENECONVERTER is enabled when building Magnum Plugins. To use as a dynamic plugin, load "GltfSceneConverter" via Corrade::PluginManager::Manager.

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

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

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

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

find_package(MagnumPlugins REQUIRED GltfSceneConverter)

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

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

Behavior and limitations

  • At the moment, alignment rules for the *.glb layout are not respected.

Mesh export

Image and texture export

  • Images are converted using a converter specified in the imageConverter configuration option, propagating flags set via setFlags() and all configuration options from the [imageConverter] group to it. An AbstractImageConverter plugin manager has to be registered using PluginManager::Manager::registerExternalManager() for image conversion to work.
  • By default, images are saved as external files for a *.gltf output and embedded into the buffer for a *.glb output. This behavior can be overriden using the bundleImages configuration option on a per-image basis.
  • Core glTF supports only JPEG and PNG file formats. Basis-encoded KTX2 files can be saved with the KHR_texture_basisu extension by setting imageConverter=BasisKtxImageConverter. The MSFT_texture_dds and EXT_texture_webp extensions are not exported because there's currently no image converter capable of saving DDS and WebP files. Other formats (such as TGA, OpenEXR...) are not supported by the spec but GltfImporter supports them and they can be exported if the strict configuration option is disabled. Such images are then referenced directly without any extension.
  • If the experimentalKhrTextureKtx configuration option is enabled, generic KTX2 images can be saved with the proposed KHR_texture_ktx extension.
  • Image and texture names, if passed, are saved into the file. Additionally the buffer views referenced by embedded images will be annotated with image ID and name if the accessorNames configuration option is enabled.
  • The texture is required to only be added after all images it references
  • At the moment, there's no support for exporting multi-level images even though the KTX2 container is capable of storing these.
  • At the moment, texture sampler properties are not exported.

2D array texture export

If the experimentalKhrTextureKtx configuration option is enabled, the plugin supports also 3D images and 2D array textures using a proposed KHR_texture_ktx extension.

  • Only KTX2 images are supported for 3D, i.e. with either imageConverter=KtxImageConverter or imageConverter=BasisKtxImageConverter. They need to have ImageFlag3D::Array set.
  • Use a TextureType::Texture2DArray texture to reference the 3D images. Due to how the extension is designed, the resulting glTF then has the texture duplicated for each layer of the image; GltfImporter then undoes the duplication again on import.
  • Due to how the extension is designed, the presence of the texture referencing the 3D image is essential for properly recognizing the image as 3D on import. Without it, the image gets recognized as 2D and the import will subsequently fail due to the image file not actually being 2D.
  • A material referencing a 2D array texture implicitly uses the first (0) layer. Use the *TextureLayer attributes (such as MaterialAttribute::BaseColorTextureLayer for a MaterialAttribute::BaseColorTexture) to specify a layer. The layer index has to be smaller than the Z dimension of the image.

Material export

Scene export

  • Only 3D scenes are supported
  • Only objects with a SceneField::Parent entry are exported, all other objects are ignored with a warning. This also implies that object IDs are not preserved, as otherwise the glTF would contain a lot of empty unreferenced node objects.
  • The SceneField::Parent hierarchy is required to be acyclical
  • To satisfy glTF requirements, if both SceneField::Transformation and at least one of Translation, Rotation and Scaling is present, only the TRS component(s) are saved into the file and not the matrix, assuming the transformation matrix is equivalent to them
  • Object and scene names, if passed, are saved into the file
  • The scene is required to only be added after all meshes and materials it references
  • At the moment, only SceneField::Parent, Transformation, Translation, Rotation, Scaling, Mesh and MeshMaterial is exported, other fields are ignored with a warning
  • At the moment, duplicate fields including multiple mesh assignments are ignored with a warning
  • At the moment, only a single scene can be exported. As a consequence, information about the default scene is redundant and thus not written.

Plugin-specific config

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

[configuration]
# Copyright and generator name, written into the asset object. If empty, no
# value is written. Add one or more extensionUsed and/or extensionRequired
# values to populate the extension usage and requirement arrays.
copyright=
generator=Magnum GltfSceneConverter
#extensionUsed=
#extensionRequired=

# Whether to write a *.gltf or a *.glb file. If empty, detected automatically
# based on filename extension, conversion to data defaults to a binary file. If
# a text file is selected for conversion to data, converting anything that
# involves binary buffers will currently fail.
binary=

# Name all buffer views and accessors to see what they belong to. Useful for
# debugging purposes. The option can be also enabled just for a particular
# add() operation and then disabled again to reduce the impact on file sizes.
accessorNames=false

# Allow only strictly valid glTF files. Disallows:
#   - meshes with zero vertices, zero indices or zero attributes
#   - image formats that don't have a corresponding glTF extension
# Magnum will be still able to open files with this option unset, but other
# libraries may fail. The option can be also disabled just for a particular
# add() operation and then enabled again to not loosen up validation for
# everything at once.
strict=true

# 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 beginning a file, changing it during
# conversion will have undefined behavior.
textureCoordinateYFlipInMaterial=false

# The non-standard MeshAttribute::ObjectId is by default recognized under this
# name. Change if you want to export it under a different identifier.
objectIdAttribute=_OBJECT_ID

# Implicitly, only material attributes that differ from glTF material defaults
# are written. Enable to unconditionally save all attributes present in given
# MaterialData. Attributes that are not present in given MaterialData are saved
# only if the Magnum default differs from the glTF default and this option
# doesn't affect them.
keepMaterialDefaults=false

# Whether to bundle images in buffers. If empty, images are bundled for *.glb
# files and saved externally for *.gltf files. Can be set differently for each
# add() operation.
bundleImages=

# Experimental KHR_texture_ktx support. The extension is not stabilized yet,
# thus the implementation may not reflect latest changes to the proposal.
experimentalKhrTextureKtx=false

# Image converter to use. Can be set differently for each add() operation in
# order to export different images in different formats. Formats that don't
# have any corresponding glTF image extension are allowed only with the strict
# option unset.
imageConverter=PngImageConverter

# Configuration options to propagate to the image converter
[configuration/imageConverter]

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

Base classes

class AbstractSceneConverter new in 2020.06
Base for scene converter plugins.

Constructors, destructors, conversion operators

GltfSceneConverter(PluginManager::AbstractManager& manager, const Containers::StringView& plugin) explicit
Plugin manager constructor.