javascript
/
three.js
зеркало из https://github.com/tazdij/three.js.git


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230
							<!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] &rarr;
		<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&lt;THREE.AnimationClip&gt;
				gltf.scene; // THREE.Scene
				gltf.scenes; // Array&lt;THREE.Scene&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>

		[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 setDDSLoader]( [param:DDSLoader ddsLoader] )</h3>
		<p>
		[page:DDSLoader ddsLoader] — Instance of THREE.DDSLoader, to be used for loading compressed textures with the MSFT_TEXTURE_DDS extension.
		</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>