three.js GLTFLoader

用于載入glTF 2.0資源的加載器。

glTF（gl傳輸格式）是一種開放格式的規(guī)范 （open format specification）， 用于更高效地傳輸、加載3D內(nèi)容。該類文件以JSON（.gltf）格式或二進制（.glb）格式提供， 外部文件存儲貼圖（.jpg、.png）和額外的二進制數(shù)據(jù)（.bin）。一個glTF組件可傳輸一個或多個場景， 包括網(wǎng)格、材質(zhì)、貼圖、蒙皮、骨架、變形目標、動畫、燈光以及攝像機。

GLTFLoader 盡可能使用 ImageBitmapLoader。請注意，圖像位圖在不再被引用時不會自動被 GC 收集，并且在處置過程中需要特殊處理。有關(guān)如何處理對象指南中的更多信息。

擴展

GLTFLoader支持下列g(shù)lTF 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 槽應(yīng)用于紋理的變換（除 aoMap 和 lightMap 之外的所有紋理）必須共享相同的變換，或者根本沒有變換。 aoMap 和 lightMap 紋理不能被變換。每個材質(zhì)最多只能使用一次變換。 請參閱#13831 和 #12788。

³您也可以在應(yīng)用程序加載后手動處理擴展。 查看 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顏色空間，而頂點顏色和材質(zhì)屬性（.color, .emissive, .specular） 則使用線性顏色空間。在典型的渲染工作流程中，紋理會被渲染器轉(zhuǎn)換為線性顏色空間，進行光照計算，然后最終輸出會被轉(zhuǎn)換回 sRGB 顏色空間并顯示在屏幕上。除非你需要使用線性顏色空間進行后期處理，否則請在使用glTF的時候?qū)ebGLRenderer進行如下配置：

renderer.outputEncoding = THREE.sRGBEncoding;

假設(shè)渲染器的配置如上所示，則GLTFLoader將可以正確地自動配置從.gltf或.glb文件中引用的紋理。 當從外部加載紋理（例如，使用TextureLoader）并將紋理應(yīng)用到glTF模型，則必須給定對應(yīng)的顏色空間與朝向：

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

自定義擴展

來自未知擴展的元數(shù)據(jù)會被保存到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 ) { ... } );

} );

構(gòu)造函數(shù)

GLTFLoader( manager : LoadingManager )

manager — 該加載器將要使用的 loadingManager 。默認為 THREE.DefaultLoadingManager。

創(chuàng)建一個新的GLTFLoader。

屬性

共有屬性請參見其基類Loader。

方法

共有方法請參見其基類Loader。

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

url — 包含有.gltf/.glb文件路徑/URL的字符串。
onLoad — 加載成功完成后將會被調(diào)用的函數(shù)。該函數(shù)接收parse所返回的已加載的JSON響應(yīng)。
onProgress — （可選）加載正在進行過程中會被調(diào)用的函數(shù)。其參數(shù)將會是XMLHttpRequest實例，包含有總字節(jié)數(shù).total與已加載的字節(jié)數(shù).loaded。
onError — （可選）若在加載過程發(fā)生錯誤，將被調(diào)用的函數(shù)。該函數(shù)接收error來作為參數(shù)。

開始從url加載，并使用解析過的響應(yīng)內(nèi)容調(diào)用回調(diào)函數(shù)。

.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 — 用于找到后續(xù)glTF資源（如紋理和.bin數(shù)據(jù)文件）的基礎(chǔ)路徑。
onLoad — 解析成功完成后將會被調(diào)用的函數(shù)。
onError — （可選）若在解析過程發(fā)生錯誤，將被調(diào)用的函數(shù)。該函數(shù)接收error來作為參數(shù)。

解析基于glTF的ArrayBuffer或JSON字符串，并在完成后觸發(fā)onLoad回調(diào)。onLoad的參數(shù)將是一個包含有已加載部分的Object：.scene、 .scenes、 .cameras、 .animations 和 .asset。

源代碼

examples/jsm/loaders/GLTFLoader.js