From af3707391841721c185c0b2459918a3668fa0247 Mon Sep 17 00:00:00 2001 From: Mugen87 Date: Tue, 14 Jan 2025 11:57:13 +0100 Subject: [PATCH 1/2] Docs: Improve `BlendModes` module. --- src/nodes/display/BlendModes.js | 63 +++++++++++++++++++++++++++++++-- 1 file changed, 61 insertions(+), 2 deletions(-) diff --git a/src/nodes/display/BlendModes.js b/src/nodes/display/BlendModes.js index f14dcb2fe70b2f..2a12b8370481a6 100644 --- a/src/nodes/display/BlendModes.js +++ b/src/nodes/display/BlendModes.js @@ -1,6 +1,20 @@ import { Fn, vec4 } from '../tsl/TSLBase.js'; import { mix, min, step } from '../math/MathNode.js'; +/** @module BlendModes **/ + +/** + * Represents a "Color Burn" blend mode. + * + * It's designed to darken the base layer's colors based on the color of the blend layer. + * It significantly increases the contrast of the base layer, making the colors more vibrant and saturated. + * The darker the color in the blend layer, the stronger the darkening and contrast effect on the base layer. + * + * @method + * @param {Node} base - The base color. + * @param {Node} blend - The blend color. A white (#ffffff) blend color does not alter the base color. + * @return {Node} The result. + */ export const blendBurn = /*@__PURE__*/ Fn( ( [ base, blend ] ) => { return min( 1.0, base.oneMinus().div( blend ) ).oneMinus(); @@ -14,6 +28,18 @@ export const blendBurn = /*@__PURE__*/ Fn( ( [ base, blend ] ) => { ] } ); +/** + * Represents a "Color Dodge" blend mode. + * + * It's designed to lighten the base layer's colors based on the color of the blend layer. + * It significantly increases the brightness of the base layer, making the colors lighter and more vibrant. + * The brighter the color in the blend layer, the stronger the lightening and contrast effect on the base layer. + * + * @method + * @param {Node} base - The base color. + * @param {Node} blend - The blend color. A black (#000000) blend color does not alter the base color. + * @return {Node} The result. + */ export const blendDodge = /*@__PURE__*/ Fn( ( [ base, blend ] ) => { return min( base.div( blend.oneMinus() ), 1.0 ); @@ -27,6 +53,18 @@ export const blendDodge = /*@__PURE__*/ Fn( ( [ base, blend ] ) => { ] } ); +/** + * Represents a "Screen" blend mode. + * + * Similar to `blendDodge()`, this mode also lightens the base layer's colors based on the color of the blend layer. + * The "Screen" blend mode is better for general brightening whereas the "Dodge" results in more subtle and nuanced + * effects. + * + * @method + * @param {Node} base - The base color. + * @param {Node} blend - The blend color. A black (#000000) blend color does not alter the base color. + * @return {Node} The result. + */ export const blendScreen = /*@__PURE__*/ Fn( ( [ base, blend ] ) => { return base.oneMinus().mul( blend.oneMinus() ).oneMinus(); @@ -40,6 +78,18 @@ export const blendScreen = /*@__PURE__*/ Fn( ( [ base, blend ] ) => { ] } ); +/** + * Represents a "Overlay" blend mode. + * + * It's designed to increase the contrast of the base layer based on the color of the top layer. + * It amplifies the existing colors and contrast in the base layer, making lighter areas lighter and darker areas darker. + * The color of the blend layer significantly influences the resulting contrast and color shift in the base layer. + * + * @method + * @param {Node} base - The base color. + * @param {Node} blend - The blend color + * @return {Node} The result. + */ 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 ) ); @@ -53,6 +103,15 @@ export const blendOverlay = /*@__PURE__*/ Fn( ( [ base, blend ] ) => { ] } ); +/** + * This function blends two color based on their alpha values by replicating the behavior of `THREE.NormalBlending`. + * It assumes both input colors have non-preumiltiplied alpha. + * + * @method + * @param {Node} base - The base color. + * @param {Node} blend - The blend color + * @return {Node} The result. + */ export const blendColor = /*@__PURE__*/ Fn( ( [ base, blend ] ) => { const outAlpha = blend.a.add( base.a.mul( blend.a.oneMinus() ) ); @@ -99,7 +158,7 @@ export const dodge = ( ...params ) => { // @deprecated, r171 }; /** - * @function + * @method * @deprecated since r171. Use {@link blendScreen} instead. * * @param {...any} params @@ -113,7 +172,7 @@ export const screen = ( ...params ) => { // @deprecated, r171 }; /** - * @function + * @method * @deprecated since r171. Use {@link blendOverlay} instead. * * @param {...any} params From 4c6b390673b85835bdaf50da9369633c7897ae67 Mon Sep 17 00:00:00 2001 From: Michael Herzog Date: Tue, 14 Jan 2025 13:00:48 +0100 Subject: [PATCH 2/2] Update BlendModes.js --- src/nodes/display/BlendModes.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/nodes/display/BlendModes.js b/src/nodes/display/BlendModes.js index 2a12b8370481a6..9ee7f7abfd97c8 100644 --- a/src/nodes/display/BlendModes.js +++ b/src/nodes/display/BlendModes.js @@ -81,7 +81,7 @@ export const blendScreen = /*@__PURE__*/ Fn( ( [ base, blend ] ) => { /** * Represents a "Overlay" blend mode. * - * It's designed to increase the contrast of the base layer based on the color of the top layer. + * It's designed to increase the contrast of the base layer based on the color of the blend layer. * It amplifies the existing colors and contrast in the base layer, making lighter areas lighter and darker areas darker. * The color of the blend layer significantly influences the resulting contrast and color shift in the base layer. *