Skip to content

Commit b124221

Browse files
Mugen87Mugen87
authored
Docs: More JSDoc. (#30656)
1 parent ef73c54 commit b124221

16 files changed

+950
-50
lines changed

‎examples/jsm/csm/CSM.js

+226-15
Original file line numberDiff line numberDiff line change
@@ -20,38 +20,179 @@ const _lightOrientationMatrix = new Matrix4();
2020
const _lightOrientationMatrixInverse = new Matrix4();
2121
const _up = new Vector3( 0, 1, 0 );
2222

23+
/**
24+
* An implementation of Cascade Shadow Maps (CSM).
25+
*
26+
* This module can only be used with {@link WebGLRenderer}. When using {@link WebGPURenderer},
27+
* use {@link CSMShadowNode} instead.
28+
*/
2329
export class CSM {
2430

31+
/**
32+
* Constructs a new CSM instance.
33+
*
34+
* @param {CSM~Data} data - The CSM data.
35+
*/
2536
constructor( data ) {
2637

38+
/**
39+
* The scene's camera.
40+
*
41+
* @type {Camera}
42+
*/
2743
this.camera = data.camera;
44+
45+
/**
46+
* The parent object, usually the scene.
47+
*
48+
* @type {Object3D}
49+
*/
2850
this.parent = data.parent;
51+
52+
/**
53+
* The number of cascades.
54+
*
55+
* @type {number}
56+
* @default 3
57+
*/
2958
this.cascades = data.cascades || 3;
59+
60+
/**
61+
* The maximum far value.
62+
*
63+
* @type {number}
64+
* @default 100000
65+
*/
3066
this.maxFar = data.maxFar || 100000;
67+
68+
/**
69+
* The frustum split mode.
70+
*
71+
* @type {('practical'|'uniform'|'logarithmic'|'custom')}
72+
* @default 'practical'
73+
*/
3174
this.mode = data.mode || 'practical';
75+
76+
/**
77+
* The shadow map size.
78+
*
79+
* @type {number}
80+
* @default 2048
81+
*/
3282
this.shadowMapSize = data.shadowMapSize || 2048;
83+
84+
/**
85+
* The shadow bias.
86+
*
87+
* @type {number}
88+
* @default 0.000001
89+
*/
3390
this.shadowBias = data.shadowBias || 0.000001;
91+
92+
/**
93+
* The light direction.
94+
*
95+
* @type {Vector3}
96+
*/
3497
this.lightDirection = data.lightDirection || new Vector3( 1, - 1, 1 ).normalize();
98+
99+
/**
100+
* The light intensity.
101+
*
102+
* @type {number}
103+
* @default 3
104+
*/
35105
this.lightIntensity = data.lightIntensity || 3;
106+
107+
/**
108+
* The light near value.
109+
*
110+
* @type {number}
111+
* @default 1
112+
*/
36113
this.lightNear = data.lightNear || 1;
114+
115+
/**
116+
* The light far value.
117+
*
118+
* @type {number}
119+
* @default 2000
120+
*/
37121
this.lightFar = data.lightFar || 2000;
122+
123+
/**
124+
* The light margin.
125+
*
126+
* @type {number}
127+
* @default 200
128+
*/
38129
this.lightMargin = data.lightMargin || 200;
130+
131+
/**
132+
* Custom split callback when using `mode='custom'`.
133+
*
134+
* @type {Function}
135+
*/
39136
this.customSplitsCallback = data.customSplitsCallback;
137+
138+
/**
139+
* Whether to fade between cascades or not.
140+
*
141+
* @type {boolean}
142+
* @default false
143+
*/
40144
this.fade = false;
145+
146+
/**
147+
* The main frustum.
148+
*
149+
* @type {CSMFrustum}
150+
*/
41151
this.mainFrustum = new CSMFrustum( { webGL: true } );
152+
153+
/**
154+
* An array of frustums representing the cascades.
155+
*
156+
* @type {Array<CSMFrustum>}
157+
*/
42158
this.frustums = [];
159+
160+
/**
161+
* An array of numbers in the range `[0,1]` the defines how the
162+
* mainCSM frustum should be split up.
163+
*
164+
* @type {Array<number>}
165+
*/
43166
this.breaks = [];
44167

168+
/**
169+
* An array of directional lights which cast the shadows for
170+
* the different cascades. There is one directional light for each
171+
* cascade.
172+
*
173+
* @type {Array<DirectionalLight>}
174+
*/
45175
this.lights = [];
176+
177+
/**
178+
* A Map holding enhanced material shaders.
179+
*
180+
* @type {Map<Material,Object>}
181+
*/
46182
this.shaders = new Map();
47183

48-
this.createLights();
184+
this._createLights();
49185
this.updateFrustums();
50-
this.injectInclude();
186+
this._injectInclude();
51187

52188
}
53189

54-
createLights() {
190+
/**
191+
* Creates the directional lights of this CSM instance.
192+
*
193+
* @private
194+
*/
195+
_createLights() {
55196

56197
for ( let i = 0; i < this.cascades; i ++ ) {
57198

@@ -72,7 +213,12 @@ export class CSM {
72213

73214
}
74215

75-
initCascades() {
216+
/**
217+
* Inits the cascades according to the scene's camera and breaks configuration.
218+
*
219+
* @private
220+
*/
221+
_initCascades() {
76222

77223
const camera = this.camera;
78224
camera.updateProjectionMatrix();
@@ -81,7 +227,12 @@ export class CSM {
81227

82228
}
83229

84-
updateShadowBounds() {
230+
/**
231+
* Updates the shadow bounds of this CSM instance.
232+
*
233+
* @private
234+
*/
235+
_updateShadowBounds() {
85236

86237
const frustums = this.frustums;
87238
for ( let i = 0; i < frustums.length; i ++ ) {
@@ -130,7 +281,13 @@ export class CSM {
130281

131282
}
132283

133-
getBreaks() {
284+
/**
285+
* Computes the breaks of this CSM instance based on the scene's camera, number of cascades
286+
* and the selected split mode.
287+
*
288+
* @private
289+
*/
290+
_getBreaks() {
134291

135292
const camera = this.camera;
136293
const far = Math.min( camera.far, this.maxFar );
@@ -197,6 +354,10 @@ export class CSM {
197354

198355
}
199356

357+
/**
358+
* Updates the CSM. This method must be called in your animation loop before
359+
* calling `renderer.render()`.
360+
*/
200361
update() {
201362

202363
const camera = this.camera;
@@ -243,13 +404,23 @@ export class CSM {
243404

244405
}
245406

246-
injectInclude() {
407+
/**
408+
* Injects the CSM shader enhancements into the built-in materials.
409+
*
410+
* @private
411+
*/
412+
_injectInclude() {
247413

248414
ShaderChunk.lights_fragment_begin = CSMShader.lights_fragment_begin;
249415
ShaderChunk.lights_pars_begin = CSMShader.lights_pars_begin;
250416

251417
}
252418

419+
/**
420+
* Applications must call this method for all materials that should be affected by CSM.
421+
*
422+
* @param {Material} material - The material to setup for CSM support.
423+
*/
253424
setupMaterial( material ) {
254425

255426
material.defines = material.defines || {};
@@ -269,7 +440,7 @@ export class CSM {
269440
material.onBeforeCompile = function ( shader ) {
270441

271442
const far = Math.min( scope.camera.far, scope.maxFar );
272-
scope.getExtendedBreaks( breaksVec2 );
443+
scope._getExtendedBreaks( breaksVec2 );
273444

274445
shader.uniforms.CSM_cascades = { value: breaksVec2 };
275446
shader.uniforms.cameraNear = { value: scope.camera.near };
@@ -283,7 +454,12 @@ export class CSM {
283454

284455
}
285456

286-
updateUniforms() {
457+
/**
458+
* Updates the CSM uniforms.
459+
*
460+
* @private
461+
*/
462+
_updateUniforms() {
287463

288464
const far = Math.min( this.camera.far, this.maxFar );
289465
const shaders = this.shaders;
@@ -293,7 +469,7 @@ export class CSM {
293469
if ( shader !== null ) {
294470

295471
const uniforms = shader.uniforms;
296-
this.getExtendedBreaks( uniforms.CSM_cascades.value );
472+
this._getExtendedBreaks( uniforms.CSM_cascades.value );
297473
uniforms.cameraNear.value = this.camera.near;
298474
uniforms.shadowFar.value = far;
299475

@@ -315,7 +491,13 @@ export class CSM {
315491

316492
}
317493

318-
getExtendedBreaks( target ) {
494+
/**
495+
* Computes the extended breaks for the CSM uniforms.
496+
*
497+
* @private
498+
* @param {Array<Vector2>} target - The target array that holds the extended breaks.
499+
*/
500+
_getExtendedBreaks( target ) {
319501

320502
while ( target.length < this.breaks.length ) {
321503

@@ -336,15 +518,21 @@ export class CSM {
336518

337519
}
338520

521+
/**
522+
* Applications must call this method every time they change camera or CSM settings.
523+
*/
339524
updateFrustums() {
340525

341-
this.getBreaks();
342-
this.initCascades();
343-
this.updateShadowBounds();
344-
this.updateUniforms();
526+
this._getBreaks();
527+
this._initCascades();
528+
this._updateShadowBounds();
529+
this._updateUniforms();
345530

346531
}
347532

533+
/**
534+
* Applications must call this method when they remove the CSM usage from their scene.
535+
*/
348536
remove() {
349537

350538
for ( let i = 0; i < this.lights.length; i ++ ) {
@@ -356,6 +544,10 @@ export class CSM {
356544

357545
}
358546

547+
/**
548+
* Frees the GPU-related resources allocated by this instance. Call this
549+
* method whenever this instance is no longer used in your app.
550+
*/
359551
dispose() {
360552

361553
const shaders = this.shaders;
@@ -382,3 +574,22 @@ export class CSM {
382574
}
383575

384576
}
577+
578+
/**
579+
* Constructor data of `CSM`.
580+
*
581+
* @typedef {Object} CSM~Data
582+
* @property {Camera} camera - The scene's camera.
583+
* @property {Object3D} parent - The parent object, usually the scene.
584+
* @property {number} [cascades=3] - The number of cascades.
585+
* @property {number} [maxFar=100000] - The maximum far value.
586+
* @property {('practical'|'uniform'|'logarithmic'|'custom')} [mode='practical'] - The frustum split mode.
587+
* @property {Function} [customSplitsCallback] - Custom split callback when using `mode='custom'`.
588+
* @property {number} [shadowMapSize=2048] - The shadow map size.
589+
* @property {number} [shadowBias=0.000001] - The shadow bias.
590+
* @property {Vector3} [lightDirection] - The light direction.
591+
* @property {number} [lightIntensity=3] - The light intensity.
592+
* @property {number} [lightNear=1] - The light near value.
593+
* @property {number} [lightNear=2000] - The light far value.
594+
* @property {number} [lightMargin=200] - The light margin.
595+
**/

0 commit comments

Comments
 (0)