Skip to content

Commit 11c6c58

Browse files
Mugen87Mugen87
authored
Docs: More JSDoc. (#30592)
1 parent 3bb6e70 commit 11c6c58

14 files changed

+506
-16
lines changed

‎src/helpers/ArrowHelper.js‎

Lines changed: 60 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,37 @@ import { Vector3 } from '../math/Vector3.js';
1111
const _axis = /*@__PURE__*/ new Vector3();
1212
let _lineGeometry, _coneGeometry;
1313

14+
/**
15+
* An 3D arrow object for visualizing directions.
16+
*
17+
* ```js
18+
* const dir = new THREE.Vector3( 1, 2, 0 );
19+
*
20+
* //normalize the direction vector (convert to vector of length 1)
21+
* dir.normalize();
22+
*
23+
* const origin = new THREE.Vector3( 0, 0, 0 );
24+
* const length = 1;
25+
* const hex = 0xffff00;
26+
*
27+
* const arrowHelper = new THREE.ArrowHelper( dir, origin, length, hex );
28+
* scene.add( arrowHelper );
29+
* ```
30+
*
31+
* @augments Object3D
32+
*/
1433
class ArrowHelper extends Object3D {
1534

16-
// dir is assumed to be normalized
17-
35+
/**
36+
* Constructs a new arror helper.
37+
*
38+
* @param {Vector3} [dir=(0, 0, 1)] - The (normalized) direction vector.
39+
* @param {Vector3} [origin=(0, 0, 0)] - Point at which the arrow starts.
40+
* @param {number} [length=1] - Length of the arrow in world units.
41+
* @param {(number|Color|string)} [color=0xffff00] - Color of the arrow.
42+
* @param {number} [headLength=length*0.2] - The length of the head of the arrow.
43+
* @param {number} [headWidth=headLength*0.2] - The width of the head of the arrow.
44+
*/
1845
constructor( dir = new Vector3( 0, 0, 1 ), origin = new Vector3( 0, 0, 0 ), length = 1, color = 0xffff00, headLength = length * 0.2, headWidth = headLength * 0.2 ) {
1946

2047
super();
@@ -33,10 +60,20 @@ class ArrowHelper extends Object3D {
3360

3461
this.position.copy( origin );
3562

63+
/**
64+
* The line part of the arrow helper.
65+
*
66+
* @type {Line}
67+
*/
3668
this.line = new Line( _lineGeometry, new LineBasicMaterial( { color: color, toneMapped: false } ) );
3769
this.line.matrixAutoUpdate = false;
3870
this.add( this.line );
3971

72+
/**
73+
* The cone part of the arrow helper.
74+
*
75+
* @type {Mesh}
76+
*/
4077
this.cone = new Mesh( _coneGeometry, new MeshBasicMaterial( { color: color, toneMapped: false } ) );
4178
this.cone.matrixAutoUpdate = false;
4279
this.add( this.cone );
@@ -46,6 +83,11 @@ class ArrowHelper extends Object3D {
4683

4784
}
4885

86+
/**
87+
* Sets the direction of the helper.
88+
*
89+
* @param {Vector3} dir - The normalized direction vector.
90+
*/
4991
setDirection( dir ) {
5092

5193
// dir is assumed to be normalized
@@ -70,6 +112,13 @@ class ArrowHelper extends Object3D {
70112

71113
}
72114

115+
/**
116+
* Sets the length of the helper.
117+
*
118+
* @param {number} length - Length of the arrow in world units.
119+
* @param {number} [headLength=length*0.2] - The length of the head of the arrow.
120+
* @param {number} [headWidth=headLength*0.2] - The width of the head of the arrow.
121+
*/
73122
setLength( length, headLength = length * 0.2, headWidth = headLength * 0.2 ) {
74123

75124
this.line.scale.set( 1, Math.max( 0.0001, length - headLength ), 1 ); // see #17458
@@ -81,6 +130,11 @@ class ArrowHelper extends Object3D {
81130

82131
}
83132

133+
/**
134+
* Sets the color of the helper.
135+
*
136+
* @param {number|Color|string} color - The color to set.
137+
*/
84138
setColor( color ) {
85139

86140
this.line.material.color.set( color );
@@ -99,6 +153,10 @@ class ArrowHelper extends Object3D {
99153

100154
}
101155

156+
/**
157+
* Frees the GPU-related resources allocated by this instance. Call this
158+
* method whenever this instance is no longer used in your app.
159+
*/
102160
dispose() {
103161

104162
this.line.geometry.dispose();
@@ -110,5 +168,4 @@ class ArrowHelper extends Object3D {
110168

111169
}
112170

113-
114171
export { ArrowHelper };

‎src/helpers/AxesHelper.js‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,24 @@ import { Float32BufferAttribute } from '../core/BufferAttribute.js';
44
import { BufferGeometry } from '../core/BufferGeometry.js';
55
import { Color } from '../math/Color.js';
66

7+
/**
8+
* An axis object to visualize the 3 axes in a simple way.
9+
* The X axis is red. The Y axis is green. The Z axis is blue.
10+
*
11+
* ```js
12+
* const axesHelper = new THREE.AxesHelper( 5 );
13+
* scene.add( axesHelper );
14+
* ```
15+
*
16+
* @augments LineSegments
17+
*/
718
class AxesHelper extends LineSegments {
819

20+
/**
21+
* Constructs a new axes helper.
22+
*
23+
* @param {number} [size=1] - Size of the lines representing the axes.
24+
*/
925
constructor( size = 1 ) {
1026

1127
const vertices = [
@@ -32,6 +48,14 @@ class AxesHelper extends LineSegments {
3248

3349
}
3450

51+
/**
52+
* Defines the colors of the axes helper.
53+
*
54+
* @param {number|Color|string} xAxisColor - The color for the x axis.
55+
* @param {number|Color|string} yAxisColor - The color for the y axis.
56+
* @param {number|Color|string} zAxisColor - The color for the z axis.
57+
* @return {AxesHelper} A reference to this axes helper.
58+
*/
3559
setColors( xAxisColor, yAxisColor, zAxisColor ) {
3660

3761
const color = new Color();
@@ -55,6 +79,10 @@ class AxesHelper extends LineSegments {
5579

5680
}
5781

82+
/**
83+
* Frees the GPU-related resources allocated by this instance. Call this
84+
* method whenever this instance is no longer used in your app.
85+
*/
5886
dispose() {
5987

6088
this.geometry.dispose();

‎src/helpers/Box3Helper.js‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,27 @@ import { LineBasicMaterial } from '../materials/LineBasicMaterial.js';
33
import { BufferAttribute, Float32BufferAttribute } from '../core/BufferAttribute.js';
44
import { BufferGeometry } from '../core/BufferGeometry.js';
55

6+
/**
7+
* A helper object to visualize an instance of {@link Box3}.
8+
*
9+
* ```js
10+
* const box = new THREE.Box3();
11+
* box.setFromCenterAndSize( new THREE.Vector3( 1, 1, 1 ), new THREE.Vector3( 2, 1, 3 ) );
12+
*
13+
* const helper = new THREE.Box3Helper( box, 0xffff00 );
14+
* scene.add( helper )
15+
* ```
16+
*
17+
* @augments LineSegments
18+
*/
619
class Box3Helper extends LineSegments {
720

21+
/**
22+
* Constructs a new box3 helper.
23+
*
24+
* @param {Box3} box - The box to visualize.
25+
* @param {number|Color|string} [color=0xffff00] - The box's color.
26+
*/
827
constructor( box, color = 0xffff00 ) {
928

1029
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 ] );
@@ -19,6 +38,11 @@ class Box3Helper extends LineSegments {
1938

2039
super( geometry, new LineBasicMaterial( { color: color, toneMapped: false } ) );
2140

41+
/**
42+
* The box being visualized.
43+
*
44+
* @type {Box3}
45+
*/
2246
this.box = box;
2347

2448
this.type = 'Box3Helper';
@@ -43,6 +67,10 @@ class Box3Helper extends LineSegments {
4367

4468
}
4569

70+
/**
71+
* Frees the GPU-related resources allocated by this instance. Call this
72+
* method whenever this instance is no longer used in your app.
73+
*/
4674
dispose() {
4775

4876
this.geometry.dispose();

‎src/helpers/BoxHelper.js‎

Lines changed: 43 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,31 @@ import { BufferGeometry } from '../core/BufferGeometry.js';
66

77
const _box = /*@__PURE__*/ new Box3();
88

9+
/**
10+
* Helper object to graphically show the world-axis-aligned bounding box
11+
* around an object. The actual bounding box is handled with {@link Box3},
12+
* this is just a visual helper for debugging. It can be automatically
13+
* resized with {@link BoxHelper#update} when the object it's created from
14+
* is transformed. Note that the object must have a geometry for this to work,
15+
* so it won't work with sprites.
16+
*
17+
* ```js
18+
* const sphere = new THREE.SphereGeometry();
19+
* const object = new THREE.Mesh( sphere, new THREE.MeshBasicMaterial( 0xff0000 ) );
20+
* const box = new THREE.BoxHelper( object, 0xffff00 );
21+
* scene.add( box );
22+
* ```
23+
*
24+
* @augments LineSegments
25+
*/
926
class BoxHelper extends LineSegments {
1027

28+
/**
29+
* Constructs a new box helper.
30+
*
31+
* @param {Object3D} [object] - The 3D object to show the world-axis-aligned bounding box.
32+
* @param {number|Color|string} [color=0xffff00] - The box's color.
33+
*/
1134
constructor( object, color = 0xffff00 ) {
1235

1336
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 ] );
@@ -19,6 +42,11 @@ class BoxHelper extends LineSegments {
1942

2043
super( geometry, new LineBasicMaterial( { color: color, toneMapped: false } ) );
2144

45+
/**
46+
* The 3D object being visualized.
47+
*
48+
* @type {Object3D}
49+
*/
2250
this.object = object;
2351
this.type = 'BoxHelper';
2452

@@ -28,13 +56,11 @@ class BoxHelper extends LineSegments {
2856

2957
}
3058

31-
update( object ) {
32-
33-
if ( object !== undefined ) {
34-
35-
console.warn( 'THREE.BoxHelper: .update() has no longer arguments.' );
36-
37-
}
59+
/**
60+
* Updates the helper's geometry to match the dimensions of the object,
61+
* including any children.
62+
*/
63+
update() {
3864

3965
if ( this.object !== undefined ) {
4066

@@ -81,6 +107,12 @@ class BoxHelper extends LineSegments {
81107

82108
}
83109

110+
/**
111+
* Updates the wireframe box for the passed object.
112+
*
113+
* @param {Object3D} object - The 3D object to create the helper for.
114+
* @return {BoxHelper} A reference to this instance.
115+
*/
84116
setFromObject( object ) {
85117

86118
this.object = object;
@@ -100,6 +132,10 @@ class BoxHelper extends LineSegments {
100132

101133
}
102134

135+
/**
136+
* Frees the GPU-related resources allocated by this instance. Call this
137+
* method whenever this instance is no longer used in your app.
138+
*/
103139
dispose() {
104140

105141
this.geometry.dispose();

‎src/helpers/CameraHelper.js‎

Lines changed: 45 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,14 +11,28 @@ const _vector = /*@__PURE__*/ new Vector3();
1111
const _camera = /*@__PURE__*/ new Camera();
1212

1313
/**
14-
* - shows frustum, line of sight and up of the camera
15-
* - suitable for fast updates
16-
* - based on frustum visualization in lightgl.js shadowmap example
17-
* https://github.com/evanw/lightgl.js/blob/master/tests/shadowmap.html
14+
* This helps with visualizing what a camera contains in its frustum. It
15+
* visualizes the frustum of a camera using a line segments.
16+
*
17+
* Based on frustum visualization in [lightgl.js shadowmap example]{@link https://github.com/evanw/lightgl.js/blob/master/tests/shadowmap.html}.
18+
*
19+
* `CameraHelper` must be a child of the scene.
20+
*
21+
* ```js
22+
* const camera = new THREE.PerspectiveCamera( 75, window.innerWidth / window.innerHeight, 0.1, 1000 );
23+
* const helper = new THREE.CameraHelper( camera );
24+
* scene.add( helper );
25+
* ```
26+
*
27+
* @augments LineSegments
1828
*/
19-
2029
class CameraHelper extends LineSegments {
2130

31+
/**
32+
* Constructs a new arror helper.
33+
*
34+
* @param {Camera} camera - The camera to visualize.
35+
*/
2236
constructor( camera ) {
2337

2438
const geometry = new BufferGeometry();
@@ -105,12 +119,22 @@ class CameraHelper extends LineSegments {
105119

106120
this.type = 'CameraHelper';
107121

122+
/**
123+
* The camera being visualized.
124+
*
125+
* @type {Camera}
126+
*/
108127
this.camera = camera;
109128
if ( this.camera.updateProjectionMatrix ) this.camera.updateProjectionMatrix();
110129

111130
this.matrix = camera.matrixWorld;
112131
this.matrixAutoUpdate = false;
113132

133+
/**
134+
* This contains the points used to visualize the camera.
135+
*
136+
* @type {Object<string,Array<number>>}
137+
*/
114138
this.pointMap = pointMap;
115139

116140
this.update();
@@ -127,6 +151,15 @@ class CameraHelper extends LineSegments {
127151

128152
}
129153

154+
/**
155+
* Defines the colors of the helper.
156+
*
157+
* @param {Color} frustum - The frustum line color.
158+
* @param {Color} cone - The cone line color.
159+
* @param {Color} up - The up line color.
160+
* @param {Color} target - The target line color.
161+
* @param {Color} cross - The cross line color.
162+
*/
130163
setColors( frustum, cone, up, target, cross ) {
131164

132165
const geometry = this.geometry;
@@ -184,6 +217,9 @@ class CameraHelper extends LineSegments {
184217

185218
}
186219

220+
/**
221+
* Updates the helper based on the projection matrix of the camera.
222+
*/
187223
update() {
188224

189225
const geometry = this.geometry;
@@ -239,6 +275,10 @@ class CameraHelper extends LineSegments {
239275

240276
}
241277

278+
/**
279+
* Frees the GPU-related resources allocated by this instance. Call this
280+
* method whenever this instance is no longer used in your app.
281+
*/
242282
dispose() {
243283

244284
this.geometry.dispose();

0 commit comments

Comments
 (0)