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


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212
							<!DOCTYPE html>
<html lang="zh">
	<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>GLTF加载器（[name]）</h1>

		<p class="desc">用于载入<em>glTF 2.0</em>资源的加载器。<br /><br />
		[link:https://www.khronos.org/gltf glTF]（gl传输格式）是一种开放格式的规范
		（[link:https://github.com/KhronosGroup/glTF/tree/master/specification/2.0 open format specification]），
		用于更高效地传输、加载3D内容。该类文件以JSON（.glft）格式或二进制（.glb）格式提供，
		外部文件存储贴图（.jpg、.png）和额外的二进制数据（.bin）。一个glTF组件可传输一个或多个场景，
		包括网格、材质、贴图、蒙皮、骨架、变形目标、动画、灯光以及摄像机。
		</p>

		<h2>扩展</h2>

		<p>
			GLTFLoader支持下列glTF 2.0扩展（[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_pbrSpecularGlossiness</li>
			<li>KHR_materials_unlit</li>
			<li>KHR_mesh_quantization</li>
			<li>KHR_lights_punctual<sup>1</sup></li>
			<li>KHR_texture_basisu <i>(experimental)</i></li>
			<li>KHR_texture_transform<sup>2</sup></li>
			<li>EXT_texture_webp</li>
			<li>MSFT_texture_dds</li>
		</ul>

		<p><i>
			<sup>1</sup>需要[link:https://threejs.org/docs/#api/en/renderers/WebGLRenderer.physicallyCorrectLights physicallyCorrectLights]被启用。
		</i></p>
		<p><i>
			<sup>2</sup>支持UV变换，但存在一些重要的限制。
			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.
			aoMap 和 lightMap 纹理不能被变换。每个材质最多只能使用一次变换。
			每次对使用具有唯一变换的纹理都会导致一次额外的GPU纹理上传。
			请参阅#[link:https://github.com/mrdoob/three.js/pull/13831 13831] 和
			#[link:https://github.com/mrdoob/three.js/issues/12788 12788]。
		</i></p>

		<h2>代码示例</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&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>例子</h2>

		<p>
			[example:webgl_loader_gltf]
		</p>

		<h2>浏览器兼容性</h2>

		<p>GLTFLoader 依赖 ES6 [link:https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise Promises]，
		这一特性不支持IE11。若要在IE11中使用该加载器，你必须引入polyfill（[link:https://github.com/stefanpenner/es6-promise include a polyfill]）
		来提供一个Promise的替代方案。</p>

		<h2>纹理</h2>

		<p>纹理中包含的颜色信息（.map, .emissiveMap, 和 .specularMap）在glTF中总是使用sRGB颜色空间，而顶点颜色和材质属性（.color, .emissive, .specular）
		则使用线性颜色空间。在典型的渲染工作流程中，纹理会被渲染器转换为线性颜色空间，进行光照计算，然后最终输出会被转换回 sRGB
		颜色空间并显示在屏幕上。除非你需要使用线性颜色空间进行后期处理，否则请在使用glTF的时候将[page:WebGLRenderer]进行如下配置：</p>

		<code>
		renderer.outputEncoding = THREE.sRGBEncoding;
		</code>

		<p>假设渲染器的配置如上所示，则GLTFLoader将可以正确地自动配置从.gltf或.glb文件中引用的纹理。
		当从外部加载纹理（例如，使用[page:TextureLoader]）并将纹理应用到glTF模型，则必须给定对应的颜色空间与朝向：</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>自定义扩展</h2>

		<p>
			来自未知扩展的元数据会被保存到Object3D、Group和Material实例中上的“.userData.gltfExtensions”，
			或被附加到 response “gltf”对象。示例：
		</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>构造函数</h2>

		<h3>[name]( [param:LoadingManager manager] )</h3>
		<p>
		[page:LoadingManager manager] — 该加载器将要使用的 [page:LoadingManager loadingManager] 。默认为 [page:LoadingManager THREE.DefaultLoadingManager]。
		</p>
		<p>
		创建一个新的[name]。
		</p>

		<h2>属性</h2>
		<p>共有属性请参见其基类[page:Loader]。</p>

		<h2>方法</h2>
		<p>共有方法请参见其基类[page:Loader]。</p>

		<h3>[method:null load]( [param:String url], [param:Function onLoad], [param:Function onProgress], [param:Function onError] )</h3>
		<p>
		[page:String url] — 包含有<em>.gltf</em>/<em>.glb</em>文件路径/URL的字符串。<br />
		[page:Function onLoad] — 加载成功完成后将会被调用的函数。该函数接收[page:Function parse]所返回的已加载的JSON响应。<br />
		[page:Function onProgress] — （可选）加载正在进行过程中会被调用的函数。其参数将会是XMLHttpRequest实例，包含有总字节数.[page:Integer total]与已加载的字节数.[page:Integer loaded]。<br />
		[page:Function onError] — （可选）若在加载过程发生错误，将被调用的函数。该函数接收error来作为参数。<br />
		</p>
		<p>
		开始从url加载，并使用解析过的响应内容调用回调函数。
		</p>

		<h3>[method:null setDRACOLoader]( [param:DRACOLoader dracoLoader] )</h3>
		<p>
		[page:DRACOLoader dracoLoader] — THREE.DRACOLoader的实例，用于解码使用KHR_draco_mesh_compression扩展压缩过的文件。
		</p>
		<p>
		请参阅[link:https://github.com/mrdoob/three.js/tree/dev/examples/js/libs/draco#readme readme]来了解Draco及其解码器的详细信息。
		</p>

		<h3>[method:null setDDSLoader]( [param:DDSLoader ddsLoader] )</h3>
		<p>
		[page:DDSLoader ddsLoader] — THREE.DDSLoader的实例，用于加载使用MSFT_TEXTURE_DDS扩展压缩过的纹理。
		</p>

		<h3>[method:null parse]( [param:ArrayBuffer data], [param:String path], [param:Function onLoad], [param:Function onError] )</h3>
		<p>
		[page:ArrayBuffer data] — 需要解析的glTF文件，值为一个ArrayBuffer或<em>JSON</em>字符串。<br />
		[page:String path] — 用于找到后续glTF资源（如纹理和.bin数据文件）的基础路径。<br />
		[page:Function onLoad] — 解析成功完成后将会被调用的函数。<br />
		[page:Function onError] — （可选）若在解析过程发生错误，将被调用的函数。该函数接收error来作为参数。<br />
		</p>
		<p>
		解析基于glTF的ArrayBuffer或<em>JSON</em>字符串，并在完成后触发[page:Function onLoad]回调。[page:Function onLoad]的参数将是一个包含有已加载部分的[page:Object]：.[page:Group scene]、 .[page:Array scenes]、 .[page:Array cameras]、 .[page:Array animations] 和 .[page:Object asset]。
		</p>

		<h2>源代码</h2>

		<p>
			[link:https://github.com/mrdoob/three.js/blob/master/examples/jsm/loaders/GLTFLoader.js examples/jsm/loaders/GLTFLoader.js]
		</p>
	</body>
</html>