GLTFLoader

GLTF加载器（GLTFLoader）

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

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

GLTFLoader uses 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 How to dispose of objects guide.

扩展

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

• KHR_draco_mesh_compression
• KHR_materials_clearcoat
• KHR_materials_ior
• KHR_materials_pbrSpecularGlossiness
• KHR_materials_specular
• KHR_materials_transmission
• KHR_materials_iridescence
• KHR_materials_unlit
• KHR_materials_volume
• KHR_mesh_quantization
• KHR_lights_punctual1
• KHR_texture_basisu
• KHR_texture_transform2
• EXT_texture_webp
• EXT_meshopt_compression

The following glTF 2.0 extension is supported by an external user plugin

• KHR_materials_variants3
• MSFT_texture_dds

1需要physicallyCorrectLights被启用。

2支持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 纹理不能被变换。每个材质最多只能使用一次变换。 请参阅#13831 和 #12788。

3You can also manually process the extension after loading in your application. See 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/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<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