A loader for glTF 2.0 resources.
glTF (GL Transmission Format) is an
open format specification
for efficient delivery and loading of 3D content. Assets may be provided either in JSON (.gltf)
or binary (.glb) format. External files store textures (.jpg, .png) and additional binary
data (.bin). A glTF asset may deliver one or more scenes, including meshes, materials,
textures, skins, skeletons, morph targets, animations, lights, and/or cameras.
GLTFLoader uses ImageBitmapLoader whenever possible. Be advised that image bitmaps are not automatically GC-collected when they are no longer referenced, and they require special handling during the disposal process. More information in the How to dispose of objects guide.
GLTFLoader supports the following glTF 2.0 extensions:
The following glTF 2.0 extension is supported by an external user plugin
The following glTF 2.0 extensions were added by Verge3D:
1Requires physicallyCorrectLights to be enabled.
2UV transforms are supported, with several key limitations. Transforms applied to a texture using the first UV slot (all textures except aoMap and lightMap) must share the same transform, or no transform at all. The aoMap and lightMap textures cannot be transformed. No more than one transform may be used per material. See #13831 and #12788.
3You can also manually process the extension after loading in your application. See Verge3D glTF materials variants example.
// Instantiate a loader
const loader = new GLTFLoader();
// Optional: Provide a DRACOLoader instance to decode compressed mesh data
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('/examples/jsm/libs/draco/');
loader.setDRACOLoader(dracoLoader);
// Load a glTF resource
loader.load(
// resource URL
'models/gltf/duck/duck.gltf',
// called when the resource is loaded
function(gltf) {
scene.add(gltf.scene);
gltf.animations; // Array<v3d.AnimationClip>
gltf.scene; // v3d.Group
gltf.scenes; // Array<v3d.Group>
gltf.cameras; // Array<v3d.Camera>
gltf.asset; // Object
},
// called while loading is progressing
function(xhr) {
console.log((xhr.loaded / xhr.total * 100) + '% loaded');
},
// called when loading has errors
function(error) {
console.log('An error happened');
}
);
GLTFLoader relies on ES6 Promises, which are not supported in IE11. To use the loader in IE11, you must include a polyfill providing a Promise replacement.
Textures containing color information (.map, .emissiveMap, and .specularMap) always use sRGB colorspace in glTF, while vertex colors and material properties (.color, .emissive, .specular) use linear colorspace. In a typical rendering workflow, textures are converted to linear colorspace by the renderer, lighting calculations are made, then final output is converted back to sRGB and displayed on screen. Unless you need post-processing in linear colorspace, always configure WebGLRenderer as follows when using glTF:
renderer.outputEncoding = v3d.sRGBEncoding;
GLTFLoader will automatically configure textures referenced from a .gltf or .glb file correctly, with the assumption that the renderer is set up as shown above. When loading textures externally (e.g., using TextureLoader) and applying them to a glTF model, colorspace and orientation must be given:
// If texture is used for color information, set colorspace.
texture.encoding = v3d.sRGBEncoding;
// UVs use the convention that (0, 0) corresponds to the upper left corner of a texture.
texture.flipY = false;
Metadata from unknown extensions is preserved as “.userData.gltfExtensions” on Object3D, Scene, and Material instances, or attached to the response “gltf” object. Example:
loader.load('foo.gltf', function(gltf) {
const scene = gltf.scene;
const mesh = scene.children[3];
const fooExtension = mesh.userData.gltfExtensions.EXT_foo;
gltf.parser.getDependency('bufferView', fooExtension.bufferView)
.then(function(fooBuffer) { ... });
});
manager — The loadingManager for the loader to use. Default is v3d.DefaultLoadingManager.
Creates a new GLTFLoader.
See the base Loader class for common properties.
See the base Loader class for common methods.
url — A string containing the path/URL of the .gltf or .glb file.
onLoad — A function to be called after the loading is successfully completed. The function receives the loaded JSON response returned from parse.
onProgress — (optional) A function to be called while the loading is in progress. The argument will be the XMLHttpRequest instance, that contains .total and .loaded bytes. If the server does not set the Content-Length header; .total will be 0.
onError — (optional) A function to be called if an error occurs during loading. The function receives error as an argument.
Begin loading from url and call the callback function with the parsed response content.
dracoLoader — Instance of v3d.DRACOLoader, to be used for decoding assets compressed with the KHR_draco_mesh_compression extension.
Refer to this readme for the details of Draco and its decoder.
ktx2Loader — Instance of v3d.KTX2Loader, to be used for loading KTX2 compressed textures.
data — glTF asset to parse, as an ArrayBuffer, JSON string or object.
path — The base path from which to find subsequent glTF resources such as textures and .bin data files.
onLoad — A function to be called when parse completes.
onError — (optional) A function to be called if an error occurs during parsing. The function receives error as an argument.
Parse a glTF-based ArrayBuffer, JSON string or object and fire onLoad callback when complete. The argument to onLoad will be an Object that contains loaded parts: .scene, .scenes, .cameras, .animations, and .asset.
For more info on how to obtain the source code of this module see this page.