Introduce scene.backgroundIntensity (mrdoob#24876)

Author: WestLangley

Diff for: docs/api/en/scenes/Scene.html

@@ -40,6 +40,11 @@ <h3>[property:Float backgroundBlurriness]</h3>
 			Sets the blurriness of the background. Only influences environment maps assigned to [page:Scene.background]. Valid input is a float between *0* and *1*. Default is *0*.
 		</p>
 
+		<h3>[property:Float backgroundIntensity]</h3>
+		<p>
+			Attenuates the color of the background. Only applies to background textures. Default is *1*.
+		</p>
+
 		<h3>[property:Texture environment]</h3>
 		<p>
 		Sets the environment map for all physical materials in the scene.

Diff for: src/renderers/shaders/ShaderLib.js

@@ -218,6 +218,7 @@ const ShaderLib = {
 		uniforms: {
 			uvTransform: { value: /*@__PURE__*/ new Matrix3() },
 			t2D: { value: null },
+			backgroundIntensity: { value: 1 }
 		},
 
 		vertexShader: ShaderChunk.background_vert,
@@ -230,7 +231,8 @@ const ShaderLib = {
 		uniforms: {
 			envMap: { value: null },
 			flipEnvMap: { value: - 1 },
-			backgroundBlurriness: { value: 0 }
+			backgroundBlurriness: { value: 0 },
+			backgroundIntensity: { value: 1 }
 		},
 
 		vertexShader: ShaderChunk.backgroundCube_vert,

Diff for: src/renderers/shaders/ShaderLib/background.glsl.js

@@ -13,21 +13,26 @@ void main() {
 
 export const fragment = /* glsl */`
 uniform sampler2D t2D;
+uniform float backgroundIntensity;
 
 varying vec2 vUv;
 
 void main() {
 
-	gl_FragColor = texture2D( t2D, vUv );
+	vec4 texColor = texture2D( t2D, vUv );
 
 	#ifdef DECODE_VIDEO_TEXTURE
 
 		// inline sRGB decode (TODO: Remove this code when https://crbug.com/1256340 is solved)
 
-		gl_FragColor = vec4( mix( pow( gl_FragColor.rgb * 0.9478672986 + vec3( 0.0521327014 ), vec3( 2.4 ) ), gl_FragColor.rgb * 0.0773993808, vec3( lessThanEqual( gl_FragColor.rgb, vec3( 0.04045 ) ) ) ), gl_FragColor.w );
+		texColor = vec4( mix( pow( texColor.rgb * 0.9478672986 + vec3( 0.0521327014 ), vec3( 2.4 ) ), texColor.rgb * 0.0773993808, vec3( lessThanEqual( texColor.rgb, vec3( 0.04045 ) ) ) ), texColor.w );
 
 	#endif
 
+	texColor.rgb *= backgroundIntensity;
+
+	gl_FragColor = texColor;
+
 	#include <tonemapping_fragment>
 	#include <encodings_fragment>
 

Diff for: src/renderers/shaders/ShaderLib/backgroundCube.glsl.js

@@ -29,6 +29,7 @@ export const fragment = /* glsl */`
 
 uniform float flipEnvMap;
 uniform float backgroundBlurriness;
+uniform float backgroundIntensity;
 
 varying vec3 vWorldDirection;
 
@@ -50,6 +51,8 @@ void main() {
 
 	#endif
 
+	texColor.rgb *= backgroundIntensity;
+
 	gl_FragColor = texColor;
 
 	#include <tonemapping_fragment>

Diff for: src/renderers/webgl/WebGLBackground.js

@@ -105,6 +105,7 @@ function WebGLBackground( renderer, cubemaps, cubeuvmaps, state, objects, alpha,
 			boxMesh.material.uniforms.envMap.value = background;
 			boxMesh.material.uniforms.flipEnvMap.value = ( background.isCubeTexture && background.isRenderTargetTexture === false ) ? - 1 : 1;
 			boxMesh.material.uniforms.backgroundBlurriness.value = scene.backgroundBlurriness;
+			boxMesh.material.uniforms.backgroundIntensity.value = scene.backgroundIntensity;
 
 			if ( currentBackground !== background ||
 				currentBackgroundVersion !== background.version ||
@@ -159,6 +160,7 @@ function WebGLBackground( renderer, cubemaps, cubeuvmaps, state, objects, alpha,
 			}
 
 			planeMesh.material.uniforms.t2D.value = background;
+			planeMesh.material.uniforms.backgroundIntensity.value = scene.backgroundIntensity;
 
 			if ( background.matrixAutoUpdate === true ) {
 

Diff for: src/scenes/Scene.js

@@ -15,6 +15,7 @@ class Scene extends Object3D {
 		this.fog = null;
 
 		this.backgroundBlurriness = 0;
+		this.backgroundIntensity = 1;
 
 		this.overrideMaterial = null;
 
@@ -35,6 +36,7 @@ class Scene extends Object3D {
 		if ( source.fog !== null ) this.fog = source.fog.clone();
 
 		this.backgroundBlurriness = source.backgroundBlurriness;
+		this.backgroundIntensity = source.backgroundIntensity;
 
 		if ( source.overrideMaterial !== null ) this.overrideMaterial = source.overrideMaterial.clone();
 
@@ -50,6 +52,7 @@ class Scene extends Object3D {
 
 		if ( this.fog !== null ) data.object.fog = this.fog.toJSON();
 		if ( this.backgroundBlurriness > 0 ) data.backgroundBlurriness = this.backgroundBlurriness;
+		if ( this.backgroundIntensity !== 1 ) data.backgroundIntensity = this.backgroundIntensity;
 
 		return data;