Merge pull request #17675 from WestLangley/dev_sprite_alphamap

SpriteMaterial: add alphaMap support

Author: WestLangley

docs/api/en/materials/SpriteMaterial.html

@@ -50,6 +50,17 @@ <h3>[name]( [param:Object parameters] )</h3>
 		<h2>Properties</h2>
 		<p>See the base [page:Material] class for common properties.</p>
 
+		<h3>[property:Texture alphaMap]</h3>
+		<p>The alpha map is a grayscale texture that controls the opacity across the surface
+			(black: fully transparent; white: fully opaque). Default is null.<br /><br />
+
+			Only the color of the texture is used, ignoring the alpha channel if one exists.
+			For RGB and RGBA textures, the [page:WebGLRenderer WebGL] renderer will use the
+			green channel when sampling this texture due to the extra bit of precision provided
+			for green in DXT-compressed and uncompressed RGB 565 formats. Luminance-only and
+			luminance/alpha textures will also still work as expected.
+		</p>
+
 		<h3>[property:Color color]</h3>
 		<p>[page:Color] of the material, by default set to white (0xffffff). The [page:.map] is mutiplied by the color.</p>
 

src/materials/SpriteMaterial.d.ts

@@ -5,6 +5,7 @@ import { MaterialParameters, Material } from './Material';
 export interface SpriteMaterialParameters extends MaterialParameters {
 	color?: Color | string | number;
 	map?: Texture | null;
+	alphaMap?: Texture | null;
 	rotation?: number;
 	sizeAttenuation?: boolean;
 }
@@ -15,6 +16,7 @@ export class SpriteMaterial extends Material {
 
 	color: Color;
 	map: Texture | null;
+	alphaMap: Texture | null;
 	rotation: number;
 	sizeAttenuation: boolean;
 	isSpriteMaterial: true;

src/materials/SpriteMaterial.js

@@ -7,6 +7,7 @@ import { Color } from '../math/Color.js';
  * parameters = {
  *  color: <hex>,
  *  map: new THREE.Texture( <Image> ),
+ *  alphaMap: new THREE.Texture( <Image> ),
  *  rotation: <float>,
  *  sizeAttenuation: <bool>
  * }
@@ -19,8 +20,11 @@ function SpriteMaterial( parameters ) {
 	this.type = 'SpriteMaterial';
 
 	this.color = new Color( 0xffffff );
+
 	this.map = null;
 
+	this.alphaMap = null;
+
 	this.rotation = 0;
 
 	this.sizeAttenuation = true;
@@ -40,8 +44,11 @@ SpriteMaterial.prototype.copy = function ( source ) {
 	Material.prototype.copy.call( this, source );
 
 	this.color.copy( source.color );
+
 	this.map = source.map;
 
+	this.alphaMap = source.alphaMap;
+
 	this.rotation = source.rotation;
 
 	this.sizeAttenuation = source.sizeAttenuation;

src/renderers/WebGLRenderer.js

@@ -2202,17 +2202,44 @@ function WebGLRenderer( parameters ) {
 		uniforms.diffuse.value.copy( material.color );
 		uniforms.opacity.value = material.opacity;
 		uniforms.rotation.value = material.rotation;
-		uniforms.map.value = material.map;
 
-		if ( material.map !== null ) {
+		if ( material.map ) {
 
-			if ( material.map.matrixAutoUpdate === true ) {
+			uniforms.map.value = material.map;
 
-				material.map.updateMatrix();
+		}
+
+		if ( material.alphaMap ) {
+
+			uniforms.alphaMap.value = material.alphaMap;
+
+		}
+
+		// uv repeat and offset setting priorities
+		// 1. color map
+		// 2. alpha map
+
+		var uvScaleMap;
+
+		if ( material.map ) {
+
+			uvScaleMap = material.map;
+
+		} else if ( material.alphaMap ) {
+
+			uvScaleMap = material.alphaMap;
+
+		}
+
+		if ( uvScaleMap !== undefined ) {
+
+			if ( uvScaleMap.matrixAutoUpdate === true ) {
+
+				uvScaleMap.updateMatrix();
 
 			}
 
-			uniforms.uvTransform.value.copy( material.map.matrix );
+			uniforms.uvTransform.value.copy( uvScaleMap.matrix );
 
 		}
 

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

@@ -5,6 +5,7 @@ uniform float opacity;
 #include <common>
 #include <uv_pars_fragment>
 #include <map_pars_fragment>
+#include <alphamap_pars_fragment>
 #include <fog_pars_fragment>
 #include <logdepthbuf_pars_fragment>
 #include <clipping_planes_pars_fragment>
@@ -18,6 +19,7 @@ void main() {
 
 	#include <logdepthbuf_fragment>
 	#include <map_fragment>
+	#include <alphamap_fragment>
 	#include <alphatest_fragment>
 
 	outgoingLight = diffuseColor.rgb;

src/renderers/shaders/UniformsLib.js

@@ -193,6 +193,7 @@ var UniformsLib = {
 		center: { value: new Vector2( 0.5, 0.5 ) },
 		rotation: { value: 0.0 },
 		map: { value: null },
+		alphaMap: { value: null },
 		uvTransform: { value: new Matrix3() }
 
 	}