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.
226 lines
8.5 KiB
226 lines
8.5 KiB
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<base href="../../" />
|
|
<script src="list.js"></script>
|
|
<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 <em>glTF 2.0</em> 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>
|
|
|
|
<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_pbrSpecularGlossiness</li>
|
|
<li>KHR_materials_unlit</li>
|
|
<li>KHR_lights_punctual<sup>1</sup></li>
|
|
<li>KHR_texture_transform<sup>2</sup></li>
|
|
<li>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 transfor at all. The aoMap and lightMap textures cannot be transformed. No
|
|
more than one transform may be used per material. Each use of a texture with a unique
|
|
transform will result in an additional GPU texture upload. See
|
|
#[link:https://github.com/mrdoob/three.js/pull/13831 13831] and
|
|
#[link:https://github.com/mrdoob/three.js/issues/12788 12788].
|
|
</i></p>
|
|
|
|
<h2>Example</h2>
|
|
|
|
<code>
|
|
// Instantiate a loader
|
|
var loader = new THREE.GLTFLoader();
|
|
|
|
// Optional: Provide a DRACOLoader instance to decode compressed mesh data
|
|
THREE.DRACOLoader.setDecoderPath( '/examples/js/libs/draco' );
|
|
loader.setDRACOLoader( new THREE.DRACOLoader() );
|
|
|
|
// Optional: Pre-fetch Draco WASM/JS module, to save time while parsing.
|
|
THREE.DRACOLoader.getDecoderModule();
|
|
|
|
// 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.Scene
|
|
gltf.scenes; // Array<THREE.Scene>
|
|
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>
|
|
|
|
[example:webgl_loader_gltf]
|
|
|
|
<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.gammaOutput = true;
|
|
renderer.gammaFactor = 2.2;
|
|
</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 ) {
|
|
|
|
var scene = gltf.scene;
|
|
|
|
var mesh = scene.children[ 3 ];
|
|
|
|
var 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>
|
|
|
|
|
|
<h2>Methods</h2>
|
|
|
|
<h3>[method:null 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 <em>.gltf</em> or <em>.glb</em> 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.<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:GLTFLoader setPath]( [param:String path] )</h3>
|
|
<p>
|
|
[page:String path] — Base path.
|
|
</p>
|
|
<p>
|
|
Set the base path for the .gltf/.glb file.
|
|
</p>
|
|
|
|
<h3>[method:GLTFLoader setResourcePath]( [param:String path] )</h3>
|
|
<p>
|
|
[page:String path] — Base path for loading additional resources e.g. textures and .bin data.
|
|
</p>
|
|
<p>
|
|
Set the base path for additional resources.
|
|
</p>
|
|
|
|
<h3>[method:null setCrossOrigin]( [param:String value] )</h3>
|
|
<p>
|
|
[page:String value] — The crossOrigin string to implement CORS for loading the url from a different domain that allows CORS.
|
|
</p>
|
|
|
|
<h3>[method:null 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:null 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 or <em>JSON</em> string.<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 or <em>JSON</em> String and fire [page:Function onLoad] callback when complete. The argument to [page:Function onLoad] will be an [page:object] that contains loaded parts: .[page:Scene scene], .[page:Array scenes], .[page:Array cameras], .[page:Array animations], and .[page:Object asset].
|
|
</p>
|
|
|
|
<h2>Source</h2>
|
|
|
|
[link:https://github.com/mrdoob/three.js/blob/master/examples/js/loaders/GLTFLoader.js examples/js/loaders/GLTFLoader.js]
|
|
</body>
|
|
</html>
|