GLTFLoader
Parses a glTF file. Can load both the .glb
(binary) and .gltf
(application/json) file format variants.
A glTF file contains a hierarchical scenegraph description that can be used to instantiate corresponding hierarcy of actual Scenegraph
related classes in most WebGL libraries.
Loader | Characteristic | |
---|---|---|
File Extensions | .glb , .gltf | |
File Type | Binary, JSON, Linked Assets | |
File Format | glTF v2, GLTF v1 * | |
Data Format | Scenegraph | |
Supported APIs | load , parse | |
Subloaders | DracoLoader , ImageLoader |
* From , the
GLTFLoader
offers optional, best-effort support for converting older glTF v1 files to glTF v2 format (options.gltf.normalize: true
). This conversion has a number of limitations and the parsed data structure may be only partially converted to glTF v2, causing issues to show up later e.g. when attempting to render the scenegraphs.
Usage
import {load} from '@loaders.gl/core';
import {GLTFLoader} from '@loaders.gl/gltf';
const gltf = await load(url, GLTFLoader);
To decompress Draco-compressed meshes:
import {load} from '@loaders.gl/core';
import {GLTFLoader} from '@loaders.gl/gltf';
import {DracoLoader} from '@loaders.gl/draco';
const gltf = load(url, GLTFLoader, {DracoLoader, decompress: true});
Overview
The GLTFLoader
aims to take care of as much processing as possible, while remaining framework-independent.
The GLTF Loader returns an object with a json
field containing the glTF Scenegraph. In its basic mode, the GLTFLoader
does not modify the loaded JSON in any way. Instead, the results of additional processing are placed in parallel top-level fields such as buffers
and images
. This ensures that applications that want to work with the standard glTF data structure can do so.
Optionally, the loaded gltf can be "post processed", which lightly annotates and transforms the loaded JSON structure to make it easier to use. Refer to postProcessGLTF for details.
In addition, certain glTF extensions, in particular Draco mesh encoding, can be fully or partially processed during loading. When possible (and extension processing is enabled), such extensions will be resolved/decompressed and replaced with standards conformant representations. See glTF Extensions for more information.
Note: while supported, synchronous parsing of glTF (e.g. using parseSync()
) has significant limitations. When parsed asynchronously (using await parse()
or await load()
), the following additional capabilities are enabled:
- linked binary resource URI:s will be loaded and resolved (assuming a valid base url is available).
- base64 encoded binary URI:s inside the JSON payload will be decoded.
- linked image URI:s can be loaded and decoded.
- Draco meshes can be decoded asynchronously on worker threads (in parallel!).
Options
Option | Type | Default | Description | |
---|---|---|---|---|
gltf.loadBuffers | Boolean | false | Fetch any referenced binary buffer files (and decode base64 encoded URIS). | |
gltf.loadImages | Boolean | false | Load any referenced image files (and decode base64 encoded URIS). | |
gltf.decompressMeshes | Boolean | true | Decompress Draco compressed meshes (if DracoLoader available). | |
gltf.postProcess | Boolean | true | Perform additional post processing on the loaded glTF data. | |
gltf.normalize | Boolean | false | Optional, best-effort attempt at converting glTF v1 files to glTF2 format. |
Remarks:
- The
gltf.postProcess
option activates additional post processing that transforms parts of JSON structure in the loaded glTF data, to make glTF data easier use in applications and WebGL libraries (e.g replacing indices with links to the indexed objects). However, the data structure returned by theGLTFLoader
will no longer be fully glTF compatible.
Data Format
With Post Processing
When the GLTFLoader
is called with gltf.postProcess
option set to true
(the default),the parsed JSON chunk will be returned, and post processing will have been performed, which will link data from binary buffers into the parsed JSON structure using non-standard fields, and also modify the data in other ways to make it easier to use.
At the top level, this will look like a standard glTF JSON structure:
{
scenes: [...],
scene: ...,
nodes: [...],
...
}
However, the objects inside these arrays will have been pre-processed to simplify usage. For details on changes and extra fields added to the various glTF objects, see post processing.
Without Post Processing
By setting gltf.postProcess
to false
, an unprocessed glTF/GLB data structure will be returned, with binary buffers provided as an ArrayBuffer
array.
{
// The base URI used to load this glTF, if any. For resolving relative uris to linked resources.
baseUri: String,
// JSON Chunk
json: Object, // Containse the parsed glTF JSON or the parsed GLB JSON chunk
// Length and indices of this array will match `json.buffers`
// The GLB bin chunk, if present, will be found in buffer 0.
// Additional glTF json `buffers` are fetched and base64 decoded from the JSON uri:s.
buffers: [{
arrayBuffer: ArrayBuffer,
byteOffset: Number,
byteLength: Number
}],
// Images can optionally be loaded and decoded, they will be stored here
// Length and indices of this array will match `json.buffers`
images: Image[],
// GLBLoader output, if this was a GLB encoded glTF
_glb?: Object
}
Field | Type | Default | Description |
---|---|---|---|
baseUri | String | `` | length of GLB (e.g. embedded in larger binary block) |
json | Object | {} | Parsed JSON from the JSON chunk |
buffers | Object[] | [] | The version number |
buffers[\*].arrayBuffer | ArrayBuffer | null | The binary chunk |
buffers[\*].byteOffset | Number | null | offset of buffer (embedded in larger binary block) |
buffers[\*].byteLength | ArrayBuffer | null | length of buffer (embedded in larger binary block) |
_glb ? | Object | N/A | The output of the GLBLoader if the parsed file was GLB formatted |