Skip to content

Commit

Permalink
Node: Document more modules. (#30037)
Browse files Browse the repository at this point in the history
  • Loading branch information
Mugen87 authored Dec 4, 2024
1 parent dfab00f commit 946a69c
Show file tree
Hide file tree
Showing 13 changed files with 675 additions and 16 deletions.
4 changes: 3 additions & 1 deletion examples/jsm/tsl/display/AnamorphicNode.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { RenderTarget, Vector2, TempNode, QuadMesh, NodeMaterial, PostProcessingUtils } from 'three/webgpu';
import { nodeObject, Fn, float, NodeUpdateType, uv, passTexture, uniform, convertToTexture, vec2, vec3, Loop, threshold } from 'three/tsl';
import { nodeObject, Fn, float, NodeUpdateType, uv, passTexture, uniform, convertToTexture, vec2, vec3, Loop, mix, luminance } from 'three/tsl';

const _quadMesh = /*@__PURE__*/ new QuadMesh();

Expand Down Expand Up @@ -92,6 +92,8 @@ class AnamorphicNode extends TempNode {

const sampleTexture = ( uv ) => textureNode.uv( uv );

const threshold = ( color, threshold ) => mix( vec3( 0.0 ), color, luminance( color ).sub( threshold ).max( 0 ) );

const anamorph = Fn( () => {

const samples = this.samples;
Expand Down
27 changes: 27 additions & 0 deletions src/nodes/display/BumpMapNode.js
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,15 @@ const perturbNormalArb = Fn( ( inputs ) => {

} );

/**
* This class can be used for applying bump maps to materials.
*
* ```js
* material.normalNode = bumpMap( texture( bumpTex ) );
* ```
*
* @augments TempNode
*/
class BumpMapNode extends TempNode {

static get type() {
Expand All @@ -52,11 +61,29 @@ class BumpMapNode extends TempNode {

}

/**
* Constructs a new bump map node.
*
* @param {Node} textureNode - Represents the bump map data.
* @param {Node?} [scaleNode=null] - Controls the intensity of the bump effect.
*/
constructor( textureNode, scaleNode = null ) {

super( 'vec3' );

/**
* Represents the bump map data.
*
* @type {Node}
*/
this.textureNode = textureNode;

/**
* Controls the intensity of the bump effect.
*
* @type {Node?}
* @default null
*/
this.scaleNode = scaleNode;

}
Expand Down
43 changes: 41 additions & 2 deletions src/nodes/display/ColorAdjustment.js
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,43 @@ import { LinearSRGBColorSpace } from '../../constants.js';

/** @module ColorAdjustment **/

/**
* Computes a grayscale value for the given RGB color value.
*
* @method
* @param {vec3} color - The color value to compute the grayscale for.
* @return {vec3} The grayscale color.
*/
export const grayscale = /*@__PURE__*/ Fn( ( [ color ] ) => {

return luminance( color.rgb );

} );

/**
* Super-saturates or desaturates the given RGB color.
*
* @method
* @param {vec3} color - The input color.
* @param {float} [adjustment=1] - Specifies the amount of the conversion. A value under `1` desaturates the color, a value over `1` super-saturates it.
* @return {vec3} The saturated color.
*/
export const saturation = /*@__PURE__*/ Fn( ( [ color, adjustment = float( 1 ) ] ) => {

return adjustment.mix( luminance( color.rgb ), color.rgb );

} );

/**
* Selectively enhance the intensity of less saturated RGB colors. Can result
* in a more natural and visually appealing image with enhanced color depth
* compared to {@link ColorAdjustment#saturation}.
*
* @method
* @param {vec3} color - The input color.
* @param {float} [adjustment=1] - Controls the intensity of the vibrance effect.
* @return {vec3} The updated color.
*/
export const vibrance = /*@__PURE__*/ Fn( ( [ color, adjustment = float( 1 ) ] ) => {

const average = add( color.r, color.g, color.b ).div( 3.0 );
Expand All @@ -30,6 +55,14 @@ export const vibrance = /*@__PURE__*/ Fn( ( [ color, adjustment = float( 1 ) ] )

} );

/**
* Updates the hue component of the given RGB color while preserving its luminance and saturation.
*
* @method
* @param {vec3} color - The input color.
* @param {float} [adjustment=1] - Defines the degree of hue rotation in radians. A positive value rotates the hue clockwise, while a negative value rotates it counterclockwise.
* @return {vec3} The updated color.
*/
export const hue = /*@__PURE__*/ Fn( ( [ color, adjustment = float( 1 ) ] ) => {

const k = vec3( 0.57735, 0.57735, 0.57735 );
Expand All @@ -40,13 +73,19 @@ export const hue = /*@__PURE__*/ Fn( ( [ color, adjustment = float( 1 ) ] ) => {

} );

/**
* Computes the luminance for the given RGB color value.
*
* @method
* @param {vec3} color - The color value to compute the luminance for.
* @param {vec3?} luminanceCoefficients - The luminance coefficients. By default predefined values of the current working color space are used.
* @return {vec3} The luminance.
*/
export const luminance = (
color,
luminanceCoefficients = vec3( ColorManagement.getLuminanceCoefficients( new Vector3() ) )
) => dot( color, luminanceCoefficients );

export const threshold = ( color, threshold ) => mix( vec3( 0.0 ), color, luminance( color ).sub( threshold ).max( 0 ) );

/**
* Color Decision List (CDL) v1.2
*
Expand Down
16 changes: 16 additions & 0 deletions src/nodes/display/ColorSpaceFunctions.js
Original file line number Diff line number Diff line change
@@ -1,6 +1,15 @@
import { mix } from '../math/MathNode.js';
import { Fn } from '../tsl/TSLCore.js';

/** @module ColorSpaceFunctions **/

/**
* Converts the given color value from sRGB to linear-sRGB color space.
*
* @method
* @param {vec3} color - The sRGB color.
* @return {vec3} The linear-sRGB color.
*/
export const sRGBTransferEOTF = /*@__PURE__*/ Fn( ( [ color ] ) => {

const a = color.mul( 0.9478672986 ).add( 0.0521327014 ).pow( 2.4 );
Expand All @@ -19,6 +28,13 @@ export const sRGBTransferEOTF = /*@__PURE__*/ Fn( ( [ color ] ) => {
]
} );

/**
* Converts the given color value from linear-sRGB to sRGB color space.
*
* @method
* @param {vec3} color - The linear-sRGB color.
* @return {vec3} The sRGB color.
*/
export const sRGBTransferOETF = /*@__PURE__*/ Fn( ( [ color ] ) => {

const a = color.pow( 0.41666 ).mul( 1.055 ).sub( 0.055 );
Expand Down
39 changes: 39 additions & 0 deletions src/nodes/display/ColorSpaceNode.js
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,12 @@ import { Matrix3 } from '../../math/Matrix3.js';
const WORKING_COLOR_SPACE = 'WorkingColorSpace';
const OUTPUT_COLOR_SPACE = 'OutputColorSpace';

/**
* This node represents a color space conversion. Meaning it converts
* a color value from a source to a target color space.
*
* @augments TempNode
*/
class ColorSpaceNode extends TempNode {

static get type() {
Expand All @@ -17,16 +23,49 @@ class ColorSpaceNode extends TempNode {

}

/**
* Constructs a new color space node.
*
* @param {Node} colorNode - Represents the color to convert.
* @param {String} source - The source color space.
* @param {String} target - The target color space.
*/
constructor( colorNode, source, target ) {

super( 'vec4' );

/**
* Represents the color to convert.
*
* @type {Node}
*/
this.colorNode = colorNode;

/**
* The source color space.
*
* @type {Node}
*/
this.source = source;

/**
* The target color space.
*
* @type {Node}
*/
this.target = target;

}

/**
* This method resolves the constants `WORKING_COLOR_SPACE` and
* `OUTPUT_COLOR_SPACE` based on the current configuration of the
* color management and renderer.
*
* @param {NodeBuilder} builder - The current node builder.
* @param {String} colorSpace - The color space to resolve.
* @return {String} The resolved color space.
*/
resolveColorSpace( builder, colorSpace ) {

if ( colorSpace === WORKING_COLOR_SPACE ) {
Expand Down
15 changes: 15 additions & 0 deletions src/nodes/display/FrontFacingNode.js
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,11 @@ import { nodeImmutable, float } from '../tsl/TSLBase.js';

import { BackSide, WebGLCoordinateSystem } from '../../constants.js';

/**
* This node can be used to evaluate whether a primitive is front or back facing.
*
* @augments Node
*/
class FrontFacingNode extends Node {

static get type() {
Expand All @@ -11,10 +16,20 @@ class FrontFacingNode extends Node {

}

/**
* Constructs a new front facing node.
*/
constructor() {

super( 'bool' );

/**
* This flag can be used for type testing.
*
* @type {Boolean}
* @readonly
* @default true
*/
this.isFrontFacingNode = true;

}
Expand Down
33 changes: 33 additions & 0 deletions src/nodes/display/NormalMapNode.js
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,15 @@ const perturbNormal2Arb = /*@__PURE__*/ Fn( ( inputs ) => {

} );

/**
* This class can be used for applying normals maps to materials.
*
* ```js
* material.normalNode = normalMap( texture( normalTex ) );
* ```
*
* @augments TempNode
*/
class NormalMapNode extends TempNode {

static get type() {
Expand All @@ -45,13 +54,37 @@ class NormalMapNode extends TempNode {

}

/**
* Constructs a new normal map node.
*
* @param {Node} textureNode - Represents the normal map data.
* @param {Node?} [scaleNode=null] - Controls the intensity of the effect.
*/
constructor( node, scaleNode = null ) {

super( 'vec3' );

/**
* Represents the normal map data.
*
* @type {Node}
*/
this.node = node;

/**
* Controls the intensity of the effect.
*
* @type {Node?}
* @default null
*/
this.scaleNode = scaleNode;

/**
* The normal map type.
*
* @type {(TangentSpaceNormalMap|ObjectSpaceNormalMap)}
* @default TangentSpaceNormalMap
*/
this.normalMapType = TangentSpaceNormalMap;

}
Expand Down
Loading

0 comments on commit 946a69c

Please sign in to comment.