123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222 |
- <!DOCTYPE html>
- <html lang="en">
- <head>
- <meta charset="utf-8" />
- <base href="../../../" />
- <script src="page.js"></script>
- <link type="text/css" rel="stylesheet" href="page.css" />
- </head>
- <body>
- [page:Loader] →
- <h1>[name]</h1>
- <p class="desc"> A loader for `glTF 2.0` resources. <br /><br />
- [link:https://www.khronos.org/gltf glTF] (GL Transmission Format) is an
- [link:https://github.com/KhronosGroup/glTF/tree/master/specification/2.0 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.
- </p>
- <p>
- [name] uses [page: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 [link:https://threejs.org/docs/#manual/en/introduction/How-to-dispose-of-objects How to dispose of objects] guide.
- </p>
- <h2>Import</h2>
- <p>
- [name] is an add-on, and must be imported explicitly.
- See [link:#manual/introduction/Installation Installation / Addons].
- </p>
- <code>
- import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
- </code>
- <h2>Extensions</h2>
- <p>
- GLTFLoader supports the following
- [link:https://github.com/KhronosGroup/glTF/tree/master/extensions/ glTF 2.0 extensions]:
- </p>
- <ul>
- <li>KHR_draco_mesh_compression</li>
- <li>KHR_materials_clearcoat</li>
- <li>KHR_materials_dispersion</li>
- <li>KHR_materials_ior</li>
- <li>KHR_materials_specular</li>
- <li>KHR_materials_transmission</li>
- <li>KHR_materials_iridescence</li>
- <li>KHR_materials_unlit</li>
- <li>KHR_materials_volume</li>
- <li>KHR_mesh_quantization</li>
- <li>KHR_lights_punctual</li>
- <li>KHR_texture_basisu</li>
- <li>KHR_texture_transform</li>
- <li>EXT_texture_webp</li>
- <li>EXT_meshopt_compression</li>
- <li>EXT_mesh_gpu_instancing</li>
- </ul>
- <p>
- The following glTF 2.0 extension is supported by an external user plugin
- </p>
- <ul>
- <li>[link:https://github.com/takahirox/three-gltf-extensions KHR_materials_variants]<sup>1</sup></li>
- <li>[link:https://github.com/takahirox/three-gltf-extensions MSFT_texture_dds]</li>
- </ul>
- <p><i>
- <sup>1</sup>You can also manually process the extension after loading in your application. See [link:https://threejs.org/examples/#webgl_loader_gltf_variants Three.js glTF materials variants example].
- </i></p>
- <h2>Code Example</h2>
- <code>
- // 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<THREE.AnimationClip>
- gltf.scene; // THREE.Group
- gltf.scenes; // Array<THREE.Group>
- gltf.cameras; // Array<THREE.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' );
- }
- );
- </code>
- <h2>Examples</h2>
- <p>
- [example:webgl_loader_gltf]
- </p>
- <h2>Textures</h2>
- <p>When loading textures externally (e.g., using [page:TextureLoader]) and applying them to a glTF model,
- textures must be configured. Textures referenced from the glTF model are configured automatically by
- GLTFLoader.</p>
- <code>
- // If texture is used for color information (.map, .emissiveMap, .specularMap, ...), set color space
- texture.colorSpace = THREE.SRGBColorSpace;
- // UVs use the convention that (0, 0) corresponds to the upper left corner of a texture.
- texture.flipY = false;
- </code>
- <h2>Custom extensions</h2>
- <p>
- Metadata from unknown extensions is preserved as “.userData.gltfExtensions” on Object3D, Scene, and Material instances,
- or attached to the response “gltf” object. Example:
- </p>
- <code>
- 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 ) { ... } );
- } );
- </code>
- <br>
- <hr>
- <h2>Constructor</h2>
- <h3>[name]( [param:LoadingManager manager] )</h3>
- <p>
- [page:LoadingManager manager] — The [page:LoadingManager loadingManager] for the loader to use. Default is [page:LoadingManager THREE.DefaultLoadingManager].
- </p>
- <p>
- Creates a new [name].
- </p>
- <h2>Properties</h2>
- <p>See the base [page:Loader] class for common properties.</p>
- <h2>Methods</h2>
- <p>See the base [page:Loader] class for common methods.</p>
- <h3>[method:undefined load]( [param:String url], [param:Function onLoad], [param:Function onProgress], [param:Function onError] )</h3>
- <p>
- [page:String url] — A string containing the path/URL of the `.gltf` or `.glb` file.<br />
- [page:Function onLoad] — A function to be called after the loading is successfully completed. The function receives the loaded JSON response returned from [page:Function parse].<br />
- [page:Function onProgress] — (optional) A function to be called while the loading is in progress. The argument will be the XMLHttpRequest instance, that contains .[page:Integer total] and .[page:Integer loaded] bytes. If the server does not set the Content-Length header; .[page:Integer total] will be 0.<br />
- [page:Function onError] — (optional) A function to be called if an error occurs during loading. The function receives error as an argument.<br />
- </p>
- <p>
- Begin loading from url and call the callback function with the parsed response content.
- </p>
- <h3>[method:this setDRACOLoader]( [param:DRACOLoader dracoLoader] )</h3>
- <p>
- [page:DRACOLoader dracoLoader] — Instance of DRACOLoader, to be used for decoding assets compressed with the KHR_draco_mesh_compression extension.
- </p>
- <p>
- Refer to this [link:https://github.com/mrdoob/three.js/tree/dev/examples/jsm/libs/draco#readme readme] for the details of Draco and its decoder.
- </p>
- <h3>[method:this setKTX2Loader]( [param:KTX2Loader ktx2Loader] )</h3>
- <p>
- [page:KTX2Loader ktx2Loader] — Instance of KTX2Loader, to be used for loading KTX2 compressed textures.
- </p>
- <h3>[method:undefined parse]( [param:ArrayBuffer data], [param:String path], [param:Function onLoad], [param:Function onError] )</h3>
- <p>
- [page:ArrayBuffer data] — glTF asset to parse, as an `ArrayBuffer`, `JSON` string or object.<br />
- [page:String path] — The base path from which to find subsequent glTF resources such as textures and .bin data files.<br />
- [page:Function onLoad] — A function to be called when parse completes.<br />
- [page:Function onError] — (optional) A function to be called if an error occurs during parsing. The function receives error as an argument.<br />
- </p>
- <p>
- Parse a glTF-based `ArrayBuffer`, `JSON` string or object and fire [page:Function onLoad] callback when complete. The argument to [page:Function onLoad] will be an [page:Object] that contains loaded parts: .[page:Group scene], .[page:Array scenes], .[page:Array cameras], .[page:Array animations], and .[page:Object asset].
- </p>
- <h2>Source</h2>
- <p>
- [link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/loaders/GLTFLoader.js examples/jsm/loaders/GLTFLoader.js]
- </p>
- </body>
- </html>
|