Add "alphaMask" option for ImageOverlays (#1372)

* Add support for using an overlay layer as a mask

* Update dts

* Remove alphaTest option

* Use #defines

* Revert "Use #defines"

This reverts commit 1a0ba67.

Author: gkjohnson

src/three/plugins/images/ImageOverlayPlugin.d.ts

@@ -8,6 +8,8 @@ export class ImageOverlayPlugin {
 		renderer: WebGLRenderer,
 		resolution?: number,
 		enableTileSplitting?: boolean,
+		alphaMask?: boolean,			// false = fade to the layer below, true = use only alpha to fade all layers underneath
+		alphaInvert?: boolean, 			// false = cut inside (keep outside); true = cut outside (keep inside)
 	} );
 
 	addOverlay( overlay: ImageOverlay, order?: number ): void;

src/three/plugins/images/ImageOverlayPlugin.js

@@ -1319,11 +1319,11 @@ export class ImageOverlayPlugin {
 
 				// set the uniform array lengths
 				params.layerMaps.length = overlays.length;
-				params.layerColor.length = overlays.length;
+				params.layerInfo.length = overlays.length;
 
 				// assign the uniforms
 				params.layerMaps.value[ i ] = target !== null ? target.texture : null;
-				params.layerColor.value[ i ] = overlay;
+				params.layerInfo.value[ i ] = overlay;
 
 				material.defines.LAYER_COUNT = overlays.length;
 				material.needsUpdate = true;
@@ -1420,13 +1420,18 @@ class ImageOverlay {
 			color = 0xffffff,
 			frame = null,
 			preprocessURL = null,
+			alphaMask = false,
+			alphaInvert = false,
 		} = options;
 		this.imageSource = null;
 
 		this.preprocessURL = preprocessURL;
 		this.opacity = opacity;
 		this.color = new Color( color );
 		this.frame = frame !== null ? frame.clone() : null;
+		this.alphaMask = alphaMask;
+		this.alphaInvert = alphaInvert;
+
 		this.isReady = false;
 		this.isInitialized = false;
 

src/three/plugins/images/overlays/wrapOverlaysMaterial.js

@@ -12,7 +12,7 @@ export function wrapOverlaysMaterial( material, previousOnBeforeCompile ) {
 
 	const params = {
 		layerMaps: { value: [] },
-		layerColor: { value: [] },
+		layerInfo: { value: [] },
 	};
 
 	material[ OVERLAY_PARAMS ] = params;
@@ -74,13 +74,16 @@ export function wrapOverlaysMaterial( material, previousOnBeforeCompile ) {
 			.replace( /void main\(/, value => /* glsl */`
 
 				#if LAYER_COUNT != 0
-					struct LayerTint {
+					struct LayerInfo {
 						vec3 color;
 						float opacity;
+
+						int alphaMask;
+						int alphaInvert;
 					};
 
 					uniform sampler2D layerMaps[ LAYER_COUNT ];
-					uniform LayerTint layerColor[ LAYER_COUNT ];
+					uniform LayerInfo layerInfo[ LAYER_COUNT ];
 				#endif
 
 				#pragma unroll_loop_start
@@ -126,11 +129,27 @@ export function wrapOverlaysMaterial( material, previousOnBeforeCompile ) {
 									smoothstep( 1.0 + wDelta, 1.0, layerUV.z );
 
 								// apply tint & opacity
-								tint.rgb *= layerColor[ i ].color;
-								tint.rgba *= layerColor[ i ].opacity * wOpacity;
+								tint.rgb *= layerInfo[ i ].color;
+								tint.rgba *= layerInfo[ i ].opacity * wOpacity;
+
+								// invert the alpha
+								if ( layerInfo[ i ].alphaInvert > 0 ) {
+
+									tint.a = 1.0 - tint.a;
+
+								}
+
+								// apply the alpha across all existing layers if alpha mask is true
+								if ( layerInfo[ i ].alphaMask > 0 ) {
+
+									diffuseColor.a *= tint.a;
+
+								} else {
+
+									// premultiplied alpha equation
+									diffuseColor = tint + diffuseColor * ( 1.0 - tint.a );
 
-								// premultiplied alpha equation
-								diffuseColor = tint + diffuseColor * ( 1.0 - tint.a );
+								}
 
 							#endif