diff --git a/src/helpers/ArrowHelper.js b/src/helpers/ArrowHelper.js index 50d9a6dabe9365..d7bf25059c8b3a 100644 --- a/src/helpers/ArrowHelper.js +++ b/src/helpers/ArrowHelper.js @@ -11,10 +11,37 @@ import { Vector3 } from '../math/Vector3.js'; const _axis = /*@__PURE__*/ new Vector3(); let _lineGeometry, _coneGeometry; +/** + * An 3D arrow object for visualizing directions. + * + * ```js + * const dir = new THREE.Vector3( 1, 2, 0 ); + * + * //normalize the direction vector (convert to vector of length 1) + * dir.normalize(); + * + * const origin = new THREE.Vector3( 0, 0, 0 ); + * const length = 1; + * const hex = 0xffff00; + * + * const arrowHelper = new THREE.ArrowHelper( dir, origin, length, hex ); + * scene.add( arrowHelper ); + * ``` + * + * @augments Object3D + */ class ArrowHelper extends Object3D { - // dir is assumed to be normalized - + /** + * Constructs a new arror helper. + * + * @param {Vector3} [dir=(0, 0, 1)] - The (normalized) direction vector. + * @param {Vector3} [origin=(0, 0, 0)] - Point at which the arrow starts. + * @param {number} [length=1] - Length of the arrow in world units. + * @param {(number|Color|string)} [color=0xffff00] - Color of the arrow. + * @param {number} [headLength=length*0.2] - The length of the head of the arrow. + * @param {number} [headWidth=headLength*0.2] - The width of the head of the arrow. + */ 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 ) { super(); @@ -33,10 +60,20 @@ class ArrowHelper extends Object3D { this.position.copy( origin ); + /** + * The line part of the arrow helper. + * + * @type {Line} + */ this.line = new Line( _lineGeometry, new LineBasicMaterial( { color: color, toneMapped: false } ) ); this.line.matrixAutoUpdate = false; this.add( this.line ); + /** + * The cone part of the arrow helper. + * + * @type {Mesh} + */ this.cone = new Mesh( _coneGeometry, new MeshBasicMaterial( { color: color, toneMapped: false } ) ); this.cone.matrixAutoUpdate = false; this.add( this.cone ); @@ -46,6 +83,11 @@ class ArrowHelper extends Object3D { } + /** + * Sets the direction of the helper. + * + * @param {Vector3} dir - The normalized direction vector. + */ setDirection( dir ) { // dir is assumed to be normalized @@ -70,6 +112,13 @@ class ArrowHelper extends Object3D { } + /** + * Sets the length of the helper. + * + * @param {number} length - Length of the arrow in world units. + * @param {number} [headLength=length*0.2] - The length of the head of the arrow. + * @param {number} [headWidth=headLength*0.2] - The width of the head of the arrow. + */ setLength( length, headLength = length * 0.2, headWidth = headLength * 0.2 ) { this.line.scale.set( 1, Math.max( 0.0001, length - headLength ), 1 ); // see #17458 @@ -81,6 +130,11 @@ class ArrowHelper extends Object3D { } + /** + * Sets the color of the helper. + * + * @param {number|Color|string} color - The color to set. + */ setColor( color ) { this.line.material.color.set( color ); @@ -99,6 +153,10 @@ class ArrowHelper extends Object3D { } + /** + * Frees the GPU-related resources allocated by this instance. Call this + * method whenever this instance is no longer used in your app. + */ dispose() { this.line.geometry.dispose(); @@ -110,5 +168,4 @@ class ArrowHelper extends Object3D { } - export { ArrowHelper }; diff --git a/src/helpers/AxesHelper.js b/src/helpers/AxesHelper.js index 48f7ac5bf87029..305eae5e5b21ef 100644 --- a/src/helpers/AxesHelper.js +++ b/src/helpers/AxesHelper.js @@ -4,8 +4,24 @@ import { Float32BufferAttribute } from '../core/BufferAttribute.js'; import { BufferGeometry } from '../core/BufferGeometry.js'; import { Color } from '../math/Color.js'; +/** + * An axis object to visualize the 3 axes in a simple way. + * The X axis is red. The Y axis is green. The Z axis is blue. + * + * ```js + * const axesHelper = new THREE.AxesHelper( 5 ); + * scene.add( axesHelper ); + * ``` + * + * @augments LineSegments + */ class AxesHelper extends LineSegments { + /** + * Constructs a new axes helper. + * + * @param {number} [size=1] - Size of the lines representing the axes. + */ constructor( size = 1 ) { const vertices = [ @@ -32,6 +48,14 @@ class AxesHelper extends LineSegments { } + /** + * Defines the colors of the axes helper. + * + * @param {number|Color|string} xAxisColor - The color for the x axis. + * @param {number|Color|string} yAxisColor - The color for the y axis. + * @param {number|Color|string} zAxisColor - The color for the z axis. + * @return {AxesHelper} A reference to this axes helper. + */ setColors( xAxisColor, yAxisColor, zAxisColor ) { const color = new Color(); @@ -55,6 +79,10 @@ class AxesHelper extends LineSegments { } + /** + * Frees the GPU-related resources allocated by this instance. Call this + * method whenever this instance is no longer used in your app. + */ dispose() { this.geometry.dispose(); diff --git a/src/helpers/Box3Helper.js b/src/helpers/Box3Helper.js index 385ea8096d2f92..af0ceee8449349 100644 --- a/src/helpers/Box3Helper.js +++ b/src/helpers/Box3Helper.js @@ -3,8 +3,27 @@ import { LineBasicMaterial } from '../materials/LineBasicMaterial.js'; import { BufferAttribute, Float32BufferAttribute } from '../core/BufferAttribute.js'; import { BufferGeometry } from '../core/BufferGeometry.js'; +/** + * A helper object to visualize an instance of {@link Box3}. + * + * ```js + * const box = new THREE.Box3(); + * box.setFromCenterAndSize( new THREE.Vector3( 1, 1, 1 ), new THREE.Vector3( 2, 1, 3 ) ); + * + * const helper = new THREE.Box3Helper( box, 0xffff00 ); + * scene.add( helper ) + * ``` + * + * @augments LineSegments + */ class Box3Helper extends LineSegments { + /** + * Constructs a new box3 helper. + * + * @param {Box3} box - The box to visualize. + * @param {number|Color|string} [color=0xffff00] - The box's color. + */ constructor( box, color = 0xffff00 ) { 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 { super( geometry, new LineBasicMaterial( { color: color, toneMapped: false } ) ); + /** + * The box being visualized. + * + * @type {Box3} + */ this.box = box; this.type = 'Box3Helper'; @@ -43,6 +67,10 @@ class Box3Helper extends LineSegments { } + /** + * Frees the GPU-related resources allocated by this instance. Call this + * method whenever this instance is no longer used in your app. + */ dispose() { this.geometry.dispose(); diff --git a/src/helpers/BoxHelper.js b/src/helpers/BoxHelper.js index 2629396bed6d50..ce41a78db7c772 100644 --- a/src/helpers/BoxHelper.js +++ b/src/helpers/BoxHelper.js @@ -6,8 +6,31 @@ import { BufferGeometry } from '../core/BufferGeometry.js'; const _box = /*@__PURE__*/ new Box3(); +/** + * Helper object to graphically show the world-axis-aligned bounding box + * around an object. The actual bounding box is handled with {@link Box3}, + * this is just a visual helper for debugging. It can be automatically + * resized with {@link BoxHelper#update} when the object it's created from + * is transformed. Note that the object must have a geometry for this to work, + * so it won't work with sprites. + * + * ```js + * const sphere = new THREE.SphereGeometry(); + * const object = new THREE.Mesh( sphere, new THREE.MeshBasicMaterial( 0xff0000 ) ); + * const box = new THREE.BoxHelper( object, 0xffff00 ); + * scene.add( box ); + * ``` + * + * @augments LineSegments + */ class BoxHelper extends LineSegments { + /** + * Constructs a new box helper. + * + * @param {Object3D} [object] - The 3D object to show the world-axis-aligned bounding box. + * @param {number|Color|string} [color=0xffff00] - The box's color. + */ constructor( object, color = 0xffff00 ) { 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 { super( geometry, new LineBasicMaterial( { color: color, toneMapped: false } ) ); + /** + * The 3D object being visualized. + * + * @type {Object3D} + */ this.object = object; this.type = 'BoxHelper'; @@ -28,13 +56,11 @@ class BoxHelper extends LineSegments { } - update( object ) { - - if ( object !== undefined ) { - - console.warn( 'THREE.BoxHelper: .update() has no longer arguments.' ); - - } + /** + * Updates the helper's geometry to match the dimensions of the object, + * including any children. + */ + update() { if ( this.object !== undefined ) { @@ -81,6 +107,12 @@ class BoxHelper extends LineSegments { } + /** + * Updates the wireframe box for the passed object. + * + * @param {Object3D} object - The 3D object to create the helper for. + * @return {BoxHelper} A reference to this instance. + */ setFromObject( object ) { this.object = object; @@ -100,6 +132,10 @@ class BoxHelper extends LineSegments { } + /** + * Frees the GPU-related resources allocated by this instance. Call this + * method whenever this instance is no longer used in your app. + */ dispose() { this.geometry.dispose(); diff --git a/src/helpers/CameraHelper.js b/src/helpers/CameraHelper.js index 85273e836da883..ffce1b9b5fb5db 100644 --- a/src/helpers/CameraHelper.js +++ b/src/helpers/CameraHelper.js @@ -11,14 +11,28 @@ const _vector = /*@__PURE__*/ new Vector3(); const _camera = /*@__PURE__*/ new Camera(); /** - * - shows frustum, line of sight and up of the camera - * - suitable for fast updates - * - based on frustum visualization in lightgl.js shadowmap example - * https://github.com/evanw/lightgl.js/blob/master/tests/shadowmap.html + * This helps with visualizing what a camera contains in its frustum. It + * visualizes the frustum of a camera using a line segments. + * + * Based on frustum visualization in [lightgl.js shadowmap example]{@link https://github.com/evanw/lightgl.js/blob/master/tests/shadowmap.html}. + * + * `CameraHelper` must be a child of the scene. + * + * ```js + * const camera = new THREE.PerspectiveCamera( 75, window.innerWidth / window.innerHeight, 0.1, 1000 ); + * const helper = new THREE.CameraHelper( camera ); + * scene.add( helper ); + * ``` + * + * @augments LineSegments */ - class CameraHelper extends LineSegments { + /** + * Constructs a new arror helper. + * + * @param {Camera} camera - The camera to visualize. + */ constructor( camera ) { const geometry = new BufferGeometry(); @@ -105,12 +119,22 @@ class CameraHelper extends LineSegments { this.type = 'CameraHelper'; + /** + * The camera being visualized. + * + * @type {Camera} + */ this.camera = camera; if ( this.camera.updateProjectionMatrix ) this.camera.updateProjectionMatrix(); this.matrix = camera.matrixWorld; this.matrixAutoUpdate = false; + /** + * This contains the points used to visualize the camera. + * + * @type {Object>} + */ this.pointMap = pointMap; this.update(); @@ -127,6 +151,15 @@ class CameraHelper extends LineSegments { } + /** + * Defines the colors of the helper. + * + * @param {Color} frustum - The frustum line color. + * @param {Color} cone - The cone line color. + * @param {Color} up - The up line color. + * @param {Color} target - The target line color. + * @param {Color} cross - The cross line color. + */ setColors( frustum, cone, up, target, cross ) { const geometry = this.geometry; @@ -184,6 +217,9 @@ class CameraHelper extends LineSegments { } + /** + * Updates the helper based on the projection matrix of the camera. + */ update() { const geometry = this.geometry; @@ -239,6 +275,10 @@ class CameraHelper extends LineSegments { } + /** + * Frees the GPU-related resources allocated by this instance. Call this + * method whenever this instance is no longer used in your app. + */ dispose() { this.geometry.dispose(); diff --git a/src/helpers/DirectionalLightHelper.js b/src/helpers/DirectionalLightHelper.js index f1b9c85c4a03cf..bbaa16d6993945 100644 --- a/src/helpers/DirectionalLightHelper.js +++ b/src/helpers/DirectionalLightHelper.js @@ -9,17 +9,51 @@ const _v1 = /*@__PURE__*/ new Vector3(); const _v2 = /*@__PURE__*/ new Vector3(); const _v3 = /*@__PURE__*/ new Vector3(); +/** + * Helper object to assist with visualizing a {@link DirectionalLight}'s + * effect on the scene. This consists of plane and a line representing the + * light's position and direction. + * + * ```js + * const light = new THREE.DirectionalLight( 0xFFFFFF ); + * scene.add( light ); + * + * const helper = new THREE.DirectionalLightHelper( light, 5 ); + * scene.add( helper ); + * ``` + * + * @augments Object3D + */ class DirectionalLightHelper extends Object3D { + /** + * Constructs a new directional light helper. + * + * @param {DirectionalLight} light - The light to be visualized. + * @param {number} [size=1] - The dimensions of the plane. + * @param {number|Color|string} [color] - The helper's color. If not set, the helper will take + * the color of the light. + */ constructor( light, size, color ) { super(); + /** + * The light being visualized. + * + * @type {DirectionalLight} + */ this.light = light; this.matrix = light.matrixWorld; this.matrixAutoUpdate = false; + /** + * The color parameter passed in the constructor. + * If not set, the helper will take the color of the light. + * + * @type {number|Color|string} + */ this.color = color; this.type = 'DirectionalLightHelper'; @@ -37,12 +71,22 @@ class DirectionalLightHelper extends Object3D { const material = new LineBasicMaterial( { fog: false, toneMapped: false } ); + /** + * Contains the line showing the location of the directional light. + * + * @type {Line} + */ this.lightPlane = new Line( geometry, material ); this.add( this.lightPlane ); geometry = new BufferGeometry(); geometry.setAttribute( 'position', new Float32BufferAttribute( [ 0, 0, 0, 0, 0, 1 ], 3 ) ); + /** + * Represents the target line of the directional light. + * + * @type {Line} + */ this.targetLine = new Line( geometry, material ); this.add( this.targetLine ); @@ -50,6 +94,10 @@ class DirectionalLightHelper extends Object3D { } + /** + * Frees the GPU-related resources allocated by this instance. Call this + * method whenever this instance is no longer used in your app. + */ dispose() { this.lightPlane.geometry.dispose(); @@ -59,6 +107,10 @@ class DirectionalLightHelper extends Object3D { } + /** + * Updates the helper to match the position and direction of the + * light being visualized. + */ update() { this.light.updateWorldMatrix( true, false ); diff --git a/src/helpers/GridHelper.js b/src/helpers/GridHelper.js index 68f4dadd3e8b2c..78c4c02da5a3c1 100644 --- a/src/helpers/GridHelper.js +++ b/src/helpers/GridHelper.js @@ -4,8 +4,30 @@ import { Float32BufferAttribute } from '../core/BufferAttribute.js'; import { BufferGeometry } from '../core/BufferGeometry.js'; import { Color } from '../math/Color.js'; +/** + * The helper is an object to define grids. Grids are two-dimensional + * arrays of lines. + * + * ```js + * const size = 10; + * const divisions = 10; + * + * const gridHelper = new THREE.GridHelper( size, divisions ); + * scene.add( gridHelper ); + * ``` + * + * @augments LineSegments + */ class GridHelper extends LineSegments { + /** + * Constructs a new grid helper. + * + * @param {number} [size=10] - The size of the grid. + * @param {number} [divisions=10] - The number of divisions across the grid. + * @param {number|Color|string} [color1=0x444444] - The color of the center line. + * @param {number|Color|string} [color2=0x888888] - The color of the lines of the grid. + */ constructor( size = 10, divisions = 10, color1 = 0x444444, color2 = 0x888888 ) { color1 = new Color( color1 ); @@ -43,6 +65,10 @@ class GridHelper extends LineSegments { } + /** + * Frees the GPU-related resources allocated by this instance. Call this + * method whenever this instance is no longer used in your app. + */ dispose() { this.geometry.dispose(); diff --git a/src/helpers/HemisphereLightHelper.js b/src/helpers/HemisphereLightHelper.js index b54f6938cd1763..f7c7c168538304 100644 --- a/src/helpers/HemisphereLightHelper.js +++ b/src/helpers/HemisphereLightHelper.js @@ -10,17 +10,48 @@ const _vector = /*@__PURE__*/ new Vector3(); const _color1 = /*@__PURE__*/ new Color(); const _color2 = /*@__PURE__*/ new Color(); +/** + * Creates a visual aid consisting of a spherical mesh for a + * given {@link HemisphereLight}. + * + * ```js + * const light = new THREE.HemisphereLight( 0xffffbb, 0x080820, 1 ); + * const helper = new THREE.HemisphereLightHelper( light, 5 ); + * scene.add( helper ); + * ``` + * + * @augments Object3D + */ class HemisphereLightHelper extends Object3D { + /** + * Constructs a new hemisphere light helper. + * + * @param {HemisphereLight} light - The light to be visualized. + * @param {number} [size=1] - The size of the mesh used to visualize the light. + * @param {number|Color|string} [color] - The helper's color. If not set, the helper will take + * the color of the light. + */ constructor( light, size, color ) { super(); + /** + * The light being visualized. + * + * @type {HemisphereLight} + */ this.light = light; this.matrix = light.matrixWorld; this.matrixAutoUpdate = false; + /** + * The color parameter passed in the constructor. + * If not set, the helper will take the color of the light. + * + * @type {number|Color|string} + */ this.color = color; this.type = 'HemisphereLightHelper'; @@ -42,6 +73,10 @@ class HemisphereLightHelper extends Object3D { } + /** + * Frees the GPU-related resources allocated by this instance. Call this + * method whenever this instance is no longer used in your app. + */ dispose() { this.children[ 0 ].geometry.dispose(); @@ -49,6 +84,10 @@ class HemisphereLightHelper extends Object3D { } + /** + * Updates the helper to match the position and direction of the + * light being visualized. + */ update() { const mesh = this.children[ 0 ]; diff --git a/src/helpers/PlaneHelper.js b/src/helpers/PlaneHelper.js index f3106afe648c6e..f1f36324c0c938 100644 --- a/src/helpers/PlaneHelper.js +++ b/src/helpers/PlaneHelper.js @@ -5,8 +5,26 @@ import { MeshBasicMaterial } from '../materials/MeshBasicMaterial.js'; import { Float32BufferAttribute } from '../core/BufferAttribute.js'; import { BufferGeometry } from '../core/BufferGeometry.js'; +/** + * A helper object to visualize an instance of {@link Plane}. + * + * ```js + * const plane = new THREE.Plane( new THREE.Vector3( 1, 1, 0.2 ), 3 ); + * const helper = new THREE.PlaneHelper( plane, 1, 0xffff00 ); + * scene.add( helper ); + * ``` + * + * @augments Line + */ class PlaneHelper extends Line { + /** + * Constructs a new plane helper. + * + * @param {Plane} plane - The plane to be visualized. + * @param {number} [size=1] - The side length of plane helper. + * @param {number|Color|string} [hex=0xffff00] - The helper's color. + */ constructor( plane, size = 1, hex = 0xffff00 ) { const color = hex; @@ -21,8 +39,19 @@ class PlaneHelper extends Line { this.type = 'PlaneHelper'; + /** + * The plane being visualized. + * + * @type {Plane} + */ this.plane = plane; + /** + * The side length of plane helper. + * + * @type {number} + * @default 1 + */ this.size = size; const positions2 = [ 1, 1, 0, - 1, 1, 0, - 1, - 1, 0, 1, 1, 0, - 1, - 1, 0, 1, - 1, 0 ]; @@ -49,6 +78,10 @@ class PlaneHelper extends Line { } + /** + * Updates the helper to match the position and direction of the + * light being visualized. + */ dispose() { this.geometry.dispose(); diff --git a/src/helpers/PointLightHelper.js b/src/helpers/PointLightHelper.js index 88990d49128751..1c7004db73bba8 100644 --- a/src/helpers/PointLightHelper.js +++ b/src/helpers/PointLightHelper.js @@ -2,8 +2,32 @@ import { Mesh } from '../objects/Mesh.js'; import { MeshBasicMaterial } from '../materials/MeshBasicMaterial.js'; import { SphereGeometry } from '../geometries/SphereGeometry.js'; +/** + * This displays a helper object consisting of a spherical mesh for + * visualizing an instance of {@link PointLight}. + * + * ```js + * const pointLight = new THREE.PointLight( 0xff0000, 1, 100 ); + * pointLight.position.set( 10, 10, 10 ); + * scene.add( pointLight ); + * + * const sphereSize = 1; + * const pointLightHelper = new THREE.PointLightHelper( pointLight, sphereSize ); + * scene.add( pointLightHelper ); + * ``` + * + * @augments Mesh + */ class PointLightHelper extends Mesh { + /** + * Constructs a new point light helper. + * + * @param {PointLight} light - The light to be visualized. + * @param {number} [sphereSize=1] - The size of the sphere helper. + * @param {number|Color|string} [color] - The helper's color. If not set, the helper will take + * the color of the light. + */ constructor( light, sphereSize, color ) { const geometry = new SphereGeometry( sphereSize, 4, 2 ); @@ -11,8 +35,19 @@ class PointLightHelper extends Mesh { super( geometry, material ); + /** + * The light being visualized. + * + * @type {HemisphereLight} + */ this.light = light; + /** + * The color parameter passed in the constructor. + * If not set, the helper will take the color of the light. + * + * @type {number|Color|string} + */ this.color = color; this.type = 'PointLightHelper'; @@ -48,6 +83,10 @@ class PointLightHelper extends Mesh { } + /** + * Frees the GPU-related resources allocated by this instance. Call this + * method whenever this instance is no longer used in your app. + */ dispose() { this.geometry.dispose(); @@ -55,6 +94,10 @@ class PointLightHelper extends Mesh { } + /** + * Updates the helper to match the position of the + * light being visualized. + */ update() { this.light.updateWorldMatrix( true, false ); diff --git a/src/helpers/PolarGridHelper.js b/src/helpers/PolarGridHelper.js index 83695f32c5a49c..90994e03ebc476 100644 --- a/src/helpers/PolarGridHelper.js +++ b/src/helpers/PolarGridHelper.js @@ -4,8 +4,34 @@ import { Float32BufferAttribute } from '../core/BufferAttribute.js'; import { BufferGeometry } from '../core/BufferGeometry.js'; import { Color } from '../math/Color.js'; +/** + * This helper is an object to define polar grids. Grids are + * two-dimensional arrays of lines. + * + * ```js + * const radius = 10; + * const sectors = 16; + * const rings = 8; + * const divisions = 64; + * + * const helper = new THREE.PolarGridHelper( radius, sectors, rings, divisions ); + * scene.add( helper ); + * ``` + * + * @augments LineSegments + */ class PolarGridHelper extends LineSegments { + /** + * Constructs a new polar grid helper. + * + * @param {number} [radius=10] - The radius of the polar grid. This can be any positive number. + * @param {number} [sectors=16] - The number of sectors the grid will be divided into. This can be any positive integer. + * @param {number} [rings=16] - The number of rings. This can be any positive integer. + * @param {number} [divisions=64] - The number of line segments used for each circle. This can be any positive integer. + * @param {number|Color|string} [color1=0x444444] - The first color used for grid elements. + * @param {number|Color|string} [color2=0x888888] - The second color used for grid elements. + */ constructor( radius = 10, sectors = 16, rings = 8, divisions = 64, color1 = 0x444444, color2 = 0x888888 ) { color1 = new Color( color1 ); @@ -83,6 +109,10 @@ class PolarGridHelper extends LineSegments { } + /** + * Frees the GPU-related resources allocated by this instance. Call this + * method whenever this instance is no longer used in your app. + */ dispose() { this.geometry.dispose(); diff --git a/src/helpers/SkeletonHelper.js b/src/helpers/SkeletonHelper.js index cae348c40ad439..570364f70b5dd3 100644 --- a/src/helpers/SkeletonHelper.js +++ b/src/helpers/SkeletonHelper.js @@ -10,9 +10,24 @@ const _vector = /*@__PURE__*/ new Vector3(); const _boneMatrix = /*@__PURE__*/ new Matrix4(); const _matrixWorldInv = /*@__PURE__*/ new Matrix4(); - +/** + * A helper object to assist with visualizing a {@link Skeleton}. + * + * ```js + * const helper = new THREE.SkeletonHelper( skinnedMesh ); + * scene.add( helper ); + * ``` + * + * @augments LineSegments + */ class SkeletonHelper extends LineSegments { + /** + * Constructs a new hemisphere light helper. + * + * @param {Object3D} object - Usually an instance of {@link SkinnedMesh}. However, any 3D object + * can be used if it represents a hierarchy of bones (see {@link Bone}). + */ constructor( object ) { const bones = getBoneList( object ); @@ -47,11 +62,29 @@ class SkeletonHelper extends LineSegments { super( geometry, material ); + /** + * This flag can be used for type testing. + * + * @type {boolean} + * @readonly + * @default true + */ this.isSkeletonHelper = true; this.type = 'SkeletonHelper'; + /** + * The object being visualized. + * + * @type {Object3D} + */ this.root = object; + + /** + * he list of bones that the helper visualizes. + * + * @type {Array} + */ this.bones = bones; this.matrix = object.matrixWorld; @@ -94,6 +127,10 @@ class SkeletonHelper extends LineSegments { } + /** + * Frees the GPU-related resources allocated by this instance. Call this + * method whenever this instance is no longer used in your app. + */ dispose() { this.geometry.dispose(); diff --git a/src/helpers/SpotLightHelper.js b/src/helpers/SpotLightHelper.js index fcf40e355cd48b..7e90dea51f904b 100644 --- a/src/helpers/SpotLightHelper.js +++ b/src/helpers/SpotLightHelper.js @@ -7,16 +7,48 @@ import { BufferGeometry } from '../core/BufferGeometry.js'; const _vector = /*@__PURE__*/ new Vector3(); +/** + * This displays a cone shaped helper object for a {@link SpotLight}. + * + * ```js + * const spotLight = new THREE.SpotLight( 0xffffff ); + * spotLight.position.set( 10, 10, 10 ); + * scene.add( spotLight ); + * + * const spotLightHelper = new THREE.SpotLightHelper( spotLight ); + * scene.add( spotLightHelper ); + * ``` + * + * @augments Object3D + */ class SpotLightHelper extends Object3D { + /** + * Constructs a new spot light helper. + * + * @param {HemisphereLight} light - The light to be visualized. + * @param {number|Color|string} [color] - The helper's color. If not set, the helper will take + * the color of the light. + */ constructor( light, color ) { super(); + /** + * The light being visualized. + * + * @type {SpotLight} + */ this.light = light; this.matrixAutoUpdate = false; + /** + * The color parameter passed in the constructor. + * If not set, the helper will take the color of the light. + * + * @type {number|Color|string} + */ this.color = color; this.type = 'SpotLightHelper'; @@ -54,6 +86,10 @@ class SpotLightHelper extends Object3D { } + /** + * Frees the GPU-related resources allocated by this instance. Call this + * method whenever this instance is no longer used in your app. + */ dispose() { this.cone.geometry.dispose(); @@ -61,6 +97,10 @@ class SpotLightHelper extends Object3D { } + /** + * Updates the helper to match the position and direction of the + * light being visualized. + */ update() { this.light.updateWorldMatrix( true, false ); diff --git a/utils/docs/jsdoc.config.json b/utils/docs/jsdoc.config.json index 65395146ab2a37..afc645708704a4 100644 --- a/utils/docs/jsdoc.config.json +++ b/utils/docs/jsdoc.config.json @@ -14,6 +14,7 @@ "src/core/Object3D.js", "src/core/EventDispatcher.js", "src/extras", + "src/helpers", "src/loaders/nodes", "src/loaders/Loader.js", "src/materials/nodes",