Chapter 169: GLTFLoader

Core Idea

A loader for the glTF 2.0 format.

glTF (GL Transmission Format) is an open format specification 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.

GLTFLoader supports the following glTF 2.0 extensions:

• KHR_draco_mesh_compression
• KHR_lights_punctual
• KHR_materials_anisotropy
• KHR_materials_clearcoat
• KHR_materials_dispersion
• KHR_materials_emissive_strength
• KHR_materials_ior
• KHR_materials_specular
• KHR_materials_transmission
• KHR_materials_iridescence
• KHR_materials_unlit
• KHR_materials_volume
• KHR_mesh_quantization
• KHR_meshopt_compression
• KHR_texture_basisu
• KHR_texture_transform
• EXT_materials_bump
• EXT_meshopt_compression
• EXT_mesh_gpu_instancing
• EXT_texture_avif
• EXT_texture_webp

The following glTF 2.0 extension is supported by an external user plugin:

• KHR_materials_variants
• MSFT_texture_dds
• KHR_animation_pointer
• NEEDLE_progressive

Code Examples

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 );
const gltf = await loader.loadAsync( 'models/gltf/duck/duck.gltf' );
scene.add( gltf.scene );

• What it demonstrates: Typical usage of GLTFLoader.

Reference Tables

Constructor

Signature
new GLTFLoader( manager : LoadingManager )

Methods

Method	Description
.load( url : string, onLoad : function, onProgress : onProgressCallback, onError : onErrorCallback )	Starts loading from the given URL and passes the loaded glTF asset to the onLoad() callback.
`.parse( data : string	ArrayBuffer, path : string, onLoad : function, onError : onErrorCallback )`
`.parseAsync( data : string	ArrayBuffer, path : string ) : Promise.<GLTFLoader~LoadObject> (async)`
.register( callback : function ) : GLTFLoader	Registers a plugin callback. This API is internally used to implement the various glTF extensions but can also used by third-party code to add additional logic to the loader.
.setDRACOLoader( dracoLoader : DRACOLoader ) : GLTFLoader	Sets the given Draco loader to this loader. Required for decoding assets compressed with the KHR_draco_mesh_compression extension.
.setKTX2Loader( ktx2Loader : KTX2Loader ) : GLTFLoader	Sets the given KTX2 loader to this loader. Required for loading KTX2 compressed textures.
.setMeshoptDecoder( meshoptDecoder : Object ) : GLTFLoader	Sets the given meshopt decoder. Required for decoding assets compressed with the EXT_meshopt_compression extension.
.unregister( callback : function ) : GLTFLoader	Unregisters a plugin callback.

Key Takeaways

1. GLTFLoader extends: Loader
2. Key methods: load, parse, parseAsync, register.

Connects To

• Loader: parent class
• Source: examples/jsm/loaders/GLTFLoader.js