Skip to content

Commit b367df1

Browse files
Mugen87Mugen87
authored
Node: Document more modules. (#30135)
* Node: Document more modules. * Clean up. * Node: Document more modules. * Fix E2E.
1 parent 2376e3c commit b367df1

22 files changed

+1324
-65
lines changed

‎examples/jsm/tsl/display/AfterImageNode.js

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,18 @@
11
import { RenderTarget, Vector2, QuadMesh, NodeMaterial, PostProcessingUtils, TempNode, NodeUpdateType } from 'three/webgpu';
22
import { nodeObject, Fn, float, vec4, uv, texture, passTexture, uniform, sign, max, convertToTexture } from 'three/tsl';
33

4+
/** @module AfterImageNode **/
5+
46
const _size = /*@__PURE__*/ new Vector2();
57
const _quadMeshComp = /*@__PURE__*/ new QuadMesh();
68

79
let _rendererState;
810

11+
/**
12+
* Post processing node for creating an after image effect.
13+
*
14+
* @augments TempNode
15+
*/
916
class AfterImageNode extends TempNode {
1017

1118
static get type() {
@@ -14,39 +21,103 @@ class AfterImageNode extends TempNode {
1421

1522
}
1623

24+
/**
25+
* Constructs a new after image node.
26+
*
27+
* @param {TextureNode} textureNode - The texture node that represents the input of the effect.
28+
* @param {Number} [damp=0.96] - The damping intensity. A higher value means a stronger after image effect.
29+
*/
1730
constructor( textureNode, damp = 0.96 ) {
1831

1932
super( 'vec4' );
2033

34+
/**
35+
* The texture node that represents the input of the effect.
36+
*
37+
* @type {TextureNode}
38+
*/
2139
this.textureNode = textureNode;
40+
41+
/**
42+
* The texture represents the pervious frame.
43+
*
44+
* @type {TextureNode}
45+
*/
2246
this.textureNodeOld = texture();
47+
48+
/**
49+
* The damping intensity as a uniform node.
50+
*
51+
* @type {UniformNode<float>}
52+
*/
2353
this.damp = uniform( damp );
2454

55+
/**
56+
* The render target used for compositing the effect.
57+
*
58+
* @private
59+
* @type {RenderTarget}
60+
*/
2561
this._compRT = new RenderTarget( 1, 1, { depthBuffer: false } );
2662
this._compRT.texture.name = 'AfterImageNode.comp';
2763

64+
/**
65+
* The render target that represents the previous frame.
66+
*
67+
* @private
68+
* @type {RenderTarget}
69+
*/
2870
this._oldRT = new RenderTarget( 1, 1, { depthBuffer: false } );
2971
this._oldRT.texture.name = 'AfterImageNode.old';
3072

73+
/**
74+
* The result of the effect is represented as a separate texture node.
75+
*
76+
* @private
77+
* @type {PassTextureNode}
78+
*/
3179
this._textureNode = passTexture( this, this._compRT.texture );
3280

81+
/**
82+
* The `updateBeforeType` is set to `NodeUpdateType.FRAME` since the node renders
83+
* its effect once per frame in `updateBefore()`.
84+
*
85+
* @type {String}
86+
* @default 'frame'
87+
*/
3388
this.updateBeforeType = NodeUpdateType.FRAME;
3489

3590
}
3691

92+
/**
93+
* Returns the result of the effect as a texture node.
94+
*
95+
* @return {PassTextureNode} A texture node that represents the result of the effect.
96+
*/
3797
getTextureNode() {
3898

3999
return this._textureNode;
40100

41101
}
42102

103+
/**
104+
* Sets the size of the effect.
105+
*
106+
* @param {Number} width - The width of the effect.
107+
* @param {Number} height - The height of the effect.
108+
*/
43109
setSize( width, height ) {
44110

45111
this._compRT.setSize( width, height );
46112
this._oldRT.setSize( width, height );
47113

48114
}
49115

116+
/**
117+
* This method is used to render the effect once per frame.
118+
*
119+
* @param {NodeFrame} frame - The current node frame.
120+
*/
50121
updateBefore( frame ) {
51122

52123
const { renderer } = frame;
@@ -90,6 +161,12 @@ class AfterImageNode extends TempNode {
90161

91162
}
92163

164+
/**
165+
* This method is used to setup the effect's TSL code.
166+
*
167+
* @param {NodeBuilder} builder - The current node builder.
168+
* @return {PassTextureNode}
169+
*/
93170
setup( builder ) {
94171

95172
const textureNode = this.textureNode;
@@ -141,6 +218,10 @@ class AfterImageNode extends TempNode {
141218

142219
}
143220

221+
/**
222+
* Frees internal resources. This method should be called
223+
* when the effect is no longer required.
224+
*/
144225
dispose() {
145226

146227
this._compRT.dispose();
@@ -150,6 +231,14 @@ class AfterImageNode extends TempNode {
150231

151232
}
152233

234+
/**
235+
* TSL function for creating an after image node for post processing.
236+
*
237+
* @function
238+
* @param {Node<vec4>} node - The node that represents the input of the effect.
239+
* @param {Number} [damp=0.96] - The damping intensity. A higher value means a stronger after image effect.
240+
* @returns {AfterImageNode}
241+
*/
153242
export const afterImage = ( node, damp ) => nodeObject( new AfterImageNode( convertToTexture( node ), damp ) );
154243

155244
export default AfterImageNode;

‎examples/jsm/tsl/display/AnaglyphPassNode.js

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,13 @@ import { Matrix3, NodeMaterial } from 'three/webgpu';
22
import { clamp, nodeObject, Fn, vec4, uv, uniform, max } from 'three/tsl';
33
import StereoCompositePassNode from './StereoCompositePassNode.js';
44

5+
/** @module AnaglyphPassNode **/
6+
7+
/**
8+
* A render pass node that creates an anaglyph effect.
9+
*
10+
* @augments StereoCompositePassNode
11+
*/
512
class AnaglyphPassNode extends StereoCompositePassNode {
613

714
static get type() {
@@ -10,20 +17,43 @@ class AnaglyphPassNode extends StereoCompositePassNode {
1017

1118
}
1219

20+
/**
21+
* Constructs a new anaglyph pass node.
22+
*
23+
* @param {Scene} scene - The scene to render.
24+
* @param {Camera} camera - The camera to render the scene with.
25+
*/
1326
constructor( scene, camera ) {
1427

1528
super( scene, camera );
1629

30+
/**
31+
* This flag can be used for type testing.
32+
*
33+
* @type {Boolean}
34+
* @readonly
35+
* @default true
36+
*/
1737
this.isAnaglyphPassNode = true;
1838

1939
// Dubois matrices from https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.7.6968&rep=rep1&type=pdf#page=4
2040

41+
/**
42+
* Color matrix node for the left eye.
43+
*
44+
* @type {UniformNode<mat3>}
45+
*/
2146
this._colorMatrixLeft = uniform( new Matrix3().fromArray( [
2247
0.456100, - 0.0400822, - 0.0152161,
2348
0.500484, - 0.0378246, - 0.0205971,
2449
0.176381, - 0.0157589, - 0.00546856
2550
] ) );
2651

52+
/**
53+
* Color matrix node for the right eye.
54+
*
55+
* @type {UniformNode<mat3>}
56+
*/
2757
this._colorMatrixRight = uniform( new Matrix3().fromArray( [
2858
- 0.0434706, 0.378476, - 0.0721527,
2959
- 0.0879388, 0.73364, - 0.112961,
@@ -32,6 +62,12 @@ class AnaglyphPassNode extends StereoCompositePassNode {
3262

3363
}
3464

65+
/**
66+
* This method is used to setup the effect's TSL code.
67+
*
68+
* @param {NodeBuilder} builder - The current node builder.
69+
* @return {PassTextureNode}
70+
*/
3571
setup( builder ) {
3672

3773
const uvNode = uv();
@@ -60,4 +96,12 @@ class AnaglyphPassNode extends StereoCompositePassNode {
6096

6197
export default AnaglyphPassNode;
6298

99+
/**
100+
* TSL function for creating an anaglyph pass node.
101+
*
102+
* @function
103+
* @param {Scene} scene - The scene to render.
104+
* @param {Camera} camera - The camera to render the scene with.
105+
* @returns {AnaglyphPassNode}
106+
*/
63107
export const anaglyphPass = ( scene, camera ) => nodeObject( new AnaglyphPassNode( scene, camera ) );

‎examples/jsm/tsl/display/BleachBypass.js

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
import { float, Fn, vec3, vec4, min, max, mix, luminance } from 'three/tsl';
22

3+
/** @module BleachBypass **/
4+
5+
/**
6+
* Applies a bleach bypass effect to the given color node.
7+
*
8+
* @function
9+
* @param {Node<vec4>} color - The color node to apply the sepia for.
10+
* @param {Node<float>} [opacity=1] - Influences how strong the effect is blended with the original color.
11+
* @return {Node<vec4>} The updated color node.
12+
*/
313
export const bleach = /*@__PURE__*/ Fn( ( [ color, opacity = 1 ] ) => {
414

515
const base = color;

‎examples/jsm/tsl/display/DepthOfFieldNode.js

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
11
import { TempNode, NodeUpdateType } from 'three/webgpu';
22
import { convertToTexture, nodeObject, Fn, uv, uniform, vec2, vec4, clamp } from 'three/tsl';
33

4+
/** @module DepthOfFieldNode **/
5+
6+
/**
7+
* Post processing node for creating depth of field (DOF) effect.
8+
*
9+
* @augments TempNode
10+
*/
411
class DepthOfFieldNode extends TempNode {
512

613
static get type() {
@@ -9,23 +16,78 @@ class DepthOfFieldNode extends TempNode {
916

1017
}
1118

19+
/**
20+
* Constructs a new DOF node.
21+
*
22+
* @param {TextureNode} textureNode - The texture node that represents the input of the effect.
23+
* @param {Node<float>} viewZNode - Represents the viewZ depth values of the scene.
24+
* @param {Node<float>} focusNode - Defines the effect's focus which is the distance along the camera's look direction in world units.
25+
* @param {Node<float>} apertureNode - Defines the effect's aperture.
26+
* @param {Node<float>} maxblurNode - Defines the effect's maximum blur.
27+
*/
1228
constructor( textureNode, viewZNode, focusNode, apertureNode, maxblurNode ) {
1329

1430
super( 'vec4' );
1531

32+
/**
33+
* The texture node that represents the input of the effect.
34+
*
35+
* @type {TextureNode}
36+
*/
1637
this.textureNode = textureNode;
38+
39+
/**
40+
* Represents the viewZ depth values of the scene.
41+
*
42+
* @type {Node<float>}
43+
*/
1744
this.viewZNode = viewZNode;
1845

46+
/**
47+
* Defines the effect's focus which is the distance along the camera's look direction in world units.
48+
*
49+
* @type {Node<float>}
50+
*/
1951
this.focusNode = focusNode;
52+
53+
/**
54+
* Defines the effect's aperture.
55+
*
56+
* @type {Node<float>}
57+
*/
2058
this.apertureNode = apertureNode;
59+
60+
/**
61+
* Defines the effect's maximum blur.
62+
*
63+
* @type {Node<float>}
64+
*/
2165
this.maxblurNode = maxblurNode;
2266

67+
/**
68+
* Represents the input's aspect ratio.
69+
*
70+
* @private
71+
* @type {UniformNode<float>}
72+
*/
2373
this._aspect = uniform( 0 );
2474

75+
/**
76+
* The `updateBeforeType` is set to `NodeUpdateType.FRAME` since the node updates
77+
* its internal uniforms once per frame in `updateBefore()`.
78+
*
79+
* @type {String}
80+
* @default 'frame'
81+
*/
2582
this.updateBeforeType = NodeUpdateType.FRAME;
2683

2784
}
2885

86+
/**
87+
* This method is used to update the effect's uniforms once per frame.
88+
*
89+
* @param {NodeFrame} frame - The current node frame.
90+
*/
2991
updateBefore() {
3092

3193
const map = this.textureNode.value;
@@ -34,6 +96,12 @@ class DepthOfFieldNode extends TempNode {
3496

3597
}
3698

99+
/**
100+
* This method is used to setup the effect's TSL code.
101+
*
102+
* @param {NodeBuilder} builder - The current node builder.
103+
* @return {ShaderCallNodeInternal}
104+
*/
37105
setup() {
38106

39107
const textureNode = this.textureNode;
@@ -116,4 +184,15 @@ class DepthOfFieldNode extends TempNode {
116184

117185
export default DepthOfFieldNode;
118186

187+
/**
188+
* TSL function for creating a depth-of-field effect (DOF) for post processing.
189+
*
190+
* @function
191+
* @param {Node<vec4>} node - The node that represents the input of the effect.
192+
* @param {Node<float>} viewZNode - Represents the viewZ depth values of the scene.
193+
* @param {Node<float> | Number} focus - Defines the effect's focus which is the distance along the camera's look direction in world units.
194+
* @param {Node<float> | Number} aperture - Defines the effect's aperture.
195+
* @param {Node<float> | Number} maxblur - Defines the effect's maximum blur.
196+
* @returns {DepthOfFieldNode}
197+
*/
119198
export const dof = ( node, viewZNode, focus = 1, aperture = 0.025, maxblur = 1 ) => nodeObject( new DepthOfFieldNode( convertToTexture( node ), nodeObject( viewZNode ), nodeObject( focus ), nodeObject( aperture ), nodeObject( maxblur ) ) );

0 commit comments

Comments
 (0)