Merge pull request #19690 from donmccurdy/feat-gltfloader-transmission

MeshPhysicalMaterial: Rename .transparency → .transmission, add .transmissionMap

docs/api/en/materials/MeshPhysicalMaterial.html

@@ -24,7 +24,7 @@
 			</li>
 			<li>
 				<b>Physically-based transparency:</b> One limitation of [page:Material.opacity .opacity] is
-				that highly transparent materials are less reflective. Physically-based [page:.transparency]
+				that highly transparent materials are less reflective. Physically-based [page:.transmission]
 				provides a more realistic option for thin, transparent surfaces like glass.
 			</li>
 			<li>
@@ -62,7 +62,7 @@
 			[example:webgl_materials_variations_physical materials / variations / physical]<br />
 			[example:webgl_materials_physical_clearcoat materials / physical / clearcoat]<br />
 			[example:webgl_materials_physical_reflectivity materials / physical / reflectivity]<br />
-			[example:webgl_materials_physical_transparency materials / physical / transparency]
+			[example:webgl_materials_physical_transmission materials / physical / transmission]
 		</p>
 
 		<h2>Constructor</h2>
@@ -128,15 +128,21 @@
 		This models the reflectivity of non-metallic materials. It has no effect when [page:MeshStandardMaterial.metalness metalness] is *1.0*
 		</p>
 
-		<h3>[property:Float transparency]</h3>
+		<h3>[property:Float transmission]</h3>
 		<p>
-		Degree of transparency, from *0.0* to *1.0*. Default is *0.0*.<br />
+		Degree of transmission (or optical transparency), from *0.0* to *1.0*. Default is *0.0*.<br />
 
-		Thin, transparent or semitransparent, plastic or glass materials remain largely reflective even if they are mostly transparent.
+		Thin, transparent or semitransparent, plastic or glass materials remain largely reflective even if they are fully transmissive.
 
-		The transparency property can be used to model these materials.<br />
+		The transmission property can be used to model these materials.<br />
 
-		When transparency is non-zero, [page:Material.opacity opacity] should be set to *1*.
+		When transmission is non-zero, [page:Material.opacity opacity] should be set to *1*.
+		</p>
+
+		<h3>[property:Texture transmissionMap]</h3>
+		<p>
+			The red channel of this texture is multiplied against [page:.transmission], for per-pixel control
+			over optical transparency. Default is *null*.
 		</p>
 
 		<h2>Methods</h2>

docs/api/zh/materials/MeshPhysicalMaterial.html

@@ -24,7 +24,7 @@
 			</li>
 			<li>
 				<b>Physically-based transparency:</b> One limitation of [page:Material.opacity .opacity] is
-				that highly transparent materials are less reflective. Physically-based [page:.transparency]
+				that highly transparent materials are less reflective. Physically-based [page:.transmission]
 				provides a more realistic option for thin, transparent surfaces like glass.
 			</li>
 			<li>
@@ -63,7 +63,7 @@
 			[example:webgl_materials_variations_physical materials / variations / physical]<br />
 			[example:webgl_materials_physical_clearcoat materials / physical / clearcoat]<br />
 			[example:webgl_materials_physical_reflectivity materials / physical / reflectivity]<br />
-			[example:webgl_materials_physical_transparency materials / physical / transparency]
+			[example:webgl_materials_physical_transmission materials / physical / transmission]
 		</p>
 
 		<h2>构造函数(Constructor)</h2>
@@ -123,15 +123,21 @@
 			这模拟了非金属材质的反射率。当[page:MeshStandardMaterial]为*1.0*时，此属性无效。
 		</p>
 
-		<h3>[property:Float transparency]</h3>
+		<h3>[property:Float transmission]</h3>
 		<p>
-		Degree of transparency, from *0.0* to *1.0*. Default is *0.0*.<br />
+		Degree of transmission (or optical transparency), from *0.0* to *1.0*. Default is *0.0*.<br />
 
-		Thin, transparent or semitransparent, plastic or glass materials remain largely reflective even if they are mostly transparent.
+		Thin, transparent or semitransparent, plastic or glass materials remain largely reflective even if they are fully transmissive.
 
-		The transparency property can be used to model these materials.<br />
+		The transmission property can be used to model these materials.<br />
 
-		When transparency is non-zero, [page:Material.opacity opacity] should be set to *1*.
+		When transmission is non-zero, [page:Material.opacity opacity] should be set to *1*.
+		</p>
+
+		<h3>[property:Texture transmissionMap]</h3>
+		<p>
+			The red channel of this texture is multiplied against [page:.transmission], for per-pixel control
+			over optical transparency. Default is *null*.
 		</p>
 
 		<h2>方法(Methods)</h2>

examples/files.js

@@ -156,7 +156,7 @@ var files = {
 		"webgl_materials_physical_clearcoat",
 		"webgl_materials_physical_reflectivity",
 		"webgl_materials_physical_sheen",
-		"webgl_materials_physical_transparency",
+		"webgl_materials_physical_transmission",
 		"webgl_materials_shaders_fresnel",
 		"webgl_materials_standard",
 		"webgl_materials_subsurface_scattering",

examples/js/loaders/GLTFLoader.js

@@ -19,6 +19,7 @@ THREE.GLTFLoader = ( function () {
 		this.ktx2Loader = null;
 
 		this.pluginCallbacks = [];
+
 		this.register( function ( parser ) {
 
 			return new GLTFMaterialsClearcoatExtension( parser );
@@ -30,6 +31,12 @@ THREE.GLTFLoader = ( function () {
 
 		} );
 
+		this.register( function ( parser ) {
+
+			return new GLTFMaterialsTransmissionExtension( parser );
+
+		} );
+
 	}
 
 	GLTFLoader.prototype = Object.assign( Object.create( THREE.Loader.prototype ), {
@@ -332,6 +339,7 @@ THREE.GLTFLoader = ( function () {
 		KHR_LIGHTS_PUNCTUAL: 'KHR_lights_punctual',
 		KHR_MATERIALS_CLEARCOAT: 'KHR_materials_clearcoat',
 		KHR_MATERIALS_PBR_SPECULAR_GLOSSINESS: 'KHR_materials_pbrSpecularGlossiness',
+		KHR_MATERIALS_TRANSMISSION: 'KHR_materials_transmission',
 		KHR_MATERIALS_UNLIT: 'KHR_materials_unlit',
 		KHR_TEXTURE_BASISU: 'KHR_texture_basisu',
 		KHR_TEXTURE_TRANSFORM: 'KHR_texture_transform',
@@ -551,6 +559,56 @@ THREE.GLTFLoader = ( function () {
 
 	};
 
+	/**
+	 * Transmission Materials Extension
+	 *
+	 * Specification: https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_materials_transmission
+	 * Draft: https://github.com/KhronosGroup/glTF/pull/1698
+	 */
+	function GLTFMaterialsTransmissionExtension( parser ) {
+
+		this.parser = parser;
+		this.name = EXTENSIONS.KHR_MATERIALS_TRANSMISSION;
+
+	}
+
+	GLTFMaterialsTransmissionExtension.prototype.getMaterialType = function ( /* materialIndex */ ) {
+
+		return THREE.MeshPhysicalMaterial;
+
+	};
+
+	GLTFMaterialsTransmissionExtension.prototype.extendMaterialParams = function ( materialIndex, materialParams ) {
+
+		var parser = this.parser;
+		var materialDef = parser.json.materials[ materialIndex ];
+
+		if ( ! materialDef.extensions || ! materialDef.extensions[ this.name ] ) {
+
+			return Promise.resolve();
+
+		}
+
+		var pending = [];
+
+		var extension = materialDef.extensions[ this.name ];
+
+		if ( extension.transmissionFactor !== undefined ) {
+
+			materialParams.transmission = extension.transmissionFactor;
+
+		}
+
+		if ( extension.transmissionTexture !== undefined ) {
+
+			pending.push( parser.assignTexture( materialParams, 'transmissionMap', extension.transmissionTexture ) );
+
+		}
+
+		return Promise.all( pending );
+
+	};
+
 	/**
 	 * BasisU Texture Extension
 	 *

examples/jsm/loaders/GLTFLoader.js

@@ -84,6 +84,7 @@ var GLTFLoader = ( function () {
 		this.ktx2Loader = null;
 
 		this.pluginCallbacks = [];
+
 		this.register( function ( parser ) {
 
 			return new GLTFMaterialsClearcoatExtension( parser );
@@ -95,6 +96,12 @@ var GLTFLoader = ( function () {
 
 		} );
 
+		this.register( function ( parser ) {
+
+			return new GLTFMaterialsTransmissionExtension( parser );
+
+		} );
+
 	}
 
 	GLTFLoader.prototype = Object.assign( Object.create( Loader.prototype ), {
@@ -397,6 +404,7 @@ var GLTFLoader = ( function () {
 		KHR_LIGHTS_PUNCTUAL: 'KHR_lights_punctual',
 		KHR_MATERIALS_CLEARCOAT: 'KHR_materials_clearcoat',
 		KHR_MATERIALS_PBR_SPECULAR_GLOSSINESS: 'KHR_materials_pbrSpecularGlossiness',
+		KHR_MATERIALS_TRANSMISSION: 'KHR_materials_transmission',
 		KHR_MATERIALS_UNLIT: 'KHR_materials_unlit',
 		KHR_TEXTURE_BASISU: 'KHR_texture_basisu',
 		KHR_TEXTURE_TRANSFORM: 'KHR_texture_transform',
@@ -616,6 +624,55 @@ var GLTFLoader = ( function () {
 
 	};
 
+	/**
+	 * Transmission Materials Extension
+	 *
+	 * Specification: https://github.com/KhronosGroup/glTF/tree/master/extensions/2.0/Khronos/KHR_materials_transmission
+	 */
+	function GLTFMaterialsTransmissionExtension( parser ) {
+
+		this.parser = parser;
+		this.name = EXTENSIONS.KHR_MATERIALS_TRANSMISSION;
+
+	}
+
+	GLTFMaterialsTransmissionExtension.prototype.getMaterialType = function ( /* materialIndex */ ) {
+
+		return MeshPhysicalMaterial;
+
+	};
+
+	GLTFMaterialsTransmissionExtension.prototype.extendMaterialParams = function ( materialIndex, materialParams ) {
+
+		var parser = this.parser;
+		var materialDef = parser.json.materials[ materialIndex ];
+
+		if ( ! materialDef.extensions || ! materialDef.extensions[ this.name ] ) {
+
+			return Promise.resolve();
+
+		}
+
+		var pending = [];
+
+		var extension = materialDef.extensions[ this.name ];
+
+		if ( extension.transmissionFactor !== undefined ) {
+
+			materialParams.transmission = extension.transmissionFactor;
+
+		}
+
+		if ( extension.transmissionTexture !== undefined ) {
+
+			pending.push( parser.assignTexture( materialParams, 'transmissionMap', extension.transmissionTexture ) );
+
+		}
+
+		return Promise.all( pending );
+
+	};
+
 	/**
 	 * BasisU Texture Extension
 	 *

examples/webgl_materials_physical_transparency.html → examples/webgl_materials_physical_transmission.html

@@ -1,7 +1,7 @@
 <!DOCTYPE html>
 <html lang="en">
 	<head>
-		<title>threejs webgl - materials - transparency</title>
+		<title>threejs webgl - materials - transmission</title>
 		<meta charset="utf-8">
 		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
 		<link type="text/css" rel="stylesheet" href="main.css">
@@ -9,7 +9,7 @@
 	<body>
 
 		<div id="container"></div>
-		<div id="info"><a href="https://threejs.org" target="_blank" rel="noopener">threejs</a> - Transparency with Premultiplied Alpha (right) and without (left)</div>
+		<div id="info"><a href="https://threejs.org" target="_blank" rel="noopener">threejs</a> - Transmission with Premultiplied Alpha (right) and without (left)</div>
 
 		<script type="module">
 
@@ -23,7 +23,7 @@
 
 			var params = {
 				color: 0xffffff,
-				transparency: 0.90,
+				transmission: 0.90,
 				envMapIntensity: 1,
 				lightIntensity: 1,
 				exposure: 1
@@ -96,8 +96,8 @@
 					envMap: hdrCubeRenderTarget.texture,
 					envMapIntensity: params.envMapIntensity,
 					depthWrite: false,
-					transparency: params.transparency, // use material.transparency for glass materials
-					opacity: 1,                        // set material.opacity to 1 when material.transparency is non-zero
+					transmission: params.transmission, // use material.transmission for glass materials
+					opacity: 1,                        // set material.opacity to 1 when material.transmission is non-zero
 					transparent: true
 				} );
 
@@ -166,11 +166,11 @@
 
 					} );
 
-				gui.add( params, 'transparency', 0, 1 )
+				gui.add( params, 'transmission', 0, 1 )
 					.onChange( function () {
 
-						material1.transparency = material2.transparency = params.transparency;
-						material1b.transparency = material2b.transparency = params.transparency;
+						material1.transmission = material2.transmission = params.transmission;
+						material1b.transmission = material2b.transmission = params.transmission;
 
 					} );
 

src/loaders/MaterialLoader.js

@@ -280,6 +280,9 @@ MaterialLoader.prototype = Object.assign( Object.create( Loader.prototype ), {
 		if ( json.clearcoatNormalMap !== undefined ) material.clearcoatNormalMap = getTexture( json.clearcoatNormalMap );
 		if ( json.clearcoatNormalScale !== undefined ) material.clearcoatNormalScale = new Vector2().fromArray( json.clearcoatNormalScale );
 
+		if ( json.transmission !== undefined ) material.transmission = json.transmission;
+		if ( json.transmissionMap !== undefined ) material.transmissionMap = getTexture( json.transmissionMap );
+
 		return material;
 
 	},

src/materials/MeshPhysicalMaterial.d.ts

@@ -8,15 +8,21 @@ import { Color } from './../math/Color';
 
 export interface MeshPhysicalMaterialParameters
 	extends MeshStandardMaterialParameters {
-	reflectivity?: number;
+
 	clearcoat?: number;
+	clearcoatMap: Texture | null;
 	clearcoatRoughness?: number;
+	clearcoatRoughnessMap: Texture | null;
+	clearcoatNormalScale?: Vector2;
+	clearcoatNormalMap?: Texture | null;
+
+	reflectivity?: number;
 
 	sheen?: Color;
 
-	clearcoatNormalScale?: Vector2;
-	clearcoatNormalMap?: Texture | null;
-	transparency?: number;
+	transmission?: number;
+	transmissionMap?: Texture | null;
+
 }
 
 export class MeshPhysicalMaterial extends MeshStandardMaterial {
@@ -34,6 +40,7 @@ export class MeshPhysicalMaterial extends MeshStandardMaterial {
 
 	sheen: Color | null;
 
-	transparency: number;
+	transmission: number;
+	transmissionMap: Texture | null;
 
 }

src/materials/MeshPhysicalMaterial.js

@@ -17,7 +17,8 @@ import { Color } from '../math/Color.js';
  *
  *  sheen: <Color>,
  *
- *  transparency: <float>
+ *  transmission: <float>,
+ *  transmissionMap: new THREE.Texture( <Image> )
  * }
  */
 
@@ -45,7 +46,8 @@ function MeshPhysicalMaterial( parameters ) {
 
 	this.sheen = null; // null will disable sheen bsdf
 
-	this.transparency = 0.0;
+	this.transmission = 0.0;
+	this.transmissionMap = null;
 
 	this.setValues( parameters );
 
@@ -86,7 +88,8 @@ MeshPhysicalMaterial.prototype.copy = function ( source ) {
 
 	}
 
-	this.transparency = source.transparency;
+	this.transmission = source.transmission;
+	this.transmissionMap = source.transmissionMap;
 
 	return this;
 

src/renderers/shaders/ShaderChunk.js

@@ -86,6 +86,8 @@ import specularmap_fragment from './ShaderChunk/specularmap_fragment.glsl.js';
 import specularmap_pars_fragment from './ShaderChunk/specularmap_pars_fragment.glsl.js';
 import tonemapping_fragment from './ShaderChunk/tonemapping_fragment.glsl.js';
 import tonemapping_pars_fragment from './ShaderChunk/tonemapping_pars_fragment.glsl.js';
+import transmissionmap_fragment from './ShaderChunk/transmissionmap_fragment.glsl.js';
+import transmissionmap_pars_fragment from './ShaderChunk/transmissionmap_pars_fragment.glsl.js';
 import uv_pars_fragment from './ShaderChunk/uv_pars_fragment.glsl.js';
 import uv_pars_vertex from './ShaderChunk/uv_pars_vertex.glsl.js';
 import uv_vertex from './ShaderChunk/uv_vertex.glsl.js';
@@ -216,6 +218,8 @@ export const ShaderChunk = {
 	specularmap_pars_fragment: specularmap_pars_fragment,
 	tonemapping_fragment: tonemapping_fragment,
 	tonemapping_pars_fragment: tonemapping_pars_fragment,
+	transmissionmap_fragment: transmissionmap_fragment,
+	transmissionmap_pars_fragment: transmissionmap_pars_fragment,
 	uv_pars_fragment: uv_pars_fragment,
 	uv_pars_vertex: uv_pars_vertex,
 	uv_vertex: uv_vertex,

src/renderers/shaders/ShaderChunk/transmissionmap_fragment.glsl.js

@@ -0,0 +1,7 @@
+export default /* glsl */`
+#ifdef USE_TRANSMISSIONMAP
+
+	totalTransmission *= texture2D( transmissionMap, vUv ).r;
+
+#endif
+`;

src/renderers/shaders/ShaderChunk/transmissionmap_pars_fragment.glsl.js

@@ -0,0 +1,7 @@
+export default /* glsl */`
+#ifdef USE_TRANSMISSIONMAP
+
+	uniform sampler2D transmissionMap;
+
+#endif
+`;

src/renderers/shaders/ShaderLib.js

@@ -303,7 +303,8 @@ ShaderLib.physical = {
 			clearcoatNormalScale: { value: new Vector2( 1, 1 ) },
 			clearcoatNormalMap: { value: null },
 			sheen: { value: new Color( 0x000000 ) },
-			transparency: { value: 0 },
+			transmission: { value: 0 },
+			transmissionMap: { value: null },
 		}
 	] ),
 

src/renderers/shaders/ShaderLib/meshphysical_frag.glsl.js

@@ -4,7 +4,7 @@ export default /* glsl */`
 #ifdef PHYSICAL
 	#define REFLECTIVITY
 	#define CLEARCOAT
-	#define TRANSPARENCY
+	#define TRANSMISSION
 #endif
 
 uniform vec3 diffuse;
@@ -13,8 +13,8 @@ uniform float roughness;
 uniform float metalness;
 uniform float opacity;
 
-#ifdef TRANSPARENCY
-	uniform float transparency;
+#ifdef TRANSMISSION
+	uniform float transmission;
 #endif
 
 #ifdef REFLECTIVITY
@@ -56,6 +56,7 @@ varying vec3 vViewPosition;
 #include <aomap_pars_fragment>
 #include <lightmap_pars_fragment>
 #include <emissivemap_pars_fragment>
+#include <transmissionmap_pars_fragment>
 #include <bsdfs>
 #include <cube_uv_reflection_fragment>
 #include <envmap_common_pars_fragment>
@@ -80,6 +81,10 @@ void main() {
 	ReflectedLight reflectedLight = ReflectedLight( vec3( 0.0 ), vec3( 0.0 ), vec3( 0.0 ), vec3( 0.0 ) );
 	vec3 totalEmissiveRadiance = emissive;
 
+	#ifdef TRANSMISSION
+		float totalTransmission = transmission;
+	#endif
+
 	#include <logdepthbuf_fragment>
 	#include <map_fragment>
 	#include <color_fragment>
@@ -92,6 +97,7 @@ void main() {
 	#include <clearcoat_normal_fragment_begin>
 	#include <clearcoat_normal_fragment_maps>
 	#include <emissivemap_fragment>
+	#include <transmissionmap_fragment>
 
 	// accumulation
 	#include <lights_physical_fragment>
@@ -104,9 +110,9 @@ void main() {
 
 	vec3 outgoingLight = reflectedLight.directDiffuse + reflectedLight.indirectDiffuse + reflectedLight.directSpecular + reflectedLight.indirectSpecular + totalEmissiveRadiance;
 
-	// this is a stub for the transparency model
-	#ifdef TRANSPARENCY
-		diffuseColor.a *= saturate( 1. - transparency + linearToRelativeLuminance( reflectedLight.directSpecular + reflectedLight.indirectSpecular ) );
+	// this is a stub for the transmission model
+	#ifdef TRANSMISSION
+		diffuseColor.a *= saturate( 1. - totalTransmission + linearToRelativeLuminance( reflectedLight.directSpecular + reflectedLight.indirectSpecular ) );
 	#endif
 
 	gl_FragColor = vec4( outgoingLight, diffuseColor.a );

src/renderers/webgl/WebGLMaterials.js

@@ -566,7 +566,13 @@ function WebGLMaterials( properties ) {
 
 		}
 
-		uniforms.transparency.value = material.transparency;
+		uniforms.transmission.value = material.transmission;
+
+		if ( material.transmissionMap ) {
+
+			uniforms.transmissionMap.value = material.transmissionMap;
+
+		}
 
 	}
 

src/renderers/webgl/WebGLProgram.js

@@ -475,6 +475,7 @@ function WebGLProgram( renderer, cacheKey, parameters, bindingStates ) {
 			parameters.roughnessMap ? '#define USE_ROUGHNESSMAP' : '',
 			parameters.metalnessMap ? '#define USE_METALNESSMAP' : '',
 			parameters.alphaMap ? '#define USE_ALPHAMAP' : '',
+			parameters.transmissionMap ? '#define USE_TRANSMISSIONMAP' : '',
 
 			parameters.vertexTangents ? '#define USE_TANGENT' : '',
 			parameters.vertexColors ? '#define USE_COLOR' : '',
@@ -604,6 +605,7 @@ function WebGLProgram( renderer, cacheKey, parameters, bindingStates ) {
 			parameters.alphaMap ? '#define USE_ALPHAMAP' : '',
 
 			parameters.sheen ? '#define USE_SHEEN' : '',
+			parameters.transmissionMap ? '#define USE_TRANSMISSIONMAP' : '',
 
 			parameters.vertexTangents ? '#define USE_TANGENT' : '',
 			parameters.vertexColors ? '#define USE_COLOR' : '',

src/renderers/webgl/WebGLPrograms.js

@@ -50,7 +50,7 @@ function WebGLPrograms( renderer, extensions, capabilities, bindingStates ) {
 		"numDirLightShadows", "numPointLightShadows", "numSpotLightShadows",
 		"shadowMapEnabled", "shadowMapType", "toneMapping", 'physicallyCorrectLights',
 		"alphaTest", "doubleSided", "flipSided", "numClippingPlanes", "numClipIntersection", "depthPacking", "dithering",
-		"sheen"
+		"sheen", "transmissionMap"
 	];
 
 	function allocateBones( object ) {
@@ -206,12 +206,14 @@ function WebGLPrograms( renderer, extensions, capabilities, bindingStates ) {
 
 			sheen: !! material.sheen,
 
+			transmissionMap: !! material.transmissionMap,
+
 			combine: material.combine,
 
 			vertexTangents: ( material.normalMap && material.vertexTangents ),
 			vertexColors: material.vertexColors,
-			vertexUvs: !! material.map || !! material.bumpMap || !! material.normalMap || !! material.specularMap || !! material.alphaMap || !! material.emissiveMap || !! material.roughnessMap || !! material.metalnessMap || !! material.clearcoatMap || !! material.clearcoatRoughnessMap || !! material.clearcoatNormalMap || !! material.displacementMap,
-			uvsVertexOnly: ! ( !! material.map || !! material.bumpMap || !! material.normalMap || !! material.specularMap || !! material.alphaMap || !! material.emissiveMap || !! material.roughnessMap || !! material.metalnessMap || !! material.clearcoatNormalMap ) && !! material.displacementMap,
+			vertexUvs: !! material.map || !! material.bumpMap || !! material.normalMap || !! material.specularMap || !! material.alphaMap || !! material.emissiveMap || !! material.roughnessMap || !! material.metalnessMap || !! material.clearcoatMap || !! material.clearcoatRoughnessMap || !! material.clearcoatNormalMap || !! material.displacementMap || !! material.transmissionMap,
+			uvsVertexOnly: ! ( !! material.map || !! material.bumpMap || !! material.normalMap || !! material.specularMap || !! material.alphaMap || !! material.emissiveMap || !! material.roughnessMap || !! material.metalnessMap || !! material.clearcoatNormalMap || !! material.transmissionMap ) && !! material.displacementMap,
 
 			fog: !! fog,
 			useFog: material.fog,