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

docs/api/en/materials/MeshPhysicalMaterial.html

@@ -24,7 +24,7 @@ <h1>[name]</h1>
 			</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 @@ <h2>Examples</h2>
 			[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 @@ <h3>[property:Float reflectivity]</h3>
 		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 @@ <h1>物理网格材质([name])</h1>
 			</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 @@ <h2>例子</h2>
 			[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 @@ <h3>[property:Float reflectivity]</h3>
 			这模拟了非金属材质的反射率。当[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,15 +1,15 @@
 <!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">
 	</head>
 	<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;