Loader →

GLTFLoader

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 (with optional LZMA compression). External files store textures (.jpg, .png, .webp, .hdr) and additional binary data (.bin). A glTF asset may deliver one or more scenes, including meshes, materials, textures, skins, skeletons, morph targets, animations, lights, light probes, fonts, 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.

You rarely need to use GLTFLoader since there are convenient App.loadScene and App.appendScene methods which hide all the complexity of loading/appending glTF 2.0 assets.

Extensions

GLTFLoader supports the following Verge3D extensions:

S8S_v3d_animation
S8S_v3d_camera
S8S_v3d_materials
S8S_v3d_mesh
S8S_v3d_node
S8S_v3d_scene
S8S_v3d_texture
S8S_v3d_lights
S8S_v3d_light_probes
S8S_v3d_curves
S8S_v3d_clipping_planes

As well as standard glTF 2.0 extensions:

KHR_materials_unlit
KHR_texture_basisu
EXT_texture_webp

Code Example


    // instantiate a loader
    const loader = new GLTFLoader();

    // load a glTF resource
    loader.load(
        // resource URL
        'duck.gltf',

        // called when the resource is loaded
        function(gltf) {
            app.scene.add(gltf.scene);

            gltf.animations; // array of v3d.AnimationClip
            gltf.scene; // v3d.Scene
            gltf.scenes; // array of v3d.Scene
            gltf.cameras; // array of v3d.Camera
            gltf.asset; // object
            gltf.world; // 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');
        }
    );

Textures

Textures containing color information (e.g. MeshStandardMaterial.map) always use sRGB colorspace in glTF, while vertex colors and material properties (e.g. MeshStandardMaterial.color) 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;

Unknown extensions

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

Constructor

GLTFLoader(manager : LoadingManager)

manager — the loadingManager for the loader to use. Default is v3d.DefaultLoadingManager.

Creates a new GLTFLoader.

Properties

See the base Loader class for common properties.

Methods

See the base Loader class for common methods.

# .load(url : String, onLoad : Function, onProgress : Function, onError : Function)

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.

# .setKTX2Loader(ktx2Loader : KTX2Loader) → this

ktx2Loader — instance of v3d.KTX2Loader, to be used for loading KTX2 compressed textures.

# .parse(data : ArrayBuffer, path : String, onLoad : Function, onError : Function)

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 an 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.

Puzzles

The are two puzzles to simplify work with glTF 2.0 assets:

load scene — to load and replace the current scene entirely.
append scene — to append some asset to the current scene.

Source

For more info on how to obtain the source code of this module see this page.