@plastic-software/three 0.174.0 → 0.175.0

package/examples/jsm/helpers/OctreeHelper.js

@@ -5,13 +5,40 @@ import {
 	LineBasicMaterial
 } from 'three';
 
+/**
+ * A helper for visualizing an Octree.
+ *
+ * ```js
+ * const helper = new OctreeHelper( octree );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments LineSegments
+ */
 class OctreeHelper extends LineSegments {
 
+	/**
+	 * Constructs a new Octree helper.
+	 *
+	 * @param {Octree} octree - The octree to visualize.
+	 * @param {number|Color|string} [color=0xffff00] - The helper's color.
+	 */
 	constructor( octree, color = 0xffff00 ) {
 
 		super( new BufferGeometry(), new LineBasicMaterial( { color: color, toneMapped: false } ) );
 
+		/**
+		 * The octree to visualize.
+		 *
+		 * @type {Octree}
+		 */
 		this.octree = octree;
+
+		/**
+		 * The helper's color.
+		 *
+		 * @type {number|Color|string}
+		 */
 		this.color = color;
 
 		this.type = 'OctreeHelper';
@@ -20,6 +47,10 @@ class OctreeHelper extends LineSegments {
 
 	}
 
+	/**
+	 * Updates the helper. This method must be called whenever the Octree's
+	 * structure is changed.
+	 */
 	update() {
 
 		const vertices = [];
@@ -61,6 +92,10 @@ class OctreeHelper 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();

package/examples/jsm/helpers/PositionalAudioHelper.js

@@ -6,8 +6,32 @@ import {
 	MathUtils
 } from 'three';
 
+/**
+ * This helper displays the directional cone of a positional audio.
+ *
+ * `PositionalAudioHelper` must be added as a child of the positional audio.
+ *
+ * ```js
+ * const positionalAudio = new THREE.PositionalAudio( listener );
+ * positionalAudio.setDirectionalCone( 180, 230, 0.1 );
+ * scene.add( positionalAudio );
+ *
+ * const helper = new PositionalAudioHelper( positionalAudio );
+ * positionalAudio.add( helper );
+ * ```
+ *
+ * @augments Line
+ */
 class PositionalAudioHelper extends Line {
 
+	/**
+	 * Constructs a new positional audio helper.
+	 *
+	 * @param {PositionalAudio} audio - The audio to visualize.
+	 * @param {number} [range=1] - The range of the directional cone.
+	 * @param {number} [divisionsInnerAngle=16] - The number of divisions of the inner part of the directional cone.
+	 * @param {number} [divisionsOuterAngle=2] The number of divisions of the outer part of the directional cone.
+	 */
 	constructor( audio, range = 1, divisionsInnerAngle = 16, divisionsOuterAngle = 2 ) {
 
 		const geometry = new BufferGeometry();
@@ -20,16 +44,47 @@ class PositionalAudioHelper extends Line {
 
 		super( geometry, [ materialOuterAngle, materialInnerAngle ] );
 
+		/**
+		 * The audio to visualize.
+		 *
+		 * @type {PositionalAudio}
+		 */
 		this.audio = audio;
+
+		/**
+		 * The range of the directional cone.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.range = range;
+
+		/**
+		 * The number of divisions of the inner part of the directional cone.
+		 *
+		 * @type {number}
+		 * @default 16
+		 */
 		this.divisionsInnerAngle = divisionsInnerAngle;
+
+		/**
+		 * The number of divisions of the outer part of the directional cone.
+		 *
+		 * @type {number}
+		 * @default 2
+		 */
 		this.divisionsOuterAngle = divisionsOuterAngle;
+
 		this.type = 'PositionalAudioHelper';
 
 		this.update();
 
 	}
 
+	/**
+	 * Updates the helper. This method must be called whenever the directional cone
+	 * of the positional audio is changed.
+	 */
 	update() {
 
 		const audio = this.audio;
@@ -95,6 +150,10 @@ class PositionalAudioHelper extends Line {
 
 	}
 
+	/**
+	 * 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();

package/examples/jsm/helpers/RectAreaLightHelper.js

@@ -9,11 +9,27 @@ import {
 } from 'three';
 
 /**
- *  This helper must be added as a child of the light
+ * Creates a visual aid for rect area lights.
+ *
+ * `RectAreaLightHelper` must be added as a child of the light.
+ *
+ * ```js
+ * const light = new THREE.RectAreaLight( 0xffffbb, 1.0, 5, 5 );
+ * const helper = new RectAreaLightHelper( light );
+ * light.add( helper );
+ * ```
+ *
+ * @augments Line
  */
-
 class RectAreaLightHelper extends Line {
 
+	/**
+	 * Constructs a new rect area light helper.
+	 *
+	 * @param {RectAreaLight} light - The light to visualize.
+	 * @param {number|Color|string} [color] - The helper's color.
+	 * If this is not the set, the helper will take the color of the light.
+	 */
 	constructor( light, color ) {
 
 		const positions = [ 1, 1, 0, - 1, 1, 0, - 1, - 1, 0, 1, - 1, 0, 1, 1, 0 ];
@@ -26,8 +42,20 @@ class RectAreaLightHelper extends Line {
 
 		super( geometry, material );
 
+		/**
+		 * The light to visualize.
+		 *
+		 * @type {RectAreaLight}
+		 */
 		this.light = light;
-		this.color = color; // optional hardwired color for the helper
+
+		/**
+		 * The helper's color. If `undefined`, the helper will take the color of the light.
+		 *
+		 * @type {number|Color|string|undefined}
+		 */
+		this.color = color;
+
 		this.type = 'RectAreaLightHelper';
 
 		//
@@ -71,6 +99,10 @@ class RectAreaLightHelper extends Line {
 
 	}
 
+	/**
+	 * 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();

package/examples/jsm/helpers/TextureHelper.js

@@ -9,8 +9,26 @@ import {
 } from 'three';
 import { mergeGeometries } from '../utils/BufferGeometryUtils.js';
 
+/**
+ * A helper that can be used to display any type of texture for
+ * debugging purposes. Depending on the type of texture (2D, 3D, Array),
+ * the helper becomes a plane or box mesh.
+ *
+ * This helper can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, import from `TextureHelperGPU.js`.
+ *
+ * @augments Mesh
+ */
 class TextureHelper extends Mesh {
 
+	/**
+	 * Constructs a new texture helper.
+	 *
+	 * @param {Texture} texture - The texture to visualize.
+	 * @param {number} [width=1] - The helper's width.
+	 * @param {number} [height=1] - The helper's height.
+	 * @param {number} [depth=1] - The helper's depth.
+	 */
 	constructor( texture, width = 1, height = 1, depth = 1 ) {
 
 		const material = new ShaderMaterial( {
@@ -81,11 +99,20 @@ class TextureHelper extends Mesh {
 
 		super( geometry, material );
 
+		/**
+		 * The texture to visualize.
+		 *
+		 * @type {Texture}
+		 */
 		this.texture = texture;
 		this.type = 'TextureHelper';
 
 	}
 
+	/**
+	 * 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();

package/examples/jsm/helpers/TextureHelperGPU.js

@@ -10,8 +10,27 @@ import {
 import { texture as textureNode, cubeTexture, texture3D, float, vec4, attribute } from 'three/tsl';
 import { mergeGeometries } from '../utils/BufferGeometryUtils.js';
 
+/**
+ * A helper that can be used to display any type of texture for
+ * debugging purposes. Depending on the type of texture (2D, 3D, Array),
+ * the helper becomes a plane or box mesh.
+ *
+ * This helper can only be used with {@link WebGPURenderer}.
+ * When using {@link WebGLRenderer}, import from `TextureHelper.js`.
+ *
+ * @private
+ * @augments Mesh
+ */
 class TextureHelper extends Mesh {
 
+	/**
+	 * Constructs a new texture helper.
+	 *
+	 * @param {Texture} texture - The texture to visualize.
+	 * @param {number} [width=1] - The helper's width.
+	 * @param {number} [height=1] - The helper's height.
+	 * @param {number} [depth=1] - The helper's depth.
+	 */
 	constructor( texture, width = 1, height = 1, depth = 1 ) {
 
 		const material = new NodeMaterial();
@@ -51,11 +70,20 @@ class TextureHelper extends Mesh {
 
 		super( geometry, material );
 
+		/**
+		 * The texture to visualize.
+		 *
+		 * @type {Texture}
+		 */
 		this.texture = texture;
 		this.type = 'TextureHelper';
 
 	}
 
+	/**
+	 * 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();

package/examples/jsm/helpers/VertexNormalsHelper.js

@@ -11,8 +11,32 @@ const _v1 = new Vector3();
 const _v2 = new Vector3();
 const _normalMatrix = new Matrix3();
 
+/**
+ * Visualizes an object's vertex normals.
+ *
+ * Requires that normals have been specified in the geometry as a buffer attribute or
+ * have been calculated using {@link BufferGeometry#computeVertexNormals}.
+ * ```js
+ * const geometry = new THREE.BoxGeometry( 10, 10, 10, 2, 2, 2 );
+ * const material = new THREE.MeshStandardMaterial();
+ * const mesh = new THREE.Mesh( geometry, material );
+ * scene.add( mesh );
+ *
+ * const helper = new VertexNormalsHelper( mesh, 1, 0xff0000 );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments LineSegments
+ */
 class VertexNormalsHelper extends LineSegments {
 
+	/**
+	 * Constructs a new vertex normals helper.
+	 *
+	 * @param {Object3D} object - The object for which to visualize vertex normals.
+	 * @param {number} [size=1] - The helper's size.
+	 * @param {number|Color|string} [color=0xff0000] - The helper's color.
+	 */
 	constructor( object, size = 1, color = 0xff0000 ) {
 
 		const geometry = new BufferGeometry();
@@ -24,20 +48,48 @@ class VertexNormalsHelper extends LineSegments {
 
 		super( geometry, new LineBasicMaterial( { color, toneMapped: false } ) );
 
+		/**
+		 * The object for which to visualize vertex normals.
+		 *
+		 * @type {Object3D}
+		 */
 		this.object = object;
+
+		/**
+		 * The helper's size.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.size = size;
-		this.type = 'VertexNormalsHelper';
 
-		//
+		this.type = 'VertexNormalsHelper';
 
+		/**
+		 * Overwritten and set to `false` since the object's world transformation
+		 * is encoded in the helper's geometry data.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.matrixAutoUpdate = false;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isVertexNormalsHelper = true;
 
 		this.update();
 
 	}
 
+	/**
+	 * Updates the vertex normals preview based on the object's world transform.
+	 */
 	update() {
 
 		this.object.updateMatrixWorld( true );
@@ -86,6 +138,10 @@ class VertexNormalsHelper 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();

package/examples/jsm/helpers/VertexTangentsHelper.js

@@ -9,8 +9,27 @@ import {
 const _v1 = new Vector3();
 const _v2 = new Vector3();
 
+/**
+ * Visualizes an object's vertex tangents.
+ *
+ * Requires that tangents have been specified in the geometry as a buffer attribute or
+ * have been calculated using {@link BufferGeometry#computeTangents}.
+ * ```js
+ * const helper = new VertexTangentsHelper( mesh, 1, 0xff0000 );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments LineSegments
+ */
 class VertexTangentsHelper extends LineSegments {
 
+	/**
+	 * Constructs a new vertex tangents helper.
+	 *
+	 * @param {Object3D} object - The object for which to visualize vertex tangents.
+	 * @param {number} [size=1] - The helper's size.
+	 * @param {number|Color|string} [color=0xff0000] - The helper's color.
+	 */
 	constructor( object, size = 1, color = 0x00ffff ) {
 
 		const geometry = new BufferGeometry();
@@ -22,18 +41,39 @@ class VertexTangentsHelper extends LineSegments {
 
 		super( geometry, new LineBasicMaterial( { color, toneMapped: false } ) );
 
+		/**
+		 * The object for which to visualize vertex tangents.
+		 *
+		 * @type {Object3D}
+		 */
 		this.object = object;
+
+		/**
+		 * The helper's size.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.size = size;
-		this.type = 'VertexTangentsHelper';
 
-		//
+		this.type = 'VertexTangentsHelper';
 
+		/**
+		 * Overwritten and set to `false` since the object's world transformation
+		 * is encoded in the helper's geometry data.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.matrixAutoUpdate = false;
 
 		this.update();
 
 	}
 
+	/**
+	 * Updates the vertex normals preview based on the object's world transform.
+	 */
 	update() {
 
 		this.object.updateMatrixWorld( true );
@@ -76,6 +116,10 @@ class VertexTangentsHelper 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();

package/examples/jsm/helpers/ViewHelper.js

@@ -17,15 +17,51 @@ import {
 	Vector4
 } from 'three';
 
+/**
+ * A special type of helper that visualizes the camera's transformation
+ * in a small viewport area as an axes helper. Such a helper is often wanted
+ * in 3D modeling tools or scene editors like the [three.js editor]{@link https://threejs.org/editor}.
+ *
+ * The helper allows to click on the X, Y and Z axes which animates the camera
+ * so it looks along the selected axis.
+ *
+ * @augments Object3D
+ */
 class ViewHelper extends Object3D {
 
+	/**
+	 * Constructs a new view helper.
+	 *
+	 * @param {Camera} camera - The camera whose transformation should be visualized.
+	 * @param {HTMLDOMElement} [domElement] - The DOM element that is used to render the view.
+	 */
 	constructor( camera, domElement ) {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isViewHelper = true;
 
+		/**
+		 * Whether the helper is currently animating or not.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default false
+		 */
 		this.animating = false;
+
+		/**
+		 * The helper's center point.
+		 *
+		 * @type {Vector3}
+		 */
 		this.center = new Vector3();
 
 		const color1 = new Color( '#ff4466' );
@@ -104,6 +140,12 @@ class ViewHelper extends Object3D {
 		const dim = 128;
 		const turnRate = 2 * Math.PI; // turn rate in angles per second
 
+		/**
+		 * Renders the helper in a separate view in the bottom-right corner
+		 * of the viewport.
+		 *
+		 * @param {WebGLRenderer|WebGPURenderer} renderer - The renderer.
+		 */
 		this.render = function ( renderer ) {
 
 			this.quaternion.copy( camera.quaternion ).invert();
@@ -115,11 +157,12 @@ class ViewHelper extends Object3D {
 			//
 
 			const x = domElement.offsetWidth - dim;
+			const y = renderer.isWebGPURenderer ? domElement.offsetHeight - dim : 0;
 
 			renderer.clearDepth();
 
 			renderer.getViewport( viewport );
-			renderer.setViewport( x, 0, dim, dim );
+			renderer.setViewport( x, y, dim, dim );
 
 			renderer.render( this, orthoCamera );
 
@@ -135,6 +178,13 @@ class ViewHelper extends Object3D {
 		const viewport = new Vector4();
 		let radius = 0;
 
+		/**
+		 * This method should be called when a click or pointer event
+		 * has happened in the app.
+		 *
+		 * @param {PointerEvent} event - The event to process.
+		 * @return {boolean} Whether an intersection with the helper has been detected or not.
+		 */
 		this.handleClick = function ( event ) {
 
 			if ( this.animating === true ) return false;
@@ -168,6 +218,13 @@ class ViewHelper extends Object3D {
 
 		};
 
+		/**
+		 * Sets labels for each axis. By default, they are unlabeled.
+		 *
+		 * @param {string|undefined} labelX - The label for the x-axis.
+		 * @param {string|undefined} labelY - The label for the y-axis.
+		 * @param {string|undefined} labelZ - The label for the z-axis.
+		 */
 		this.setLabels = function ( labelX, labelY, labelZ ) {
 
 			options.labelX = labelX;
@@ -178,6 +235,13 @@ class ViewHelper extends Object3D {
 
 		};
 
+		/**
+		 * Sets the label style. Has no effect when the axes are unlabeled.
+		 *
+		 * @param {string} [font='24px Arial'] - The label font.
+		 * @param {string} [color='#000000'] - The label color.
+		 * @param {number} [radius=14] - The label radius.
+		 */
 		this.setLabelStyle = function ( font, color, radius ) {
 
 			options.font = font;
@@ -188,6 +252,12 @@ class ViewHelper extends Object3D {
 
 		};
 
+		/**
+		 * Updates the helper. This method should be called in the app's animation
+		 * loop.
+		 *
+		 * @param {number} delta - The delta time in seconds.
+		 */
 		this.update = function ( delta ) {
 
 			const step = delta * turnRate;
@@ -209,6 +279,10 @@ class ViewHelper extends Object3D {
 
 		};
 
+		/**
+		 * Frees the GPU-related resources allocated by this instance. Call this
+		 * method whenever this instance is no longer used in your app.
+		 */
 		this.dispose = function () {
 
 			geometry.dispose();

package/examples/jsm/interactive/HTMLMesh.js

@@ -8,8 +8,29 @@ import {
 	Color
 } from 'three';
 
+/**
+ * This class can be used to render a DOM element onto a canvas and use it as a texture
+ * for a plane mesh.
+ *
+ * A typical use case for this class is to render the GUI of `lil-gui` as a texture so it
+ * is compatible for VR.
+ *
+ * ```js
+ * const gui = new GUI( { width: 300 } ); // create lil-gui instance
+ *
+ * const mesh = new HTMLMesh( gui.domElement );
+ * scene.add( mesh );
+ * ```
+ *
+ * @augments Mesh
+ */
 class HTMLMesh extends Mesh {
 
+	/**
+	 * Constructs a new HTML mesh.
+	 *
+	 * @param {HTMLElement} dom - The DOM element to display as a plane mesh.
+	 */
 	constructor( dom ) {
 
 		const texture = new HTMLTexture( dom );
@@ -30,6 +51,10 @@ class HTMLMesh extends Mesh {
 		this.addEventListener( 'mouseup', onEvent );
 		this.addEventListener( 'click', onEvent );
 
+		/**
+		 * Frees the GPU-related resources allocated by this instance and removes all event listeners.
+		 * Call this method whenever this instance is no longer used in your app.
+		 */
 		this.dispose = function () {
 
 			geometry.dispose();