Class GltfImport

Loads a glTF's content, converts it to Unity resources and is able to feed it to an IInstantiator for instantiation.

Inheritance

object

GltfImport

Implements

IGltfReadable

IMaterialProvider

IMaterialsVariantsProvider

IGltfAccessors

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Unity.Cloud.Gltfast

Assembly: Unity.Cloud.Gltfast.dll

Syntax

[MovedFrom(true, "GLTFast", "glTFast", null)]
public class GltfImport : IGltfReadable, IMaterialProvider, IMaterialsVariantsProvider, IGltfAccessors, IDisposable

Constructors

GltfImport(IDownloadProvider, IDeferAgent, IMaterialGenerator, ICodeLogger)

Constructs a GltfImport instance with injectable customization objects.

Declaration

public GltfImport(IDownloadProvider downloadProvider = null, IDeferAgent deferAgent = null, IMaterialGenerator materialGenerator = null, ICodeLogger logger = null)

Parameters

Type	Name	Description
IDownloadProvider	downloadProvider	Provides file access or download customization
IDeferAgent	deferAgent	Provides custom update loop behavior for better frame rate control
IMaterialGenerator	materialGenerator	Provides custom glTF to Unity material conversion
ICodeLogger	logger	Custom logger for reporting messages. Defaults to the shared Instance (writes to Unity's Console) when null is passed. Pass Instance (or new NullLogger()) to suppress all output.

Fields

defaultMaterial

Required for Editor import only to preserve default/fallback materials

Declaration

public Material defaultMaterial

Field Value

Type	Description
Material

Properties

DefaultSceneIndex

Default scene index

Declaration

public int? DefaultSceneIndex { get; }

Property Value

Type	Description
int?

DeferAgent

Defer agent used by this glTF import instance.

Declaration

public IDeferAgent DeferAgent { get; }

Property Value

Type	Description
IDeferAgent

LoadingDone

True, when loading has finished and glTF can be instantiated

Declaration

public bool LoadingDone { get; }

Property Value

Type	Description
bool

LoadingError

True if an error happened during glTF loading

Declaration

public bool LoadingError { get; }

Property Value

Type	Description
bool

Logger

Logger used by this glTF import instance.

Declaration

public ICodeLogger Logger { get; }

Property Value

Type	Description
ICodeLogger

MaterialCount

Number of materials

Declaration

public int MaterialCount { get; }

Property Value

Type	Description
int

MaterialsVariantsCount

Number of materials variants.

Declaration

public int MaterialsVariantsCount { get; }

Property Value

Type	Description
int

See Also

https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_materials_variants

Meshes

Allows accessing all imported meshes.

Declaration

public IReadOnlyCollection<Mesh> Meshes { get; }

Property Value

Type	Description
IReadOnlyCollection<Mesh>

Root

Main glTF data structure

Declaration

public Root Root { get; protected set; }

Property Value

Type	Description
Root

SceneCount

Number of scenes

Declaration

public int SceneCount { get; }

Property Value

Type	Description
int

TextureCount

Number of textures

Declaration

public int TextureCount { get; }

Property Value

Type	Description
int

See Also

GetTexture(int)

Methods

AddImportAddonInstance<T>(T)

Adds an import add-on instance. To be called before any loading is initiated.

Declaration

public void AddImportAddonInstance<T>(T importInstance) where T : ImportAddonInstance

Parameters

Type	Name	Description
T	importInstance	The import instance to add.

Type Parameters

Name	Description
T	Type of the import instance

Dispose()

Frees up memory by disposing all sub assets. There can be no instantiation or other element access afterwards.

Declaration

public void Dispose()

GetAccessorData<T>(int)

Provides an accessors typed data.

Declaration

public NativeArray<T>.ReadOnly GetAccessorData<T>(int accessorIndex) where T : unmanaged

Parameters

Type	Name	Description
int	accessorIndex	glTF accessor index.

Returns

Type	Description
NativeArray<T>.ReadOnly	The requested data or a non-initialized readonly native array if the request couldn't be handled.

Type Parameters

Name	Description
T	Accessor member type.

GetAnimationClips()

Returns all imported animation clips

Declaration

public AnimationClip[] GetAnimationClips()

Returns

Type	Description
AnimationClip[]	All imported animation clips

GetBindPoses(int)

Returns an array of inverse bone matrices representing a skin's bind pose suitable for use with UnityEngine.Mesh.bindposes by glTF skin index.

Declaration

public Matrix4x4[] GetBindPoses(int skinId)

Parameters

Type	Name	Description
int	skinId	glTF skin index

Returns

Type	Description
Matrix4x4[]	Corresponding bind poses

GetDefaultMaterial()

Returns a fallback material to be used when no material was assigned (provided by the IMaterialGenerator)

Declaration

public Material GetDefaultMaterial()

Returns

Type	Description
Material	Default material

GetDefaultMaterialAsync()

Returns a fallback material to be used when no material was assigned (provided by the IMaterialGenerator)

Declaration

public Task<Material> GetDefaultMaterialAsync()

Returns

Type	Description
Task<Material>	Default material

GetDefaultMaterialAsync(CancellationToken)

Returns a fallback material to be used when no material was assigned (provided by the IMaterialGenerator)

Declaration

public Task<Material> GetDefaultMaterialAsync(CancellationToken cancellationToken)

Parameters

Type	Name	Description
CancellationToken	cancellationToken	Token to submit cancellation requests. The default value is None.

Returns

Type	Description
Task<Material>	Default material

GetImportAddonInstance<T>()

Queries the import instance of a particular type.

Declaration

public T GetImportAddonInstance<T>() where T : ImportAddonInstance

Returns

Type	Description
T	The import instance that was previously added. False if there was none.

Type Parameters

Name	Description
T	Type of the import instance

GetMaterial(int)

Get a Unity Material by its glTF material index

Declaration

public Material GetMaterial(int index = 0)

Parameters

Type	Name	Description
int	index	glTF material index

Returns

Type	Description
Material	Corresponding Unity Material

GetMaterialAsync(int)

Get a Unity Material by its glTF material index

Declaration

public Task<Material> GetMaterialAsync(int index)

Parameters

Type	Name	Description
int	index	glTF material index

Returns

Type	Description
Task<Material>	Corresponding Unity Material

GetMaterialAsync(int, CancellationToken)

Get a Unity Material by its glTF material index

Declaration

public Task<Material> GetMaterialAsync(int index, CancellationToken cancellationToken)

Parameters

Type	Name	Description
int	index	glTF material index
CancellationToken	cancellationToken	Token to submit cancellation requests. The default value is None.

Returns

Type	Description
Task<Material>	Corresponding Unity Material

GetMaterialsVariantName(int)

Gets the name of a specific materials variant.

Declaration

public string GetMaterialsVariantName(int index)

Parameters

Type	Name	Description
int	index	Materials variant index.

Returns

Type	Description
string	Name of a materials variant.

See Also

https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_materials_variants

GetMaterialsVariantsSlots(int, int)

Returns the material slots that correspond to the given MeshResult's sub-meshes.

Declaration

public IMaterialsVariantsSlot[] GetMaterialsVariantsSlots(int meshIndex, int meshNumeration)

Parameters

Type	Name	Description
int	meshIndex	glTF mesh index.
int	meshNumeration	Per glTF mesh MeshResult numeration. A glTF mesh is converted into one or more MeshResults which are numbered consecutively.

Returns

Type	Description
IMaterialsVariantsSlot[]	Corresponding materials variants slots.

See Also

IMaterialsVariantsSlot

MeshResult

GetMesh(int, int)

Gets a specific Unity mesh of a glTF mesh. A single glTF mesh is converted into one or more Unity Meshes, so meshNumeration is required to depict which exact one.

Declaration

public Mesh GetMesh(int meshIndex, int meshNumeration)

Parameters

Type	Name	Description
int	meshIndex	glTF mesh index.
int	meshNumeration	Per glTF mesh MeshResult numeration. A glTF mesh is converted into one or more MeshResults which are numbered consecutively.

Returns

Type	Description
Mesh	An imported Unity mesh.

GetMeshCount(int)

Imported Unity Mesh count. A single glTF mesh is converted into one or more Unity Meshes.

Declaration

public int GetMeshCount(int meshIndex)

Parameters

Type	Name	Description
int	meshIndex	glTF mesh index.

Returns

Type	Description
int	Number of imported Unity meshes.

See Also

GetMeshes(int)

GetMeshes(int)

Iterates all imported Unity meshes of a glTF mesh.

Declaration

public IEnumerable<Mesh> GetMeshes(int meshIndex)

Parameters

Type	Name	Description
int	meshIndex	glTF mesh index.

Returns

Type	Description
IEnumerable<Mesh>	Iteration over one or more Unity meshes.

See Also

GetMeshCount(int)

GetSceneName(int)

Get a glTF's scene's name by its index

Declaration

public string GetSceneName(int sceneIndex)

Parameters

Type	Name	Description
int	sceneIndex	glTF scene index

Returns

Type	Description
string	Scene name or null

GetSourceCamera(uint)

Get source (de-serialized glTF) camera

Declaration

public Camera GetSourceCamera(uint index)

Parameters

Type	Name	Description
uint	index	glTF camera index

Returns

Type	Description
Camera	De-serialized glTF camera

GetSourceImage(int)

Get source (de-serialized glTF) image

Declaration

public Image GetSourceImage(int index = 0)

Parameters

Type	Name	Description
int	index	glTF image index

Returns

Type	Description
Image	De-serialized glTF image

GetSourceLightPunctual(uint)

Get source (de-serialized glTF) light

Declaration

public LightPunctual GetSourceLightPunctual(uint index)

Parameters

Type	Name	Description
uint	index	glTF light index

Returns

Type	Description
LightPunctual	De-serialized glTF light

GetSourceMaterial(int)

Get source (de-serialized glTF) material

Declaration

public Material GetSourceMaterial(int index = 0)

Parameters

Type	Name	Description
int	index	glTF material index

Returns

Type	Description
Material	De-serialized glTF material

GetSourceMesh(int)

Get source (de-serialized glTF) mesh.

Declaration

public Mesh GetSourceMesh(int meshIndex)

Parameters

Type	Name	Description
int	meshIndex	glTF mesh index.

Returns

Type	Description
Mesh	De-serialized glTF mesh.

GetSourceMeshPrimitive(int, int)

Get source (de-serialized glTF) mesh primitive

Declaration

public MeshPrimitive GetSourceMeshPrimitive(int meshIndex, int primitiveIndex)

Parameters

Type	Name	Description
int	meshIndex	glTF mesh index.
int	primitiveIndex	glTF primitive index within mesh.

Returns

Type	Description
MeshPrimitive	De-serialized glTF mesh primitive

GetSourceNode(int)

Get source (de-serialized glTF) node

Declaration

public Node GetSourceNode(int index = 0)

Parameters

Type	Name	Description
int	index	glTF node index

Returns

Type	Description
Node	De-serialized glTF node

GetSourceScene(int)

Get source (de-serialized glTF) scene

Declaration

public Scene GetSourceScene(int index = 0)

Parameters

Type	Name	Description
int	index	glTF scene index

Returns

Type	Description
Scene	De-serialized glTF scene

GetSourceTexture(int)

Get source (de-serialized glTF) texture

Declaration

public Texture GetSourceTexture(int index = 0)

Parameters

Type	Name	Description
int	index	glTF texture index

Returns

Type	Description
Texture	De-serialized glTF texture

GetTexture(int)

Get imported glTF texture by index.

Declaration

public Texture2D GetTexture(int index = 0)

Parameters

Type	Name	Description
int	index	glTF texture index

Returns

Type	Description
Texture2D	Loaded Unity texture

InstantiateMainSceneAsync(IInstantiator, CancellationToken)

Creates an instance of the main scene of the glTF ( Root.scene property in the JSON at root level) If the main scene index is not set, it instantiates nothing (as defined in the glTF 2.0 specification)

Declaration

public Task<bool> InstantiateMainSceneAsync(IInstantiator instantiator, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
IInstantiator	instantiator	Instantiator implementation; Receives and processes the scene data
CancellationToken	cancellationToken	Token to submit cancellation requests. The default value is None.

Returns

Type	Description
Task<bool>	True if the main scene was instantiated or was not set. False in case of errors.

Exceptions

Type	Condition
OperationCanceledException	Thrown when cancelled before completion.

See Also

DefaultSceneIndex

InstantiateMainSceneAsync(Transform, CancellationToken)

Creates an instance of the main scene of the glTF ( Root.scene property in the JSON at root level) If the main scene index is not set, it instantiates nothing (as defined in the glTF 2.0 specification)

Declaration

public Task<bool> InstantiateMainSceneAsync(Transform parent, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Transform	parent	Transform that the scene will get parented to
CancellationToken	cancellationToken	Token to submit cancellation requests. The default value is None.

Returns

Type	Description
Task<bool>	True if the main scene was instantiated or was not set. False in case of errors.

Exceptions

Type	Condition
OperationCanceledException	Thrown when cancelled before completion.

See Also

DefaultSceneIndex

InstantiateSceneAsync(IInstantiator, int, CancellationToken)

Creates an instance of the scene specified by the scene index.

Declaration

public Task<bool> InstantiateSceneAsync(IInstantiator instantiator, int sceneIndex = 0, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
IInstantiator	instantiator	Instantiator implementation; Receives and processes the scene data
int	sceneIndex	Index of the scene to be instantiated
CancellationToken	cancellationToken	Token to submit cancellation requests. The default value is None.

Returns

Type	Description
Task<bool>	True if the scene was instantiated. False in case of errors.

Exceptions

Type	Condition
OperationCanceledException	Thrown when cancelled before completion.

See Also

SceneCount

GetSceneName(int)

InstantiateSceneAsync(Transform, int, CancellationToken)

Creates an instance of the scene specified by the scene index.

Declaration

public Task<bool> InstantiateSceneAsync(Transform parent, int sceneIndex = 0, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Transform	parent	Transform that the scene will get parented to
int	sceneIndex	Index of the scene to be instantiated
CancellationToken	cancellationToken	Token to submit cancellation requests. The default value is None.

Returns

Type	Description
Task<bool>	True if the scene was instantiated. False in case of errors.

Exceptions

Type	Condition
OperationCanceledException	Thrown when cancelled before completion.

See Also

SceneCount

GetSceneName(int)

IsTextureYFlipped(int)

Evaluates if the texture's vertical orientation conforms to Unity's default. If it's not aligned (=true; =flipped), the texture has to be applied mirrored vertically.

Declaration

public bool IsTextureYFlipped(int index = 0)

Parameters

Type	Name	Description
int	index	glTF texture index

Returns

Type	Description
bool	True if the vertical orientation is flipped, false otherwise

LeaseBufferData()

Acquires read access to the glTF asset's buffer data.

Declaration

public IGltfBufferData LeaseBufferData()

Returns

Type	Description
IGltfBufferData	Read access to the asset's buffer data.

Remarks

The returned lease keeps the buffer memory alive until it is disposed, so dispose it as soon as the data is no longer needed. Buffer data only exists from the moment a glTF's buffers were loaded; a lease taken before or after that reports BufferUnavailable on every request.

LoadAsync(byte[], Uri, ImportSettings, CancellationToken)

Loads a glTF from a byte array.

Declaration

public Task<bool> LoadAsync(byte[] data, Uri uri = null, ImportSettings importSettings = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
byte[]	data	Either glTF-Binary data or a UTF-8 encoded glTF JSON
Uri	uri	Base URI for relative paths of external buffers or images
ImportSettings	importSettings	Import Settings (ImportSettings for details)
CancellationToken	cancellationToken	Token to submit cancellation requests. The default value is None.

Returns

Type	Description
Task<bool>	True if loading was mainly successful and no critical error occurred, false otherwise

Remarks

data is not copied. It has to stay unmodified until the returned Task<TResult> completed, since glTFast reads from it throughout loading, potentially from worker threads.

Exceptions

Type	Condition
OperationCanceledException	Thrown when cancelled before completion.

LoadAsync(string, ImportSettings, CancellationToken)

Load a glTF file (JSON or binary) The URL can be a file path (using the "file://" scheme) or a web address.

Declaration

public Task<bool> LoadAsync(string url, ImportSettings importSettings = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	url	Uniform Resource Locator. Can be a file path (using the "file://" scheme) or a web address.
ImportSettings	importSettings	Import Settings (ImportSettings for details)
CancellationToken	cancellationToken	Token to submit cancellation requests. The default value is None.

Returns

Type	Description
Task<bool>	True if loading was mainly successful and no critical error occurred, false otherwise

Exceptions

Type	Condition
OperationCanceledException	Thrown when cancelled before completion.

LoadAsync(Uri, ImportSettings, CancellationToken)

Load a glTF file (JSON or binary) The URL can be a file path (using the "file://" scheme) or a web address.

Declaration

public Task<bool> LoadAsync(Uri url, ImportSettings importSettings = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Uri	url	Uniform Resource Locator. Can be a file path (using the "file://" scheme) or a web address.
ImportSettings	importSettings	Import Settings (ImportSettings for details)
CancellationToken	cancellationToken	Token to submit cancellation requests. The default value is None.

Returns

Type	Description
Task<bool>	True if loading was mainly successful and no critical error occurred, false otherwise

Exceptions

Type	Condition
OperationCanceledException	Thrown when cancelled before completion.

LoadAsync(ReadOnly, Uri, ImportSettings, CancellationToken)

Loads a glTF from a NativeArray.

Declaration

public Task<bool> LoadAsync(NativeArray<byte>.ReadOnly data, Uri uri = null, ImportSettings importSettings = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
NativeArray<byte>.ReadOnly	data	Either glTF-Binary data or a UTF-8 encoded glTF JSON
Uri	uri	Base URI for relative paths of external buffers or images
ImportSettings	importSettings	Import Settings (ImportSettings for details)
CancellationToken	cancellationToken	Token to submit cancellation requests. The default value is None.

Returns

Type	Description
Task<bool>	True if loading was mainly successful and no critical error occurred, false otherwise

Remarks

data is not copied. The caller keeps ownership of it and has to keep it allocated and unmodified until the returned Task<TResult> completed. glTFast reads from it throughout loading, potentially from worker threads. Disposing the underlying NativeArray_1 before that results in undefined behavior (a safety check exception in the Unity Editor, invalid reads otherwise).

Exceptions

Type	Condition
OperationCanceledException	Thrown when cancelled before completion.

LoadFileAsync(string, Uri, ImportSettings, CancellationToken)

Load glTF from a local file path.

Declaration

public Task<bool> LoadFileAsync(string localPath, Uri uri = null, ImportSettings importSettings = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	localPath	Local path to glTF or glTF-Binary file.
Uri	uri	Base URI for relative paths of external buffers or images
ImportSettings	importSettings	Import Settings (ImportSettings for details)
CancellationToken	cancellationToken	Token to submit cancellation requests. The default value is None.

Returns

Type	Description
Task<bool>	True if loading was mainly successful and no critical error occurred, false otherwise

Exceptions

Type	Condition
OperationCanceledException	Thrown when cancelled before completion.

LoadGltfJsonAsync(string, Uri, ImportSettings, CancellationToken)

Load a glTF JSON from a string

Declaration

public Task<bool> LoadGltfJsonAsync(string json, Uri uri = null, ImportSettings importSettings = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	json	A glTF document, as UTF-8 JSON text.
Uri	uri	Base URI for relative paths of external buffers or images
ImportSettings	importSettings	Import Settings (ImportSettings for details)
CancellationToken	cancellationToken	Token to submit cancellation requests. The default value is None.

Returns

Type	Description
Task<bool>	True if loading was mainly successful and no critical error occurred, false otherwise

Exceptions

Type	Condition
OperationCanceledException	Thrown when cancelled before completion.

LoadStreamAsync(Stream, Uri, ImportSettings, CancellationToken)

Load glTF from a stream.

Declaration

public Task<bool> LoadStreamAsync(Stream stream, Uri uri = null, ImportSettings importSettings = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Stream	stream	Stream of the glTF or glTF-Binary
Uri	uri	Base URI for relative paths of external buffers or images
ImportSettings	importSettings	Import Settings (ImportSettings for details)
CancellationToken	cancellationToken	Token to submit cancellation requests. The default value is None.

Returns

Type	Description
Task<bool>	True if loading was mainly successful and no critical error occurred, false otherwise

Exceptions

Type	Condition
OperationCanceledException	Thrown when cancelled before completion.

ParseJson(ReadOnlySpan<byte>)

De-serializes a UTF-8 encoded glTF JSON string and returns the glTF root object along with the list of decoded data URI UriValues produced by the converter. Ownership of those entries transfers to the caller, which must add them to a disposal container (m_BufferMemoryOwners for buffer data URIs, m_VolatileDisposables otherwise) or dispose them directly.

Declaration

protected static (Root root, List<UriValue> pending) ParseJson(ReadOnlySpan<byte> json)

Parameters

Type	Name	Description
ReadOnlySpan<byte>	json	glTF JSON (UTF-8 encoded)

Returns

Type	Description
(Root root, List<UriValue> pending)	De-serialized glTF root object paired with the converter's pending list.

SetDefaultDeferAgent(IDeferAgent)

Sets the default IDeferAgent for subsequently generated GltfImport instances.

Declaration

public static void SetDefaultDeferAgent(IDeferAgent deferAgent)

Parameters

Type	Name	Description
IDeferAgent	deferAgent	New default IDeferAgent

UnsetDefaultDeferAgent(IDeferAgent)

Allows un-registering default IDeferAgent. For example if it's no longer available.

Declaration

public static void UnsetDefaultDeferAgent(IDeferAgent deferAgent)

Parameters

Type	Name	Description
IDeferAgent	deferAgent	IDeferAgent in question

Events

LoadAccessorDataEvent

Is called when retrieving data from accessors should be performed/started.

Declaration

public event Action LoadAccessorDataEvent

Event Type

Type	Description
Action

MeshResultAssigned

Is called when a mesh and its primitives are assigned to a MeshResult and sub-meshes. Parameters are MeshResult index, mesh index and per sub-mesh primitive index

Declaration

public event Action<int, int, int[]> MeshResultAssigned

Event Type

Type	Description
Action<int, int, int[]>

Implements

IGltfReadable

IMaterialProvider

IMaterialsVariantsProvider

IGltfAccessors

IDisposable