BlendModes: Added `blend*` prefix (#29897)

* Rename `BlendMode` -> `BlendModes`

* Added `blend` prefix

* update examples

* improve warning message

* rename `blendNormal` -> `blendColor`

* move 'blendColor' to Porter Duff formula

examples/webgpu_backdrop.html

@@ -25,7 +25,7 @@
 		<script type="module">
 
 			import * as THREE from 'three';
-			import { float, vec3, color, viewportSharedTexture, hue, overlay, posterize, grayscale, saturation, viewportSafeUV, screenUV, checker, uv, time, oscSine, output } from 'three/tsl';
+			import { float, vec3, color, viewportSharedTexture, hue, blendOverlay, posterize, grayscale, saturation, viewportSafeUV, screenUV, checker, uv, time, oscSine, output } from 'three/tsl';
 
 			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
 
@@ -106,7 +106,7 @@
 				addBackdropSphere( viewportSharedTexture().rgb.oneMinus() );
 				addBackdropSphere( grayscale( viewportSharedTexture().rgb ) );
 				addBackdropSphere( saturation( viewportSharedTexture().rgb, 10 ), oscSine() );
-				addBackdropSphere( overlay( viewportSharedTexture().rgb, checker( uv().mul( 10 ) ) ) );
+				addBackdropSphere( blendOverlay( viewportSharedTexture().rgb, checker( uv().mul( 10 ) ) ) );
 				addBackdropSphere( viewportSharedTexture( viewportSafeUV( screenUV.mul( 40 ).floor().div( 40 ) ) ) );
 				addBackdropSphere( viewportSharedTexture( viewportSafeUV( screenUV.mul( 80 ).floor().div( 80 ) ) ).add( color( 0x0033ff ) ) );
 				addBackdropSphere( vec3( 0, 0, viewportSharedTexture().b ) );

examples/webgpu_parallax_uv.html

@@ -27,7 +27,7 @@
 		<script type="module">
 
 			import * as THREE from 'three';
-			import { texture, parallaxUV, overlay, uv } from 'three/tsl';
+			import { texture, parallaxUV, blendOverlay, uv } from 'three/tsl';
 
 			import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
 
@@ -89,7 +89,7 @@
 				const parallaxUVOffset = parallaxUV( uv(), offsetUV );
 				const parallaxResult = texture( bottomTexture, parallaxUVOffset );
 
-				const iceNode = overlay( texture( topTexture ), parallaxResult );
+				const iceNode = blendOverlay( texture( topTexture ), parallaxResult );
 
 				// material
 

examples/webgpu_postprocessing_ssr.html

@@ -28,7 +28,7 @@
 
 	<script type="module">
 		import * as THREE from 'three';
-		import { pass, mrt, output, transformedNormalView, metalness, blendNormal, screenUV, color } from 'three/tsl';
+		import { pass, mrt, output, transformedNormalView, metalness, blendColor, screenUV, color } from 'three/tsl';
 		import { ssr } from 'three/addons/tsl/display/SSRNode.js';
 
 		import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
@@ -107,7 +107,7 @@
 
 			// blend SSR over beauty
 		
-			const outputNode = blendNormal( scenePassColor, ssrPass );
+			const outputNode = blendColor( scenePassColor, ssrPass );
 
 			postProcessing.outputNode = outputNode;
 

src/nodes/TSL.js

@@ -84,7 +84,7 @@ export * from './accessors/UserDataNode.js';
 export * from './accessors/VelocityNode.js';
 
 // display
-export * from './display/BlendMode.js';
+export * from './display/BlendModes.js';
 export * from './display/BumpMapNode.js';
 export * from './display/ColorAdjustment.js';
 export * from './display/ColorSpaceNode.js';

src/nodes/display/BlendMode.js

@@ -1,67 +0,0 @@
-import { Fn, vec4 } from '../tsl/TSLBase.js';
-import { mix, min, step } from '../math/MathNode.js';
-
-export const burn = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
-
-	return min( 1.0, base.oneMinus().div( blend ) ).oneMinus();
-
-} ).setLayout( {
-	name: 'burnBlend',
-	type: 'vec3',
-	inputs: [
-		{ name: 'base', type: 'vec3' },
-		{ name: 'blend', type: 'vec3' }
-	]
-} );
-
-export const dodge = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
-
-	return min( base.div( blend.oneMinus() ), 1.0 );
-
-} ).setLayout( {
-	name: 'dodgeBlend',
-	type: 'vec3',
-	inputs: [
-		{ name: 'base', type: 'vec3' },
-		{ name: 'blend', type: 'vec3' }
-	]
-} );
-
-export const screen = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
-
-	return base.oneMinus().mul( blend.oneMinus() ).oneMinus();
-
-} ).setLayout( {
-	name: 'screenBlend',
-	type: 'vec3',
-	inputs: [
-		{ name: 'base', type: 'vec3' },
-		{ name: 'blend', type: 'vec3' }
-	]
-} );
-
-export const overlay = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
-
-	return mix( base.mul( 2.0 ).mul( blend ), base.oneMinus().mul( 2.0 ).mul( blend.oneMinus() ).oneMinus(), step( 0.5, base ) );
-
-} ).setLayout( {
-	name: 'overlayBlend',
-	type: 'vec3',
-	inputs: [
-		{ name: 'base', type: 'vec3' },
-		{ name: 'blend', type: 'vec3' }
-	]
-} );
-
-export const blendNormal = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
-
-	return vec4( base.rgb.mul( blend.a.oneMinus() ).add( blend.rgb.mul( blend.a ) ), base.a );
-
-} ).setLayout( {
-	name: 'blendNormal',
-	type: 'vec4',
-	inputs: [
-		{ name: 'base', type: 'vec4' },
-		{ name: 'blend', type: 'vec4' }
-	]
-} );

src/nodes/display/BlendModes.js

@@ -0,0 +1,99 @@
+import { Fn, vec4 } from '../tsl/TSLBase.js';
+import { mix, min, step } from '../math/MathNode.js';
+
+export const blendBurn = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
+
+	return min( 1.0, base.oneMinus().div( blend ) ).oneMinus();
+
+} ).setLayout( {
+	name: 'blendBurn',
+	type: 'vec3',
+	inputs: [
+		{ name: 'base', type: 'vec3' },
+		{ name: 'blend', type: 'vec3' }
+	]
+} );
+
+export const blendDodge = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
+
+	return min( base.div( blend.oneMinus() ), 1.0 );
+
+} ).setLayout( {
+	name: 'blendDodge',
+	type: 'vec3',
+	inputs: [
+		{ name: 'base', type: 'vec3' },
+		{ name: 'blend', type: 'vec3' }
+	]
+} );
+
+export const blendScreen = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
+
+	return base.oneMinus().mul( blend.oneMinus() ).oneMinus();
+
+} ).setLayout( {
+	name: 'blendScreen',
+	type: 'vec3',
+	inputs: [
+		{ name: 'base', type: 'vec3' },
+		{ name: 'blend', type: 'vec3' }
+	]
+} );
+
+export const blendOverlay = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
+
+	return mix( base.mul( 2.0 ).mul( blend ), base.oneMinus().mul( 2.0 ).mul( blend.oneMinus() ).oneMinus(), step( 0.5, base ) );
+
+} ).setLayout( {
+	name: 'blendOverlay',
+	type: 'vec3',
+	inputs: [
+		{ name: 'base', type: 'vec3' },
+		{ name: 'blend', type: 'vec3' }
+	]
+} );
+
+export const blendColor = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
+
+	const outAlpha = blend.a.add( base.a.mul( blend.a.oneMinus() ) );
+
+	return vec4( blend.rgb.mul( blend.a ).add( base.rgb.mul( base.a ).mul( blend.a.oneMinus() ) ).div( outAlpha ), outAlpha );
+
+} ).setLayout( {
+	name: 'blendColor',
+	type: 'vec4',
+	inputs: [
+		{ name: 'base', type: 'vec4' },
+		{ name: 'blend', type: 'vec4' }
+	]
+} );
+
+// deprecated
+
+export const burn = ( ...params ) => { // @deprecated, r171
+
+	console.warn( 'THREE.TSL: "burn" has been renamed. Use "blendBurn" instead.' );
+	return blendBurn( params );
+
+};
+
+export const dodge = ( ...params ) => { // @deprecated, r171
+
+	console.warn( 'THREE.TSL: "dodge" has been renamed. Use "blendDodge" instead.' );
+	return blendDodge( params );
+
+};
+
+export const screen = ( ...params ) => { // @deprecated, r171
+
+	console.warn( 'THREE.TSL: "screen" has been renamed. Use "blendScreen" instead.' );
+	return blendScreen( params );
+
+};
+
+export const overlay = ( ...params ) => { // @deprecated, r171
+
+	console.warn( 'THREE.TSL: "overlay" has been renamed. Use "blendOverlay" instead.' );
+	return blendOverlay( params );
+
+};