Chevron Down
Table of Contents
Chevron DownAPI Reference

GLTFLoader

Parses a glTF file. Can load both the .glb (binary) and .gltf (text/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.

LoaderCharacteristic
File Extensions.glb, .gltf
File TypeBinary, JSON, Linked Assets
File FormatglTF
Data FormatScenegraph
Decoder TypeSynchronous (limited), Asynchronous
Worker Thread SupportNo
Streaming SupportNo

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!).

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});

Options

OptionTypeDefault AsyncSyncDescription
fetchLinkedResourcesBooleantrueNoFetch any linked .BIN files, decode base64 encoded URIS. Async only.
fetchImagesBooleanfalseNoFetch any referenced image files (and decode base64 encoded URIS). Async only.
createImagesBooleanfalseCreate image objects from loaded image data.
fetchFunctionfetchN/AFunction used to fetch linked resources.
uriStringfetchN/AFunction used to fetch linked resources.
decompressBooleantrueYesDecompress Draco compressed meshes (if DracoLoader available).
DracoLoaderDracoLoadernullYes*Supply to enable decoding of Draco compressed meshes. * DracoWorkerLoader is async only.
postProcessBooleanfalsePerform additional post processing to simplify use in WebGL libraries.

Data Format

Returns

{
  // The base URI used to load this glTF, if any. For resolving relative uris to linked resources.
  baseUri: String,

  // JSON Chunk
  json: Object,

  // Length and indices of this array will match `json.buffers`
  // The GLB bin chunk, if present, will be found in buffer 0.
  // Additional buffers are fetched or 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
}
FieldTypeDefaultDescription
baseUriString | length of GLB (e.g. embedded in larger binary block)
jsonObject{}Parsed JSON from the JSON chunk
buffersObject[][]The version number
buffers[\*].arrayBufferArrayBuffernullThe binary chunk
buffers[\*].byteOffsetNumbernulloffset of buffer (embedded in larger binary block)
buffers[\*].byteLengthArrayBuffernulllength of buffer (embedded in larger binary block)
_glb?ObjectN/AThe output of the GLBLoader if the parsed file was GLB formatted