three.js GLTFLoader

用于载入glTF 2.0资源的加载器。

glTF（gl传输格式）是一种开放格式的规范 （open format specification）， 用于更高效地传输、加载3D内容。该类文件以JSON（.gltf）格式或二进制（.glb）格式提供， 外部文件存储贴图（.jpg、.png）和额外的二进制数据（.bin）。一个glTF组件可传输一个或多个场景， 包括网格、材质、贴图、蒙皮、骨架、变形目标、动画、灯光以及摄像机。

GLTFLoader 尽可能使用 ImageBitmapLoader。请注意，图像位图在不再被引用时不会自动被 GC 收集，并且在处置过程中需要特殊处理。有关如何处理对象指南中的更多信息。

扩展

GLTFLoader支持下列glTF 2.0扩展（glTF 2.0 extensions）：

• KHR_draco_mesh_compression
• KHR_materials_clearcoat
• KHR_materials_ior
• KHR_materials_specular
• KHR_materials_transmission
• KHR_materials_iridescence
• KHR_materials_unlit
• KHR_materials_volume
• KHR_mesh_quantization
• KHR_lights_punctual¹
• KHR_texture_basisu
• KHR_texture_transform²
• EXT_texture_webp
• EXT_meshopt_compression
• EXT_mesh_gpu_instancing

外部用户插件支持以下 glTF 2.0 扩展

• KHR_materials_variants³
• MSFT_texture_dds

¹需要physicallyCorrectLights被启用。

²支持UV变换，但存在一些重要的限制。 使用第一个 UV 槽应用于纹理的变换（除 aoMap 和 lightMap 之外的所有纹理）必须共享相同的变换，或者根本没有变换。 aoMap 和 lightMap 纹理不能被变换。每个材质最多只能使用一次变换。 请参阅#13831 和 #12788。

³您也可以在应用程序加载后手动处理扩展。 查看 Three.js glTF materials variants example.

代码示例

// 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<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' );

	}
);

例子

webgl_loader_gltf

浏览器兼容性

GLTFLoader 依赖 ES6 Promises， 这一特性不支持IE11。若要在IE11中使用该加载器，你必须引入polyfill（include a polyfill） 来提供一个Promise的替代方案。

纹理

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

renderer.outputEncoding = THREE.sRGBEncoding;

假设渲染器的配置如上所示，则GLTFLoader将可以正确地自动配置从.gltf或.glb文件中引用的纹理。 当从外部加载纹理（例如，使用TextureLoader）并将纹理应用到glTF模型，则必须给定对应的颜色空间与朝向：

// 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;

自定义扩展

来自未知扩展的元数据会被保存到Object3D、Group和Material实例中上的“.userData.gltfExtensions”， 或被附加到 response “gltf”对象。示例：

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 ) { ... } );

} );

构造函数

GLTFLoader( manager : LoadingManager )

manager — 该加载器将要使用的 loadingManager 。默认为 THREE.DefaultLoadingManager。

创建一个新的GLTFLoader。

属性

共有属性请参见其基类Loader。

方法

共有方法请参见其基类Loader。

.load ( url : String, onLoad : Function, onProgress : Function, onError : Function ) : undefined

url — 包含有.gltf/.glb文件路径/URL的字符串。
onLoad — 加载成功完成后将会被调用的函数。该函数接收parse所返回的已加载的JSON响应。
onProgress — （可选）加载正在进行过程中会被调用的函数。其参数将会是XMLHttpRequest实例，包含有总字节数.total与已加载的字节数.loaded。
onError — （可选）若在加载过程发生错误，将被调用的函数。该函数接收error来作为参数。

开始从url加载，并使用解析过的响应内容调用回调函数。

.setDRACOLoader ( dracoLoader : DRACOLoader ) : this

dracoLoader — THREE.DRACOLoader的实例，用于解码使用KHR_draco_mesh_compression扩展压缩过的文件。

请参阅readme来了解Draco及其解码器的详细信息。

.parse ( data : ArrayBuffer, path : String, onLoad : Function, onError : Function ) : undefined

data — 需要解析的glTF文件，值为一个ArrayBuffer或JSON字符串。
path — 用于找到后续glTF资源（如纹理和.bin数据文件）的基础路径。
onLoad — 解析成功完成后将会被调用的函数。
onError — （可选）若在解析过程发生错误，将被调用的函数。该函数接收error来作为参数。

解析基于glTF的ArrayBuffer或JSON字符串，并在完成后触发onLoad回调。onLoad的参数将是一个包含有已加载部分的Object：.scene、 .scenes、 .cameras、 .animations 和 .asset。

源代码

examples/jsm/loaders/GLTFLoader.js