javascript
/
three.js
mirror of https://github.com/tazdij/three.js.git


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221
							<!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] &rarr;

		<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_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&lt;THREE.AnimationClip&gt;
				gltf.scene; // THREE.Group
				gltf.scenes; // Array&lt;THREE.Group&gt;
				gltf.cameras; // Array&lt;THREE.Camera&gt;
				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 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/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 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>