Skip to content

Commit 1fc010c

Browse files
Mugen87Mugen87
authored
Nodes: Document more modules. (#30075)
1 parent ef48dee commit 1fc010c

19 files changed

+493
-17
lines changed

‎src/nodes/core/Node.js

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -333,7 +333,6 @@ class Node extends EventDispatcher {
333333
* Generate a custom cache key for this node.
334334
*
335335
* @return {Number} The cache key of the node.
336-
* @default 0
337336
*/
338337
customCacheKey() {
339338

‎src/nodes/lighting/AONode.js

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
import LightingNode from './LightingNode.js';
22

3+
/**
4+
* A generic class that can be used by nodes which contribute
5+
* ambient occlusion to the scene. E.g. an ambient occlusion map
6+
* node can be used as input for this module. Used in {@link NodeMaterial}.
7+
*
8+
* @augments LightingNode
9+
*/
310
class AONode extends LightingNode {
411

512
static get type() {
@@ -8,10 +15,20 @@ class AONode extends LightingNode {
815

916
}
1017

18+
/**
19+
* Constructs a new AO node.
20+
*
21+
* @param {Node<float>} aoNode - The ambient occlusion node.
22+
*/
1123
constructor( aoNode = null ) {
1224

1325
super();
1426

27+
/**
28+
* The ambient occlusion node.
29+
*
30+
* @type {Node<float>}
31+
*/
1532
this.aoNode = aoNode;
1633

1734
}

‎src/nodes/lighting/AmbientLightNode.js

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
import AnalyticLightNode from './AnalyticLightNode.js';
22

3+
/**
4+
* Module for representing ambient lights as nodes.
5+
*
6+
* @augments AnalyticLightNode
7+
*/
38
class AmbientLightNode extends AnalyticLightNode {
49

510
static get type() {
@@ -8,6 +13,11 @@ class AmbientLightNode extends AnalyticLightNode {
813

914
}
1015

16+
/**
17+
* Constructs a new ambient light node.
18+
*
19+
* @param {AmbientLight?} [light=null] - The ambient light source.
20+
*/
1121
constructor( light = null ) {
1222

1323
super( light );

‎src/nodes/lighting/AnalyticLightNode.js

Lines changed: 88 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,11 @@ import { hash } from '../core/NodeUtils.js';
77
import { shadow } from './ShadowNode.js';
88
import { nodeObject } from '../tsl/TSLCore.js';
99

10+
/**
11+
* Base class for analytic light nodes.
12+
*
13+
* @augments LightingNode
14+
*/
1015
class AnalyticLightNode extends LightingNode {
1116

1217
static get type() {
@@ -15,31 +20,85 @@ class AnalyticLightNode extends LightingNode {
1520

1621
}
1722

23+
/**
24+
* Constructs a new analytic light node.
25+
*
26+
* @param {Light?} [light=null] - The light source.
27+
*/
1828
constructor( light = null ) {
1929

2030
super();
2131

32+
/**
33+
* The light source.
34+
*
35+
* @type {Light}
36+
* @default null
37+
*/
2238
this.light = light;
2339

40+
/**
41+
* The light's color value.
42+
*
43+
* @type {Color}
44+
*/
2445
this.color = new Color();
46+
47+
/**
48+
* The light's color node. Points to `colorNode` of the light source, if set. Otherwise
49+
* it creates a uniform node based on {@link AnalyticLightNode#color}.
50+
*
51+
* @type {Node}
52+
*/
2553
this.colorNode = ( light && light.colorNode ) || uniform( this.color ).setGroup( renderGroup );
2654

55+
/**
56+
* This property is used to retain a reference to the original value of {@link AnalyticLightNode#colorNode}.
57+
* The final color node is represented by a differnt node when using shadows.
58+
*
59+
* @type {Node}
60+
*/
2761
this.baseColorNode = null;
2862

63+
/**
64+
* Represents the light's shadow.
65+
*
66+
* @type {ShadowNode}
67+
*/
2968
this.shadowNode = null;
69+
70+
/**
71+
* Represents the light's shadow color.
72+
*
73+
* @type {Node}
74+
*/
3075
this.shadowColorNode = null;
3176

77+
/**
78+
* This flag can be used for type testing.
79+
*
80+
* @type {Boolean}
81+
* @readonly
82+
* @default true
83+
*/
3284
this.isAnalyticLightNode = true;
3385

86+
/**
87+
* Overwritten since analytic light nodes are updated
88+
* once per frame.
89+
*
90+
* @type {String}
91+
* @default 'frame'
92+
*/
3493
this.updateType = NodeUpdateType.FRAME;
3594

3695
}
3796

3897
/**
39-
* Overwrites the default `customCacheKey()` implementation by including the
40-
* light.id and light.castShadow into the cache key.
98+
* Overwrites the default {@link Node#customCacheKey} implementation by including the
99+
* `light.id` and `light.castShadow` into the cache key.
41100
*
42-
* @return {Number} The hash.
101+
* @return {Number} The custom cache key.
43102
*/
44103
customCacheKey() {
45104

@@ -53,12 +112,24 @@ class AnalyticLightNode extends LightingNode {
53112

54113
}
55114

115+
/**
116+
* Setups the shadow node for this light. The method exists so concrete light classes
117+
* can setup different types of shadow nodes.
118+
*
119+
* @return {ShadowNode} The created shadow node.
120+
*/
56121
setupShadowNode() {
57122

58123
return shadow( this.light );
59124

60125
}
61126

127+
/**
128+
* Setups the shadow for this light. This method is only executed if the light
129+
* cast shadows and the current build object receives shadows.
130+
*
131+
* @param {NodeBuilder} builder - The current node builder.
132+
*/
62133
setupShadow( builder ) {
63134

64135
const { renderer } = builder;
@@ -97,6 +168,13 @@ class AnalyticLightNode extends LightingNode {
97168

98169
}
99170

171+
/**
172+
* Unlike most other nodes, lighting nodes do not return a output node in {@link Node#setup}.
173+
* The main purpose of lighting nodes is to configure the current {@link LightingModel} and/or
174+
* invocate the respecitve interface methods.
175+
*
176+
* @param {NodeBuilder} builder - The current node builder.
177+
*/
100178
setup( builder ) {
101179

102180
this.colorNode = this.baseColorNode || this.colorNode;
@@ -119,6 +197,13 @@ class AnalyticLightNode extends LightingNode {
119197

120198
}
121199

200+
/**
201+
* The update method is used to update light uniforms per frame.
202+
* Potentially overwritten in concrete light nodes to update light
203+
* specific uniforms.
204+
*
205+
* @param {NodeFrame} frame - A reference to the current node frame.
206+
*/
122207
update( /*frame*/ ) {
123208

124209
const { light } = this;

‎src/nodes/lighting/BasicEnvironmentNode.js

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,14 @@
11
import LightingNode from './LightingNode.js';
22
import { cubeMapNode } from '../utils/CubeMapNode.js';
33

4+
/**
5+
* Represents a basic model for Image-based lighting (IBL). The environment
6+
* is defined via environment maps in the equirectanular or cube map format.
7+
* `BasicEnvironmentNode` is intended for non-PBR materials like {@link MeshBasicNodeMaterial}
8+
* or {@link MeshPhongNodeMaterial}.
9+
*
10+
* @augments LightingNode
11+
*/
412
class BasicEnvironmentNode extends LightingNode {
513

614
static get type() {
@@ -9,10 +17,21 @@ class BasicEnvironmentNode extends LightingNode {
917

1018
}
1119

20+
/**
21+
* Constructs a new basic environment node.
22+
*
23+
* @param {Node} [envNode=null] - A node representing the environment.
24+
*/
1225
constructor( envNode = null ) {
1326

1427
super();
1528

29+
/**
30+
* A node representing the environment.
31+
*
32+
* @type {Node}
33+
* @default null
34+
*/
1635
this.envNode = envNode;
1736

1837
}

‎src/nodes/lighting/BasicLightMapNode.js

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
11
import LightingNode from './LightingNode.js';
22
import { float } from '../tsl/TSLBase.js';
33

4+
/**
5+
* A specific version of {@link IrradianceNode} that is only relevant
6+
* for {@link MeshBasicNodeMaterial}. Since the material is unlit, it
7+
* requires a special scaling factor for the light map.
8+
*
9+
* @augments LightingNode
10+
*/
411
class BasicLightMapNode extends LightingNode {
512

613
static get type() {
@@ -9,10 +16,20 @@ class BasicLightMapNode extends LightingNode {
916

1017
}
1118

19+
/**
20+
* Constructs a new basic light map node.
21+
*
22+
* @param {Node<vec3>} lightMapNode - The light map node.
23+
*/
1224
constructor( lightMapNode = null ) {
1325

1426
super();
1527

28+
/**
29+
* The light map node.
30+
*
31+
* @type {Node<vec3>}
32+
*/
1633
this.lightMapNode = lightMapNode;
1734

1835
}

‎src/nodes/lighting/DirectionalLightNode.js

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
import AnalyticLightNode from './AnalyticLightNode.js';
22
import { lightTargetDirection } from '../accessors/Lights.js';
33

4+
/**
5+
* Module for representing directional lights as nodes.
6+
*
7+
* @augments AnalyticLightNode
8+
*/
49
class DirectionalLightNode extends AnalyticLightNode {
510

611
static get type() {
@@ -9,6 +14,11 @@ class DirectionalLightNode extends AnalyticLightNode {
914

1015
}
1116

17+
/**
18+
* Constructs a new directional light node.
19+
*
20+
* @param {DirectionalLight?} [light=null] - The directional light source.
21+
*/
1222
constructor( light = null ) {
1323

1424
super( light );

‎src/nodes/lighting/EnvironmentNode.js

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,13 @@ import { pmremTexture } from '../pmrem/PMREMNode.js';
1111

1212
const _envNodeCache = new WeakMap();
1313

14+
/**
15+
* Represents a physical model for Image-based lighting (IBL). The environment
16+
* is defined via environment maps in the equirectanular, cube map or cubeUV (PMREM) format.
17+
* `EnvironmentNode` is intended for PBR materials like {@link MeshStandardNodeMaterial}.
18+
*
19+
* @augments LightingNode
20+
*/
1421
class EnvironmentNode extends LightingNode {
1522

1623
static get type() {
@@ -19,10 +26,21 @@ class EnvironmentNode extends LightingNode {
1926

2027
}
2128

29+
/**
30+
* Constructs a new environment node.
31+
*
32+
* @param {Node} [envNode=null] - A node representing the environment.
33+
*/
2234
constructor( envNode = null ) {
2335

2436
super();
2537

38+
/**
39+
* A node representing the environment.
40+
*
41+
* @type {Node}
42+
* @default null
43+
*/
2644
this.envNode = envNode;
2745

2846
}

0 commit comments

Comments
 (0)