Docs: Improve BlendModes module.

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<vec3>} base - The base color.
+ * @param {Node<vec3>} blend - The blend color. A white (#ffffff) blend color does not alter the base color.
+ * @return {Node<vec3>} 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<vec3>} base - The base color.
+ * @param {Node<vec3>} blend - The blend color. A black (#000000) blend color does not alter the base color.
+ * @return {Node<vec3>} 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<vec3>} base - The base color.
+ * @param {Node<vec3>} blend - The blend color. A black (#000000) blend color does not alter the base color.
+ * @return {Node<vec3>} 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 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.
+ *
+ * @method
+ * @param {Node<vec3>} base - The base color.
+ * @param {Node<vec3>} blend - The blend color
+ * @return {Node<vec3>} 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<vec4>} base - The base color.
+ * @param {Node<vec4>} blend - The blend color
+ * @return {Node<vec4>} 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