You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
239 lines
9.3 KiB
239 lines
9.3 KiB
<!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>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_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<sup>1</sup></li>
|
|
<li>KHR_texture_basisu</li>
|
|
<li>KHR_texture_transform<sup>2</sup></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>3</sup></li>
|
|
<li>[link:https://github.com/takahirox/three-gltf-extensions MSFT_texture_dds]</li>
|
|
</ul>
|
|
|
|
<p><i>
|
|
<sup>1</sup>Requires [link:https://threejs.org/docs/#api/en/renderers/WebGLRenderer.physicallyCorrectLights physicallyCorrectLights] to be enabled.
|
|
</i></p>
|
|
<p><i>
|
|
<sup>2</sup>UV 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
|
|
#[link:https://github.com/mrdoob/three.js/pull/13831 13831] and
|
|
#[link:https://github.com/mrdoob/three.js/issues/12788 12788].
|
|
</i></p>
|
|
|
|
<p><i>
|
|
<sup>3</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/js/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>Browser compatibility</h2>
|
|
|
|
<p>GLTFLoader relies on ES6 [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise Promises],
|
|
which are not supported in IE11. To use the loader in IE11, you must
|
|
[link:https://github.com/stefanpenner/es6-promise include a polyfill]
|
|
providing a Promise replacement.</p>
|
|
|
|
<h2>Textures</h2>
|
|
|
|
<p>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 [page:WebGLRenderer] as follows when using glTF:</p>
|
|
|
|
<code>
|
|
renderer.outputEncoding = THREE.sRGBEncoding;
|
|
</code>
|
|
|
|
<p>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
|
|
[page:TextureLoader]) and applying them to a glTF model, colorspace and orientation must be given:</p>
|
|
|
|
<code>
|
|
// If texture is used for color information, set colorspace.
|
|
texture.encoding = THREE.sRGBEncoding;
|
|
|
|
// 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 THREE.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/js/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 THREE.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>
|
|
|