Skip to content

Commit 6d005b1

Browse files
Mugen87Mugen87
authored
Docs: More JSDoc. (#30633)
1 parent 628fc0d commit 6d005b1

27 files changed

+2037
-91
lines changed

Diff for: ‎src/core/BufferAttribute.js

+413-3
Large diffs are not rendered by default.

Diff for: ‎src/core/BufferGeometry.js

+336
Large diffs are not rendered by default.

Diff for: ‎src/core/Clock.js

+60
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,64 @@
1+
/**
2+
* Class for keeping track of time.
3+
*/
14
class Clock {
25

6+
/**
7+
* Constructs a new clock.
8+
*
9+
* @param {boolean} [autoStart=true] - Whether to automatically start the clock when
10+
* `getDelta()` is called for the first time.
11+
*/
312
constructor( autoStart = true ) {
413

14+
/**
15+
* If set to `true`, the clock starts automatically when `getDelta()` is called
16+
* for the first time.
17+
*
18+
* @type {boolean}
19+
* @default true
20+
*/
521
this.autoStart = autoStart;
622

23+
/**
24+
* Holds the time at which the clock's `start()` method was last called.
25+
*
26+
* @type {number}
27+
* @default 0
28+
*/
729
this.startTime = 0;
30+
31+
/**
32+
* Holds the time at which the clock's `start()`, `getElapsedTime()` or
33+
* `getDelta()` methods were last called.
34+
*
35+
* @type {number}
36+
* @default 0
37+
*/
838
this.oldTime = 0;
39+
40+
/**
41+
* Keeps track of the total time that the clock has been running.
42+
*
43+
* @type {number}
44+
* @default 0
45+
*/
946
this.elapsedTime = 0;
1047

48+
/**
49+
* Whether the clock is running or not.
50+
*
51+
* @type {boolean}
52+
* @default true
53+
*/
1154
this.running = false;
1255

1356
}
1457

58+
/**
59+
* Starts the clock. When `autoStart` is set to `true`, the method is automatically
60+
* called by the class.
61+
*/
1562
start() {
1663

1764
this.startTime = now();
@@ -22,6 +69,9 @@ class Clock {
2269

2370
}
2471

72+
/**
73+
* Stops the clock.
74+
*/
2575
stop() {
2676

2777
this.getElapsedTime();
@@ -30,13 +80,23 @@ class Clock {
3080

3181
}
3282

83+
/**
84+
* Returns the elapsed time in seconds.
85+
*
86+
* @return {number} The elapsed time.
87+
*/
3388
getElapsedTime() {
3489

3590
this.getDelta();
3691
return this.elapsedTime;
3792

3893
}
3994

95+
/**
96+
* Returns the delta time in seconds.
97+
*
98+
* @return {number} The delta time.
99+
*/
40100
getDelta() {
41101

42102
let diff = 0;

Diff for: ‎src/core/GLBufferAttribute.js

+99
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,107 @@
1+
/**
2+
* An alternative version of a buffer attribute with more control over the VBO.
3+
*
4+
* The renderer does not construct a VBO for this kind of attribute. Instead, it uses
5+
* whatever VBO is passed in constructor and can later be altered via the `buffer` property.
6+
*
7+
* The most common use case for this class is when some kind of GPGPU calculation interferes
8+
* or even produces the VBOs in question.
9+
*
10+
* Notice that this class can only be used with {@link WebGLRenderer}.
11+
*/
112
class GLBufferAttribute {
213

14+
/**
15+
* Constructs a new GL buffer attribute.
16+
*
17+
* @param {WebGLBuffer} buffer - The native WebGL buffer.
18+
* @param {number} type - The native data type (e.g. `gl.FLOAT`).
19+
* @param {number} itemSize - The item size.
20+
* @param {number} elementSize - The corresponding size (in bytes) for the given `type` parameter.
21+
* @param {number} count - The expected number of vertices in VBO.
22+
*/
323
constructor( buffer, type, itemSize, elementSize, count ) {
424

25+
/**
26+
* This flag can be used for type testing.
27+
*
28+
* @type {boolean}
29+
* @readonly
30+
* @default true
31+
*/
532
this.isGLBufferAttribute = true;
633

34+
/**
35+
* The name of the buffer attribute.
36+
*
37+
* @type {string}
38+
*/
739
this.name = '';
840

41+
/**
42+
* The native WebGL buffer.
43+
*
44+
* @type {WebGLBuffer}
45+
*/
946
this.buffer = buffer;
47+
48+
/**
49+
* The native data type.
50+
*
51+
* @type {number}
52+
*/
1053
this.type = type;
54+
55+
/**
56+
* The item size, see {@link BufferAttribute#itemSize}.
57+
*
58+
* @type {number}
59+
*/
1160
this.itemSize = itemSize;
61+
62+
/**
63+
* The corresponding size (in bytes) for the given `type` parameter.
64+
*
65+
* @type {number}
66+
*/
1267
this.elementSize = elementSize;
68+
69+
/**
70+
* The expected number of vertices in VBO.
71+
*
72+
* @type {number}
73+
*/
1374
this.count = count;
1475

76+
/**
77+
* A version number, incremented every time the `needsUpdate` is set to `true`.
78+
*
79+
* @type {number}
80+
*/
1581
this.version = 0;
1682

1783
}
1884

85+
/**
86+
* Flag to indicate that this attribute has changed and should be re-sent to
87+
* the GPU. Set this to `true` when you modify the value of the array.
88+
*
89+
* @type {number}
90+
* @default false
91+
* @param {boolean} value
92+
*/
1993
set needsUpdate( value ) {
2094

2195
if ( value === true ) this.version ++;
2296

2397
}
2498

99+
/**
100+
* Sets the given native WebGL buffer.
101+
*
102+
* @param {WebGLBuffer} buffer - The buffer to set.
103+
* @return {BufferAttribute} A reference to this instance.
104+
*/
25105
setBuffer( buffer ) {
26106

27107
this.buffer = buffer;
@@ -30,6 +110,13 @@ class GLBufferAttribute {
30110

31111
}
32112

113+
/**
114+
* Sets the given native data type and element size.
115+
*
116+
* @param {number} type - The native data type (e.g. `gl.FLOAT`).
117+
* @param {number} elementSize - The corresponding size (in bytes) for the given `type` parameter.
118+
* @return {BufferAttribute} A reference to this instance.
119+
*/
33120
setType( type, elementSize ) {
34121

35122
this.type = type;
@@ -39,6 +126,12 @@ class GLBufferAttribute {
39126

40127
}
41128

129+
/**
130+
* Sets the item size.
131+
*
132+
* @param {number} itemSize - The item size.
133+
* @return {BufferAttribute} A reference to this instance.
134+
*/
42135
setItemSize( itemSize ) {
43136

44137
this.itemSize = itemSize;
@@ -47,6 +140,12 @@ class GLBufferAttribute {
47140

48141
}
49142

143+
/**
144+
* Sets the count (the expected number of vertices in VBO).
145+
*
146+
* @param {number} count - The count.
147+
* @return {BufferAttribute} A reference to this instance.
148+
*/
50149
setCount( count ) {
51150

52151
this.count = count;

Diff for: ‎src/core/InstancedBufferAttribute.js

+29
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,42 @@
11
import { BufferAttribute } from './BufferAttribute.js';
22

3+
/**
4+
* An instanced version of a buffer attribute.
5+
*
6+
* @augments BufferAttribute
7+
*/
38
class InstancedBufferAttribute extends BufferAttribute {
49

10+
/**
11+
* Constructs a new instanced buffer attribute.
12+
*
13+
* @param {TypedArray} array - The array holding the attribute data.
14+
* @param {number} itemSize - The item size.
15+
* @param {boolean} [normalized=false] - Whether the data are normalized or not.
16+
* @param {number} [meshPerAttribute=1] - How often a value of this buffer attribute should be repeated.
17+
*/
518
constructor( array, itemSize, normalized, meshPerAttribute = 1 ) {
619

720
super( array, itemSize, normalized );
821

22+
/**
23+
* This flag can be used for type testing.
24+
*
25+
* @type {boolean}
26+
* @readonly
27+
* @default true
28+
*/
929
this.isInstancedBufferAttribute = true;
1030

31+
/**
32+
* Defines how often a value of this buffer attribute should be repeated. A
33+
* value of one means that each value of the instanced attribute is used for
34+
* a single instance. A value of two means that each value is used for two
35+
* consecutive instances (and so on).
36+
*
37+
* @type {number}
38+
* @default 1
39+
*/
1140
this.meshPerAttribute = meshPerAttribute;
1241

1342
}

Diff for: ‎src/core/InstancedBufferGeometry.js

+20
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,34 @@
11
import { BufferGeometry } from './BufferGeometry.js';
22

3+
/**
4+
* An instanced version of a geometry.
5+
*/
36
class InstancedBufferGeometry extends BufferGeometry {
47

8+
/**
9+
* Constructs a new instanced buffer geometry.
10+
*/
511
constructor() {
612

713
super();
814

15+
/**
16+
* This flag can be used for type testing.
17+
*
18+
* @type {boolean}
19+
* @readonly
20+
* @default true
21+
*/
922
this.isInstancedBufferGeometry = true;
1023

1124
this.type = 'InstancedBufferGeometry';
25+
26+
/**
27+
* The instance count.
28+
*
29+
* @type {number}
30+
* @default Infinity
31+
*/
1232
this.instanceCount = Infinity;
1333

1434
}

Diff for: ‎src/core/InstancedInterleavedBuffer.js

+26
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,39 @@
11
import { InterleavedBuffer } from './InterleavedBuffer.js';
22

3+
/**
4+
* An instanced version of an interleaved buffer.
5+
*
6+
* @augments InterleavedBuffer
7+
*/
38
class InstancedInterleavedBuffer extends InterleavedBuffer {
49

10+
/**
11+
* Constructs a new instanced interleaved buffer.
12+
*
13+
* @param {TypedArray} array - A typed array with a shared buffer storing attribute data.
14+
* @param {number} stride - The number of typed-array elements per vertex.
15+
* @param {number} [meshPerAttribute=1] - Defines how often a value of this interleaved buffer should be repeated.
16+
*/
517
constructor( array, stride, meshPerAttribute = 1 ) {
618

719
super( array, stride );
820

21+
/**
22+
* This flag can be used for type testing.
23+
*
24+
* @type {boolean}
25+
* @readonly
26+
* @default true
27+
*/
928
this.isInstancedInterleavedBuffer = true;
1029

30+
/**
31+
* Defines how often a value of this buffer attribute should be repeated,
32+
* see {@link InstancedBufferAttribute#meshPerAttribute}.
33+
*
34+
* @type {number}
35+
* @default 1
36+
*/
1137
this.meshPerAttribute = meshPerAttribute;
1238

1339
}

0 commit comments

Comments
 (0)