Skip to content

Commit b124221

Browse files
Mugen87Mugen87
authoredMar 5, 2025··
Docs: More JSDoc. (#30656)
·
r176r175
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+
**/

‎examples/jsm/csm/CSMFrustum.js

+52
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,35 @@ import { Vector3, Matrix4 } from 'three';
22

33
const inverseProjectionMatrix = new Matrix4();
44

5+
/**
6+
* Represents the frustum of a CSM instance.
7+
*/
58
class CSMFrustum {
69

10+
/**
11+
* Constructs a new CSM frustum.
12+
*
13+
* @param {CSMFrustum~Data} data - The CSM data.
14+
*/
715
constructor( data ) {
816

917
data = data || {};
1018

19+
/**
20+
* The zNear value. This value depends on whether the CSM
21+
* is used with WebGL or WebGPU. Both API use different
22+
* conventions for their projection matrices.
23+
*
24+
* @type {number}
25+
*/
1126
this.zNear = data.webGL === true ? - 1 : 0;
1227

28+
/**
29+
* An object representing the vertices of the near and
30+
* far plane in view space.
31+
*
32+
* @type {Object}
33+
*/
1334
this.vertices = {
1435
near: [
1536
new Vector3(),
@@ -33,6 +54,13 @@ class CSMFrustum {
3354

3455
}
3556

57+
/**
58+
* Setups this CSM frustum from the given projection matrix and max far value.
59+
*
60+
* @param {Matrix4} projectionMatrix - The projection matrix, ususally of the scene's camera.
61+
* @param {number} maxFar - The maximum far value.
62+
* @returns {Object} An object representing the vertices of the near and far plane in view space.
63+
*/
3664
setFromProjectionMatrix( projectionMatrix, maxFar ) {
3765

3866
const zNear = this.zNear;
@@ -80,6 +108,14 @@ class CSMFrustum {
80108

81109
}
82110

111+
/**
112+
* Splits the CSM frustum by the given array. The new CSM frustum are pushed into the given
113+
* target array.
114+
*
115+
* @param {Array<number>} breaks - An array of numbers in the range `[0,1]` the defines how the
116+
* CSM frustum should be split up.
117+
* @param {Array<CSMFrustum>} target - The target array that holds the new CSM frustums.
118+
*/
83119
split( breaks, target ) {
84120

85121
while ( breaks.length > target.length ) {
@@ -134,6 +170,13 @@ class CSMFrustum {
134170

135171
}
136172

173+
/**
174+
* Transforms the given target CSM frustum into the different coordinate system defined by the
175+
* given camera matrix.
176+
*
177+
* @param {Matrix4} cameraMatrix - The matrix that defines the new coordinate system.
178+
* @param {CSMFrustum} target - The CSM to convert.
179+
*/
137180
toSpace( cameraMatrix, target ) {
138181

139182
for ( let i = 0; i < 4; i ++ ) {
@@ -152,4 +195,13 @@ class CSMFrustum {
152195

153196
}
154197

198+
/**
199+
* Constructor data of `CSMFrustum`.
200+
*
201+
* @typedef {Object} CSMFrustum~Data
202+
* @property {boolean} [webGL] - Whether this CSM frustum is used with WebGL or WebGPU.
203+
* @property {Matrix4} [projectionMatrix] - A projection matrix usually of the scene's camera.
204+
* @property {number} [maxFar] - The maximum far value.
205+
**/
206+
155207
export { CSMFrustum };

‎examples/jsm/csm/CSMHelper.js

+47
Original file line numberDiff line numberDiff line change
@@ -12,14 +12,51 @@ import {
1212
DoubleSide
1313
} from 'three';
1414

15+
/**
16+
* A helper for visualizing the cascades of a CSM instance.
17+
*
18+
* @augments Group
19+
*/
1520
class CSMHelper extends Group {
1621

22+
/**
23+
* Constructs a new CSM helper.
24+
*
25+
* @param {CSM|CSMShadowNode} csm - The CSM instance to visualize.
26+
*/
1727
constructor( csm ) {
1828

1929
super();
30+
31+
/**
32+
* The CSM instance to visualize.
33+
*
34+
* @type {CSM|CSMShadowNode}
35+
*/
2036
this.csm = csm;
37+
38+
/**
39+
* Whether to display the CSM frustum or not.
40+
*
41+
* @type {boolean}
42+
* @default true
43+
*/
2144
this.displayFrustum = true;
45+
46+
/**
47+
* Whether to display the cascade planes or not.
48+
*
49+
* @type {boolean}
50+
* @default true
51+
*/
2252
this.displayPlanes = true;
53+
54+
/**
55+
* Whether to display the shadow bounds or not.
56+
*
57+
* @type {boolean}
58+
* @default true
59+
*/
2360
this.displayShadowBounds = true;
2461

2562
const indices = new Uint16Array( [ 0, 1, 1, 2, 2, 3, 3, 0, 4, 5, 5, 6, 6, 7, 7, 4, 0, 4, 1, 5, 2, 6, 3, 7 ] );
@@ -37,6 +74,9 @@ class CSMHelper extends Group {
3774

3875
}
3976

77+
/**
78+
* This method must be called if one of the `display*` properties is changed at runtime.
79+
*/
4080
updateVisibility() {
4181

4282
const displayFrustum = this.displayFrustum;
@@ -63,6 +103,9 @@ class CSMHelper extends Group {
63103

64104
}
65105

106+
/**
107+
* Updates the helper. This method should be called in the app's animation loop.
108+
*/
66109
update() {
67110

68111
const csm = this.csm;
@@ -160,6 +203,10 @@ class CSMHelper extends Group {
160203

161204
}
162205

206+
/**
207+
* Frees the GPU-related resources allocated by this instance. Call this
208+
* method whenever this instance is no longer used in your app.
209+
*/
163210
dispose() {
164211

165212
const frustumLines = this.frustumLines;

‎examples/jsm/csm/CSMShader.js

+8
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,13 @@
11
import { ShaderChunk } from 'three';
22

3+
/** @module CSMShader */
4+
5+
/**
6+
* The object that holds the GLSL enhancements to enable CSM. This
7+
* code is injected into the built-in material shaders by {@link CSM}.
8+
*
9+
* @type {Object}
10+
*/
311
const CSMShader = {
412
lights_fragment_begin: /* glsl */`
513
vec3 geometryPosition = - vViewPosition;

‎examples/jsm/csm/CSMShadowNode.js

+156-13
Original file line numberDiff line numberDiff line change
@@ -35,34 +35,126 @@ class LwLight extends Object3D {
3535

3636
}
3737

38+
/**
39+
* An implementation of Cascade Shadow Maps (CSM).
40+
*
41+
* This module can only be used with {@link WebGPURenderer}. When using {@link WebGLRenderer},
42+
* use {@link CSM} instead.
43+
*
44+
* @augments ShadowBaseNode
45+
*/
3846
class CSMShadowNode extends ShadowBaseNode {
3947

48+
/**
49+
* Constructs a new CSM shadow node.
50+
*
51+
* @param {DirectionalLight} light - The CSM light.
52+
* @param {CSMShadowNode~Data} data - The CSM data.
53+
*/
4054
constructor( light, data = {} ) {
4155

4256
super( light );
4357

58+
/**
59+
* The scene's camera.
60+
*
61+
* @type {?Camera}
62+
* @default null
63+
*/
4464
this.camera = null;
65+
66+
/**
67+
* The number of cascades.
68+
*
69+
* @type {number}
70+
* @default 3
71+
*/
4572
this.cascades = data.cascades || 3;
73+
74+
/**
75+
* The maximum far value.
76+
*
77+
* @type {number}
78+
* @default 100000
79+
*/
4680
this.maxFar = data.maxFar || 100000;
81+
82+
/**
83+
* The frustum split mode.
84+
*
85+
* @type {('practical'|'uniform'|'logarithmic'|'custom')}
86+
* @default 'practical'
87+
*/
4788
this.mode = data.mode || 'practical';
89+
90+
/**
91+
* The light margin.
92+
*
93+
* @type {number}
94+
* @default 200
95+
*/
4896
this.lightMargin = data.lightMargin || 200;
97+
98+
/**
99+
* Custom split callback when using `mode='custom'`.
100+
*
101+
* @type {Function}
102+
*/
49103
this.customSplitsCallback = data.customSplitsCallback;
50104

105+
/**
106+
* Whether to fade between cascades or not.
107+
*
108+
* @type {boolean}
109+
* @default false
110+
*/
51111
this.fade = false;
52112

113+
/**
114+
* An array of numbers in the range `[0,1]` the defines how the
115+
* mainCSM frustum should be split up.
116+
*
117+
* @type {Array<number>}
118+
*/
53119
this.breaks = [];
54120

55121
this._cascades = [];
122+
123+
/**
124+
* The main frustum.
125+
*
126+
* @type {?CSMFrustum}
127+
* @default null
128+
*/
56129
this.mainFrustum = null;
130+
131+
/**
132+
* An array of frustums representing the cascades.
133+
*
134+
* @type {Array<CSMFrustum>}
135+
*/
57136
this.frustums = [];
58137

138+
/**
139+
* An array of directional lights which cast the shadows for
140+
* the different cascades. There is one directional light for each
141+
* cascade.
142+
*
143+
* @type {Array<DirectionalLight>}
144+
*/
59145
this.lights = [];
60146

61147
this._shadowNodes = [];
62148

63149
}
64150

65-
init( { camera, renderer } ) {
151+
/**
152+
* Inits the CSM shadow node.
153+
*
154+
* @private
155+
* @param {NodeBuilder} builder - The node builder.
156+
*/
157+
_init( { camera, renderer } ) {
66158

67159
this.camera = camera;
68160

@@ -97,7 +189,12 @@ class CSMShadowNode extends ShadowBaseNode {
97189

98190
}
99191

100-
initCascades() {
192+
/**
193+
* Inits the cascades according to the scene's camera and breaks configuration.
194+
*
195+
* @private
196+
*/
197+
_initCascades() {
101198

102199
const camera = this.camera;
103200
camera.updateProjectionMatrix();
@@ -107,7 +204,13 @@ class CSMShadowNode extends ShadowBaseNode {
107204

108205
}
109206

110-
getBreaks() {
207+
/**
208+
* Computes the breaks of this CSM instance based on the scene's camera, number of cascades
209+
* and the selected split mode.
210+
*
211+
* @private
212+
*/
213+
_getBreaks() {
111214

112215
const camera = this.camera;
113216
const far = Math.min( camera.far, this.maxFar );
@@ -178,7 +281,12 @@ class CSMShadowNode extends ShadowBaseNode {
178281

179282
}
180283

181-
setLightBreaks() {
284+
/**
285+
* Sets the ligth breaks.
286+
*
287+
* @private
288+
*/
289+
_setLightBreaks() {
182290

183291
for ( let i = 0, l = this.cascades; i < l; i ++ ) {
184292

@@ -191,7 +299,12 @@ class CSMShadowNode extends ShadowBaseNode {
191299

192300
}
193301

194-
updateShadowBounds() {
302+
/**
303+
* Updates the shadow bounds of this CSM instance.
304+
*
305+
* @private
306+
*/
307+
_updateShadowBounds() {
195308

196309
const frustums = this.frustums;
197310

@@ -243,16 +356,25 @@ class CSMShadowNode extends ShadowBaseNode {
243356

244357
}
245358

359+
/**
360+
* Applications must call this method every time they change camera or CSM settings.
361+
*/
246362
updateFrustums() {
247363

248-
this.getBreaks();
249-
this.initCascades();
250-
this.updateShadowBounds();
251-
this.setLightBreaks();
364+
this._getBreaks();
365+
this._initCascades();
366+
this._updateShadowBounds();
367+
this._setLightBreaks();
252368

253369
}
254370

255-
setupFade() {
371+
/**
372+
* Setups the TSL when using fading.
373+
*
374+
* @private
375+
* @return {ShaderCallNodeInternal}
376+
*/
377+
_setupFade() {
256378

257379
const cameraNear = reference( 'camera.near', 'float', this ).setGroup( renderGroup );
258380
const cascades = reference( '_cascades', 'vec2', this ).setGroup( renderGroup ).label( 'cascades' );
@@ -328,7 +450,13 @@ class CSMShadowNode extends ShadowBaseNode {
328450

329451
}
330452

331-
setupStandard() {
453+
/**
454+
* Setups the TSL when no fading (default).
455+
*
456+
* @private
457+
* @return {ShaderCallNodeInternal}
458+
*/
459+
_setupStandard() {
332460

333461
const cameraNear = reference( 'camera.near', 'float', this ).setGroup( renderGroup );
334462
const cascades = reference( '_cascades', 'vec2', this ).setGroup( renderGroup ).label( 'cascades' );
@@ -365,9 +493,9 @@ class CSMShadowNode extends ShadowBaseNode {
365493

366494
setup( builder ) {
367495

368-
if ( this.camera === null ) this.init( builder );
496+
if ( this.camera === null ) this._init( builder );
369497

370-
return this.fade === true ? this.setupFade() : this.setupStandard();
498+
return this.fade === true ? this._setupFade() : this._setupStandard();
371499

372500
}
373501

@@ -421,6 +549,10 @@ class CSMShadowNode extends ShadowBaseNode {
421549

422550
}
423551

552+
/**
553+
* Frees the GPU-related resources allocated by this instance. Call this
554+
* method whenever this instance is no longer used in your app.
555+
*/
424556
dispose() {
425557

426558
for ( let i = 0; i < this.lights.length; i ++ ) {
@@ -439,4 +571,15 @@ class CSMShadowNode extends ShadowBaseNode {
439571

440572
}
441573

574+
/**
575+
* Constructor data of `CSMShadowNode`.
576+
*
577+
* @typedef {Object} CSMShadowNode~Data
578+
* @property {number} [cascades=3] - The number of cascades.
579+
* @property {number} [maxFar=100000] - The maximum far value.
580+
* @property {('practical'|'uniform'|'logarithmic'|'custom')} [mode='practical'] - The frustum split mode.
581+
* @property {Function} [customSplitsCallback] - Custom split callback when using `mode='custom'`.
582+
* @property {number} [lightMargin=200] - The light margin.
583+
**/
584+
442585
export { CSMShadowNode };

‎examples/jsm/lines/Line2.js

+36
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,48 @@ import { LineSegments2 } from '../lines/LineSegments2.js';
22
import { LineGeometry } from '../lines/LineGeometry.js';
33
import { LineMaterial } from '../lines/LineMaterial.js';
44

5+
/**
6+
* A polyline drawn between vertices.
7+
*
8+
* This adds functionality beyond {@link Line}, like arbitrary line width and changing width to
9+
* be in world units.It extends {@link LineSegments2}, simplifying constructing segments from a
10+
* chain of points.
11+
*
12+
* This module can only be used with {@link WebGLRenderer}. When using {@link WebGPURenderer},
13+
* import the class from `lines/webgpu/Line2.js`.
14+
*
15+
* ```js
16+
* const geometry = new LineGeometry();
17+
* geometry.setPositions( positions );
18+
* geometry.setColors( colors );
19+
*
20+
* const material = new LineMaterial( { linewidth: 5, vertexColors: true } };
21+
*
22+
* const line = new Line2( geometry, material );
23+
* scene.add( line );
24+
* ```
25+
*
26+
* @augments LineSegments2
27+
*/
528
class Line2 extends LineSegments2 {
629

30+
/**
31+
* Constructs a new wide line.
32+
*
33+
* @param {LineGeometry} [geometry] - The line geometry.
34+
* @param {LineMaterial} [material] - The line material.
35+
*/
736
constructor( geometry = new LineGeometry(), material = new LineMaterial( { color: Math.random() * 0xffffff } ) ) {
837

938
super( geometry, material );
1039

40+
/**
41+
* This flag can be used for type testing.
42+
*
43+
* @type {boolean}
44+
* @readonly
45+
* @default true
46+
*/
1147
this.isLine2 = true;
1248

1349
this.type = 'Line2';

‎examples/jsm/lines/LineGeometry.js

+52
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,51 @@
11
import { LineSegmentsGeometry } from '../lines/LineSegmentsGeometry.js';
22

3+
/**
4+
* A chain of vertices, forming a polyline.
5+
*
6+
* This is used in {@link Line2} to describe the shape.
7+
*
8+
* ```js
9+
* const points = [
10+
* new THREE.Vector3( - 10, 0, 0 ),
11+
* new THREE.Vector3( 0, 5, 0 ),
12+
* new THREE.Vector3( 10, 0, 0 ),
13+
* ];
14+
*
15+
* const geometry = new LineGeometry();
16+
* geometry.setFromPoints( points );
17+
* ```
18+
*
19+
* @augments LineSegmentsGeometry
20+
*/
321
class LineGeometry extends LineSegmentsGeometry {
422

23+
/**
24+
* Constructs a new line geometry.
25+
*/
526
constructor() {
627

728
super();
829

30+
/**
31+
* This flag can be used for type testing.
32+
*
33+
* @type {boolean}
34+
* @readonly
35+
* @default true
36+
*/
937
this.isLineGeometry = true;
1038

1139
this.type = 'LineGeometry';
1240

1341
}
1442

43+
/**
44+
* Sets the given line positions for this goemetry.
45+
*
46+
* @param {Float32|Array} array - The position data to set.
47+
* @return {LineGeometry} A reference to this geometry.
48+
*/
1549
setPositions( array ) {
1650

1751
// converts [ x1, y1, z1, x2, y2, z2, ... ] to pairs format
@@ -37,6 +71,12 @@ class LineGeometry extends LineSegmentsGeometry {
3771

3872
}
3973

74+
/**
75+
* Sets the given line colors for this goemetry.
76+
*
77+
* @param {Float32|Array} array - The position data to set.
78+
* @return {LineGeometry} A reference to this geometry.
79+
*/
4080
setColors( array ) {
4181

4282
// converts [ r1, g1, b1, r2, g2, b2, ... ] to pairs format
@@ -62,6 +102,12 @@ class LineGeometry extends LineSegmentsGeometry {
62102

63103
}
64104

105+
/**
106+
* Setups this line segments geometry from the given sequence of points.
107+
*
108+
* @param {Array<Vector3|Vector2>} points - An array of points in 2D or 3D space.
109+
* @return {LineGeometry} A reference to this geometry.
110+
*/
65111
setFromPoints( points ) {
66112

67113
// converts a vector3 or vector2 array to pairs format
@@ -87,6 +133,12 @@ class LineGeometry extends LineSegmentsGeometry {
87133

88134
}
89135

136+
/**
137+
* Setups this line segments geometry from the given line.
138+
*
139+
* @param {Line} line - The line that should be used as a data source for this geometry.
140+
* @return {LineGeometry} A reference to this geometry.
141+
*/
90142
fromLine( line ) {
91143

92144
const geometry = line.geometry;

‎examples/jsm/lines/LineMaterial.js

+95
Original file line numberDiff line numberDiff line change
@@ -403,8 +403,28 @@ ShaderLib[ 'line' ] = {
403403
`
404404
};
405405

406+
/**
407+
* A material for drawing wireframe-style geometries.
408+
*
409+
* Unlike {@link LineBasicMaterial}, it supports arbitrary line widths and allows using world units
410+
* instead of screen space units. This material is used with {@link LineSegments2} and {@link Line2}.
411+
*
412+
* This module can only be used with {@link WebGLRenderer}. When using {@link WebGPURenderer},
413+
* use {@link Line2NodeMaterial}.
414+
*
415+
* @augments ShaderMaterial
416+
*/
406417
class LineMaterial extends ShaderMaterial {
407418

419+
/**
420+
* Constructs a new line segments geometry.
421+
*
422+
* @param {Object} [parameters] - An object with one or more properties
423+
* defining the material's appearance. Any property of the material
424+
* (including any property from inherited materials) can be passed
425+
* in here. Color values can be passed any type of value accepted
426+
* by {@link Color#set}.
427+
*/
408428
constructor( parameters ) {
409429

410430
super( {
@@ -419,12 +439,25 @@ class LineMaterial extends ShaderMaterial {
419439

420440
} );
421441

442+
/**
443+
* This flag can be used for type testing.
444+
*
445+
* @type {boolean}
446+
* @readonly
447+
* @default true
448+
*/
422449
this.isLineMaterial = true;
423450

424451
this.setValues( parameters );
425452

426453
}
427454

455+
/**
456+
* The material's color.
457+
*
458+
* @type {Color}
459+
* @default (1,1,1)
460+
*/
428461
get color() {
429462

430463
return this.uniforms.diffuse.value;
@@ -437,6 +470,12 @@ class LineMaterial extends ShaderMaterial {
437470

438471
}
439472

473+
/**
474+
* Whether the material's sizes (width, dash gaps) are in world units.
475+
*
476+
* @type {boolean}
477+
* @default false
478+
*/
440479
get worldUnits() {
441480

442481
return 'WORLD_UNITS' in this.defines;
@@ -457,6 +496,13 @@ class LineMaterial extends ShaderMaterial {
457496

458497
}
459498

499+
/**
500+
* Controls line thickness in CSS pixel units when `worldUnits` is `false` (default),
501+
* or in world units when `worldUnits` is `true`.
502+
*
503+
* @type {number}
504+
* @default 1
505+
*/
460506
get linewidth() {
461507

462508
return this.uniforms.linewidth.value;
@@ -470,6 +516,12 @@ class LineMaterial extends ShaderMaterial {
470516

471517
}
472518

519+
/**
520+
* Whether the line is dashed, or solid.
521+
*
522+
* @type {boolean}
523+
* @default false
524+
*/
473525
get dashed() {
474526

475527
return 'USE_DASH' in this.defines;
@@ -496,6 +548,12 @@ class LineMaterial extends ShaderMaterial {
496548

497549
}
498550

551+
/**
552+
* The scale of the dashes and gaps.
553+
*
554+
* @type {number}
555+
* @default 1
556+
*/
499557
get dashScale() {
500558

501559
return this.uniforms.dashScale.value;
@@ -508,6 +566,12 @@ class LineMaterial extends ShaderMaterial {
508566

509567
}
510568

569+
/**
570+
* The size of the dash.
571+
*
572+
* @type {number}
573+
* @default 1
574+
*/
511575
get dashSize() {
512576

513577
return this.uniforms.dashSize.value;
@@ -520,6 +584,12 @@ class LineMaterial extends ShaderMaterial {
520584

521585
}
522586

587+
/**
588+
* Where in the dash cycle the dash starts.
589+
*
590+
* @type {number}
591+
* @default 0
592+
*/
523593
get dashOffset() {
524594

525595
return this.uniforms.dashOffset.value;
@@ -532,6 +602,12 @@ class LineMaterial extends ShaderMaterial {
532602

533603
}
534604

605+
/**
606+
* The size of the gap.
607+
*
608+
* @type {number}
609+
* @default 0
610+
*/
535611
get gapSize() {
536612

537613
return this.uniforms.gapSize.value;
@@ -544,6 +620,12 @@ class LineMaterial extends ShaderMaterial {
544620

545621
}
546622

623+
/**
624+
* The opacity.
625+
*
626+
* @type {number}
627+
* @default 1
628+
*/
547629
get opacity() {
548630

549631
return this.uniforms.opacity.value;
@@ -557,6 +639,13 @@ class LineMaterial extends ShaderMaterial {
557639

558640
}
559641

642+
/**
643+
* The size of the viewport, in screen pixels. This must be kept updated to make
644+
* screen-space rendering accurate.The `LineSegments2.onBeforeRender` callback
645+
* performs the update for visible objects.
646+
*
647+
* @type {Vector2}
648+
*/
560649
get resolution() {
561650

562651
return this.uniforms.resolution.value;
@@ -569,6 +658,12 @@ class LineMaterial extends ShaderMaterial {
569658

570659
}
571660

661+
/**
662+
* Whether to use alphaToCoverage or not. When enabled, this can improve the
663+
* anti-aliasing of line edges when using MSAA.
664+
*
665+
* @type {Vector2}
666+
*/
572667
get alphaToCoverage() {
573668

574669
return 'USE_ALPHA_TO_COVERAGE' in this.defines;

‎examples/jsm/lines/LineSegments2.js

+51-2
Original file line numberDiff line numberDiff line change
@@ -224,22 +224,65 @@ function raycastScreenSpace( lineSegments, camera, intersects ) {
224224

225225
}
226226

227+
/**
228+
* A series of lines drawn between pairs of vertices.
229+
*
230+
* This adds functionality beyond {@link LineSegments}, like arbitrary line width and changing width
231+
* to be in world units. {@link Line2} extends this object, forming a polyline instead of individual
232+
* segments.
233+
*
234+
* This module can only be used with {@link WebGLRenderer}. When using {@link WebGPURenderer},
235+
* import the class from `lines/webgpu/LineSegments2.js`.
236+
*
237+
* ```js
238+
* const geometry = new LineSegmentsGeometry();
239+
* geometry.setPositions( positions );
240+
* geometry.setColors( colors );
241+
*
242+
* const material = new LineMaterial( { linewidth: 5, vertexColors: true } };
243+
*
244+
* const lineSegments = new LineSegments2( geometry, material );
245+
* scene.add( lineSegments );
246+
* ```
247+
*
248+
* @augments Mesh
249+
*/
227250
class LineSegments2 extends Mesh {
228251

252+
/**
253+
* Constructs a new wide line.
254+
*
255+
* @param {LineSegmentsGeometry} [geometry] - The line geometry.
256+
* @param {LineMaterial} [material] - The line material.
257+
*/
229258
constructor( geometry = new LineSegmentsGeometry(), material = new LineMaterial( { color: Math.random() * 0xffffff } ) ) {
230259

231260
super( geometry, material );
232261

262+
/**
263+
* This flag can be used for type testing.
264+
*
265+
* @type {boolean}
266+
* @readonly
267+
* @default true
268+
*/
233269
this.isLineSegments2 = true;
234270

235271
this.type = 'LineSegments2';
236272

237273
}
238274

239-
// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
240-
275+
/**
276+
* Computes an array of distance values which are necessary for rendering dashed lines.
277+
* For each vertex in the geometry, the method calculates the cumulative length from the
278+
* current point to the very beginning of the line.
279+
*
280+
* @return {LineSegments2} A reference to this instance.
281+
*/
241282
computeLineDistances() {
242283

284+
// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
285+
243286
const geometry = this.geometry;
244287

245288
const instanceStart = geometry.attributes.instanceStart;
@@ -265,6 +308,12 @@ class LineSegments2 extends Mesh {
265308

266309
}
267310

311+
/**
312+
* Computes intersection points between a casted ray and this instance.
313+
*
314+
* @param {Raycaster} raycaster - The raycaster.
315+
* @param {Array<Object>} intersects - The target array that holds the intersection points.
316+
*/
268317
raycast( raycaster, intersects ) {
269318

270319
const worldUnits = this.material.worldUnits;

‎examples/jsm/lines/LineSegmentsGeometry.js

+62-8
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,29 @@ import {
1212
const _box = new Box3();
1313
const _vector = new Vector3();
1414

15+
/**
16+
* A series of vertex pairs, forming line segments.
17+
*
18+
* This is used in {@link LineSegments2} to describe the shape.
19+
*
20+
* @augments InstancedBufferGeometry
21+
*/
1522
class LineSegmentsGeometry extends InstancedBufferGeometry {
1623

24+
/**
25+
* Constructs a new line segments geometry.
26+
*/
1727
constructor() {
1828

1929
super();
2030

31+
/**
32+
* This flag can be used for type testing.
33+
*
34+
* @type {boolean}
35+
* @readonly
36+
* @default true
37+
*/
2138
this.isLineSegmentsGeometry = true;
2239

2340
this.type = 'LineSegmentsGeometry';
@@ -32,6 +49,12 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
3249

3350
}
3451

52+
/**
53+
* Applies the given 4x4 tranformation matrix to the geometry.
54+
*
55+
* @param {Matrix4} matrix - The matrix to apply.
56+
* @return {LineSegmentsGeometry} A reference to this instance.
57+
*/
3558
applyMatrix4( matrix ) {
3659

3760
const start = this.attributes.instanceStart;
@@ -63,6 +86,13 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
6386

6487
}
6588

89+
/**
90+
* Sets the given line positions for this goemetry. The length must be a multiple of six since
91+
* each line segment is defined by a start end vertex in the pattern `(xyz xyz)`.
92+
*
93+
* @param {Float32|Array} array - The position data to set.
94+
* @return {LineSegmentsGeometry} A reference to this geometry.
95+
*/
6696
setPositions( array ) {
6797

6898
let lineSegments;
@@ -93,6 +123,13 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
93123

94124
}
95125

126+
/**
127+
* Sets the given line colors for this goemetry. The length must be a multiple of six since
128+
* each line segment is defined by a start end color in the pattern `(rgb rgb)`.
129+
*
130+
* @param {Float32|Array} array - The position data to set.
131+
* @return {LineSegmentsGeometry} A reference to this geometry.
132+
*/
96133
setColors( array ) {
97134

98135
let colors;
@@ -116,6 +153,12 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
116153

117154
}
118155

156+
/**
157+
* Setups this line segments geometry from the given wireframe geometry.
158+
*
159+
* @param {WireframeGeometry} geometry - The geometry that should be used as a data source for this geometry.
160+
* @return {LineSegmentsGeometry} A reference to this geometry.
161+
*/
119162
fromWireframeGeometry( geometry ) {
120163

121164
this.setPositions( geometry.attributes.position.array );
@@ -124,6 +167,12 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
124167

125168
}
126169

170+
/**
171+
* Setups this line segments geometry from the given edges geometry.
172+
*
173+
* @param {EdgesGeometry} geometry - The geometry that should be used as a data source for this geometry.
174+
* @return {LineSegmentsGeometry} A reference to this geometry.
175+
*/
127176
fromEdgesGeometry( geometry ) {
128177

129178
this.setPositions( geometry.attributes.position.array );
@@ -132,6 +181,12 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
132181

133182
}
134183

184+
/**
185+
* Setups this line segments geometry from the given mesh.
186+
*
187+
* @param {Mesh} mesh - The mesh geometry that should be used as a data source for this geometry.
188+
* @return {LineSegmentsGeometry} A reference to this geometry.
189+
*/
135190
fromMesh( mesh ) {
136191

137192
this.fromWireframeGeometry( new WireframeGeometry( mesh.geometry ) );
@@ -142,6 +197,13 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
142197

143198
}
144199

200+
/**
201+
* Setups this line segments geometry from the given line segments.
202+
*
203+
* @param {LineSegments} lineSegments - The line segments that should be used as a data source for this geometry.
204+
* Assumes the source geometry is not using indices.
205+
* @return {LineSegmentsGeometry} A reference to this geometry.
206+
*/
145207
fromLineSegments( lineSegments ) {
146208

147209
const geometry = lineSegments.geometry;
@@ -230,14 +292,6 @@ class LineSegmentsGeometry extends InstancedBufferGeometry {
230292

231293
}
232294

233-
applyMatrix( matrix ) {
234-
235-
console.warn( 'THREE.LineSegmentsGeometry: applyMatrix() has been renamed to applyMatrix4().' );
236-
237-
return this.applyMatrix4( matrix );
238-
239-
}
240-
241295
}
242296

243297
export { LineSegmentsGeometry };

‎examples/jsm/lines/Wireframe.js

+38-2
Original file line numberDiff line numberDiff line change
@@ -12,22 +12,58 @@ const _start = new Vector3();
1212
const _end = new Vector3();
1313
const _viewport = new Vector4();
1414

15+
/**
16+
* A class for creating wireframes based on wide lines.
17+
*
18+
* This module can only be used with {@link WebGLRenderer}. When using {@link WebGPURenderer},
19+
* import the class from `lines/webgpu/Wireframe.js`.
20+
*
21+
* ```js
22+
* const geometry = new THREE.IcosahedronGeometry();
23+
* const wireframeGeometry = new WireframeGeometry2( geo );
24+
*
25+
* const wireframe = new Wireframe( wireframeGeometry, material );
26+
* scene.add( wireframe );
27+
* ```
28+
*
29+
* @augments Mesh
30+
*/
1531
class Wireframe extends Mesh {
1632

33+
/**
34+
* Constructs a new wireframe.
35+
*
36+
* @param {LineSegmentsGeometry} [geometry] - The line geometry.
37+
* @param {LineMaterial} [material] - The line material.
38+
*/
1739
constructor( geometry = new LineSegmentsGeometry(), material = new LineMaterial( { color: Math.random() * 0xffffff } ) ) {
1840

1941
super( geometry, material );
2042

43+
/**
44+
* This flag can be used for type testing.
45+
*
46+
* @type {boolean}
47+
* @readonly
48+
* @default true
49+
*/
2150
this.isWireframe = true;
2251

2352
this.type = 'Wireframe';
2453

2554
}
2655

27-
// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
28-
56+
/**
57+
* Computes an array of distance values which are necessary for rendering dashed lines.
58+
* For each vertex in the geometry, the method calculates the cumulative length from the
59+
* current point to the very beginning of the line.
60+
*
61+
* @return {Wireframe} A reference to this instance.
62+
*/
2963
computeLineDistances() {
3064

65+
// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
66+
3167
const geometry = this.geometry;
3268

3369
const instanceStart = geometry.attributes.instanceStart;

‎examples/jsm/lines/WireframeGeometry2.js

+24
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,36 @@ import {
33
} from 'three';
44
import { LineSegmentsGeometry } from '../lines/LineSegmentsGeometry.js';
55

6+
/**
7+
* A special type of line segments geometry intended for wireframe rendering.
8+
*
9+
* This is used in {@link Wireframe} to describe the shape.
10+
*
11+
* ```js
12+
* const geometry = new THREE.IcosahedronGeometry();
13+
* const wireframeGeometry = new WireframeGeometry2( geo );
14+
* ```
15+
*
16+
* @augments LineSegmentsGeometry
17+
*/
618
class WireframeGeometry2 extends LineSegmentsGeometry {
719

20+
/**
21+
* Constructs a new wireframe geometry.
22+
*
23+
* @param {BufferGeometry} [geometry] - The geometry to render the wireframe for.
24+
*/
825
constructor( geometry ) {
926

1027
super();
1128

29+
/**
30+
* This flag can be used for type testing.
31+
*
32+
* @type {boolean}
33+
* @readonly
34+
* @default true
35+
*/
1236
this.isWireframeGeometry2 = true;
1337

1438
this.type = 'WireframeGeometry2';

‎examples/jsm/lines/webgpu/Line2.js

+25-1
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,37 @@ import { Line2NodeMaterial } from 'three/webgpu';
33
import { LineSegments2 } from './LineSegments2.js';
44
import { LineGeometry } from '../LineGeometry.js';
55

6-
6+
/**
7+
* A polyline drawn between vertices.
8+
*
9+
* This adds functionality beyond {@link Line}, like arbitrary line width and changing width to
10+
* be in world units.It extends {@link LineSegments2}, simplifying constructing segments from a
11+
* chain of points.
12+
*
13+
* This module can only be used with {@link WebGPURenderer}. When using {@link WebGLRenderer},
14+
* import the class from `lines/Line2.js`.
15+
*
16+
* @augments LineSegments2
17+
*/
718
class Line2 extends LineSegments2 {
819

20+
/**
21+
* Constructs a new wide line.
22+
*
23+
* @param {LineGeometry} [geometry] - The line geometry.
24+
* @param {Line2NodeMaterial} [material] - The line material.
25+
*/
926
constructor( geometry = new LineGeometry(), material = new Line2NodeMaterial( { color: Math.random() * 0xffffff } ) ) {
1027

1128
super( geometry, material );
1229

30+
/**
31+
* This flag can be used for type testing.
32+
*
33+
* @type {boolean}
34+
* @readonly
35+
* @default true
36+
*/
1337
this.isLine2 = true;
1438

1539
this.type = 'Line2';

‎examples/jsm/lines/webgpu/LineSegments2.js

+44-6
Original file line numberDiff line numberDiff line change
@@ -223,24 +223,56 @@ function raycastScreenSpace( lineSegments, camera, intersects ) {
223223

224224
}
225225

226+
/**
227+
* A series of lines drawn between pairs of vertices.
228+
*
229+
* This adds functionality beyond {@link LineSegments}, like arbitrary line width and changing width
230+
* to be in world units. {@link Line2} extends this object, forming a polyline instead of individual
231+
* segments.
232+
*
233+
* This module can only be used with {@link WebGPURenderer}. When using {@link WebGLRenderer},
234+
* import the class from `lines/LineSegments2.js`.
235+
*
236+
* @augments Mesh
237+
*/
226238
class LineSegments2 extends Mesh {
227239

240+
/**
241+
* Constructs a new wide line.
242+
*
243+
* @param {LineSegmentsGeometry} [geometry] - The line geometry.
244+
* @param {Line2NodeMaterial} [material] - The line material.
245+
*/
228246
constructor( geometry = new LineSegmentsGeometry(), material = new Line2NodeMaterial( { color: Math.random() * 0xffffff } ) ) {
229247

230248
super( geometry, material );
231249

250+
/**
251+
* This flag can be used for type testing.
252+
*
253+
* @type {boolean}
254+
* @readonly
255+
* @default true
256+
*/
232257
this.isLineSegments2 = true;
233258

234259
this.type = 'LineSegments2';
235260

236-
this.resolution = new Vector2();
261+
this._resolution = new Vector2();
237262

238263
}
239264

240-
// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
241-
265+
/**
266+
* Computes an array of distance values which are necessary for rendering dashed lines.
267+
* For each vertex in the geometry, the method calculates the cumulative length from the
268+
* current point to the very beginning of the line.
269+
*
270+
* @return {LineSegments2} A reference to this instance.
271+
*/
242272
computeLineDistances() {
243273

274+
// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
275+
244276
const geometry = this.geometry;
245277

246278
const instanceStart = geometry.attributes.instanceStart;
@@ -269,10 +301,16 @@ class LineSegments2 extends Mesh {
269301
onBeforeRender( renderer ) {
270302

271303
renderer.getViewport( _viewport );
272-
this.resolution.set( _viewport.z, _viewport.w );
304+
this._resolution.set( _viewport.z, _viewport.w );
273305

274306
}
275307

308+
/**
309+
* Computes intersection points between a casted ray and this instance.
310+
*
311+
* @param {Raycaster} raycaster - The raycaster.
312+
* @param {Array<Object>} intersects - The target array that holds the intersection points.
313+
*/
276314
raycast( raycaster, intersects ) {
277315

278316
const worldUnits = this.material.worldUnits;
@@ -312,7 +350,7 @@ class LineSegments2 extends Mesh {
312350
} else {
313351

314352
const distanceToSphere = Math.max( camera.near, _sphere.distanceToPoint( _ray.origin ) );
315-
sphereMargin = getWorldSpaceHalfWidth( camera, distanceToSphere, this.resolution );
353+
sphereMargin = getWorldSpaceHalfWidth( camera, distanceToSphere, this._resolution );
316354

317355
}
318356

@@ -342,7 +380,7 @@ class LineSegments2 extends Mesh {
342380
} else {
343381

344382
const distanceToBox = Math.max( camera.near, _box.distanceToPoint( _ray.origin ) );
345-
boxMargin = getWorldSpaceHalfWidth( camera, distanceToBox, this.resolution );
383+
boxMargin = getWorldSpaceHalfWidth( camera, distanceToBox, this._resolution );
346384

347385
}
348386

‎examples/jsm/lines/webgpu/Wireframe.js

+30-2
Original file line numberDiff line numberDiff line change
@@ -11,22 +11,50 @@ import { LineSegmentsGeometry } from '../../lines/LineSegmentsGeometry.js';
1111
const _start = new Vector3();
1212
const _end = new Vector3();
1313

14+
/**
15+
* A class for creating wireframes based on wide lines.
16+
*
17+
* This module can only be used with {@link WebGPURenderer}. When using {@link WebGLRenderer},
18+
* import the class from `lines/Wireframe.js`.
19+
*
20+
* @augments Mesh
21+
*/
1422
class Wireframe extends Mesh {
1523

24+
/**
25+
* Constructs a new wireframe.
26+
*
27+
* @param {LineSegmentsGeometry} [geometry] - The line geometry.
28+
* @param {Line2NodeMaterial} [material] - The line material.
29+
*/
1630
constructor( geometry = new LineSegmentsGeometry(), material = new Line2NodeMaterial( { color: Math.random() * 0xffffff } ) ) {
1731

1832
super( geometry, material );
1933

34+
/**
35+
* This flag can be used for type testing.
36+
*
37+
* @type {boolean}
38+
* @readonly
39+
* @default true
40+
*/
2041
this.isWireframe = true;
2142

2243
this.type = 'Wireframe';
2344

2445
}
2546

26-
// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
27-
47+
/**
48+
* Computes an array of distance values which are necessary for rendering dashed lines.
49+
* For each vertex in the geometry, the method calculates the cumulative length from the
50+
* current point to the very beginning of the line.
51+
*
52+
* @return {Wireframe} A reference to this instance.
53+
*/
2854
computeLineDistances() {
2955

56+
// for backwards-compatibility, but could be a method of LineSegmentsGeometry...
57+
3058
const geometry = this.geometry;
3159

3260
const instanceStart = geometry.attributes.instanceStart;

‎utils/docs/jsdoc.config.json

+4-1
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
"examples/jsm/animation",
1616
"examples/jsm/capabilities",
1717
"examples/jsm/controls",
18+
"examples/jsm/csm",
1819
"examples/jsm/curves",
1920
"examples/jsm/effects",
2021
"examples/jsm/environments",
@@ -24,14 +25,16 @@
2425
"examples/jsm/interactive",
2526
"examples/jsm/lighting",
2627
"examples/jsm/lights",
28+
"examples/jsm/lines",
2729
"examples/jsm/textures",
2830
"examples/jsm/tsl",
2931
"src"
3032
],
3133
"exclude": [
3234
"src/renderers/common/extras/PMREMGenerator.js",
3335
"examples/jsm/helpers/LightProbeHelperGPU.js",
34-
"examples/jsm/helpers/TextureHelperGPU.js"
36+
"examples/jsm/helpers/TextureHelperGPU.js",
37+
"examples/jsm/lines/webgpu"
3538
]
3639
}
3740
}

0 commit comments

Comments
 (0)
Please sign in to comment.