super-three 0.173.4 → 0.175.0

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();

package/examples/jsm/interactive/InteractiveGroup.js

@@ -7,11 +7,7 @@ import {
 const _pointer = new Vector2();
 const _event = { type: '', data: _pointer };
 
-// TODO: Dispatch pointerevents too
-
-/**
- * The XR events that are mapped to "standard" pointer events
- */
+// The XR events that are mapped to "standard" pointer events.
 const _events = {
 	'move': 'mousemove',
 	'select': 'click',
@@ -21,17 +17,58 @@ const _events = {
 
 const _raycaster = new Raycaster();
 
+/**
+ * This class can be used to group 3D objects in an interactive group.
+ * The group itself can listen to Pointer, Mouse or XR controller events to
+ * detect selections of descendant 3D objects. If a 3D object is selected,
+ * the respective event is going to dispatched to it.
+ *
+ * ```js
+ * const group = new InteractiveGroup();
+ * group.listenToPointerEvents( renderer, camera );
+ * group.listenToXRControllerEvents( controller1 );
+ * group.listenToXRControllerEvents( controller2 );
+ * scene.add( group );
+ *
+ * // now add objects that should be interactive
+ * group.add( mesh1, mesh2, mesh3 );
+ * ```
+ * @augments Group
+ */
 class InteractiveGroup extends Group {
 
 	constructor() {
 
 		super();
 
+		/**
+		 * The internal raycaster.
+		 *
+		 * @type {Raycaster}
+		 */
 		this.raycaster = new Raycaster();
 
+		/**
+		 * The internal raycaster.
+		 *
+		 * @type {?HTMLDOMElement}
+		 * @default null
+		 */
 		this.element = null;
+
+		/**
+		 * The camera used for raycasting.
+		 *
+		 * @type {?Camera}
+		 * @default null
+		 */
 		this.camera = null;
 
+		/**
+		 * An array of XR controllers.
+		 *
+		 * @type {Array<Group>}
+		 */
 		this.controllers = [];
 
 		this._onPointerEvent = this.onPointerEvent.bind( this );
@@ -92,6 +129,14 @@ class InteractiveGroup extends Group {
 
 	}
 
+	/**
+	 * Calling this method makes sure the interactive group listens to Pointer and Mouse events.
+	 * The target is the `domElement` of the given renderer. The camera is required for the internal
+	 * raycasting so 3D objects can be detected based on the events.
+	 *
+	 * @param {(WebGPURenderer|WebGLRenderer)} renderer - The renderer.
+	 * @param {Camera} camera - The camera.
+	 */
 	listenToPointerEvents( renderer, camera ) {
 
 		this.camera = camera;
@@ -107,6 +152,9 @@ class InteractiveGroup extends Group {
 
 	}
 
+	/**
+	 * Disconnects this interactive group from all Pointer and Mouse Events.
+	 */
 	disconnectionPointerEvents() {
 
 		if ( this.element !== null ) {
@@ -123,6 +171,12 @@ class InteractiveGroup extends Group {
 
 	}
 
+	/**
+	 * Calling this method makes sure the interactive group listens to events of
+	 * the given XR controller.
+	 *
+	 * @param {Group} controller - The XR controller.
+	 */
 	listenToXRControllerEvents( controller ) {
 
 		this.controllers.push( controller );
@@ -133,6 +187,9 @@ class InteractiveGroup extends Group {
 
 	}
 
+	/**
+	 * Disconnects this interactive group from all XR controllers.
+	 */
 	disconnectXrControllerEvents() {
 
 		for ( const controller of this.controllers ) {
@@ -146,6 +203,9 @@ class InteractiveGroup extends Group {
 
 	}
 
+	/**
+	 * Disconnects this interactive group from the DOM and all XR controllers.
+	 */
 	disconnect() {
 
 		this.disconnectionPointerEvents();

package/examples/jsm/interactive/SelectionBox.js

@@ -5,10 +5,6 @@ import {
 	Quaternion,
 } from 'three';
 
-/**
- * This is a class to check whether objects are in a selection area in 3D space
- */
-
 const _frustum = new Frustum();
 const _center = new Vector3();
 
@@ -33,34 +29,103 @@ const _matrix = new Matrix4();
 const _quaternion = new Quaternion();
 const _scale = new Vector3();
 
+/**
+ * This class can be used to select 3D objects in a scene with a selection box.
+ * It is recommended to visualize the selected area with the help of {@link SelectionHelper}.
+ *
+ * ```js
+ * const selectionBox = new SelectionBox( camera, scene );
+ * const selectedObjects = selectionBox.select( startPoint, endPoint );
+ * ```
+ */
 class SelectionBox {
 
+	/**
+	 * Constructs a new selection box.
+	 *
+	 * @param {Camera} camera - The camera the scene is rendered with.
+	 * @param {Scene} scene - The scene.
+	 * @param {number} [deep=Number.MAX_VALUE] - How deep the selection frustum of perspective cameras should extend.
+	 */
 	constructor( camera, scene, deep = Number.MAX_VALUE ) {
 
+		/**
+		 * The camera the scene is rendered with.
+		 *
+		 * @type {Camera}
+		 */
 		this.camera = camera;
+
+		/**
+		 * The camera the scene is rendered with.
+		 *
+		 * @type {Scene}
+		 */
 		this.scene = scene;
+
+		/**
+		 * The start point of the selection.
+		 *
+		 * @type {Vector3}
+		 */
 		this.startPoint = new Vector3();
+
+		/**
+		 * The end point of the selection.
+		 *
+		 * @type {Vector3}
+		 */
 		this.endPoint = new Vector3();
+
+		/**
+		 * The selected 3D objects.
+		 *
+		 * @type {Array<Object3D>}
+		 */
 		this.collection = [];
+
+		/**
+		 * The selected instance IDs of instanced meshes.
+		 *
+		 * @type {Object}
+		 */
 		this.instances = {};
+
+		/**
+		 * How deep the selection frustum of perspective cameras should extend.
+		 *
+		 * @type {number}
+		 * @default Number.MAX_VALUE
+		 */
 		this.deep = deep;
 
 	}
 
+	/**
+	 * This method selects 3D objects in the scene based on the given start
+	 * and end point. If no parameters are provided, the method uses the start
+	 * and end values of the respective members.
+	 *
+	 * @param {Vector3} [startPoint] - The start point.
+	 * @param {Vector3} [endPoint] - The end point.
+	 * @return {Array<Object3D>} The selected 3D objects.
+	 */
 	select( startPoint, endPoint ) {
 
 		this.startPoint = startPoint || this.startPoint;
 		this.endPoint = endPoint || this.endPoint;
 		this.collection = [];
 
-		this.updateFrustum( this.startPoint, this.endPoint );
-		this.searchChildInFrustum( _frustum, this.scene );
+		this._updateFrustum( this.startPoint, this.endPoint );
+		this._searchChildInFrustum( _frustum, this.scene );
 
 		return this.collection;
 
 	}
 
-	updateFrustum( startPoint, endPoint ) {
+	// private
+
+	_updateFrustum( startPoint, endPoint ) {
 
 		startPoint = startPoint || this.startPoint;
 		endPoint = endPoint || this.endPoint;
@@ -170,7 +235,7 @@ class SelectionBox {
 
 	}
 
-	searchChildInFrustum( frustum, object ) {
+	_searchChildInFrustum( frustum, object ) {
 
 		if ( object.isMesh || object.isLine || object.isPoints ) {
 
@@ -214,7 +279,7 @@ class SelectionBox {
 
 			for ( let x = 0; x < object.children.length; x ++ ) {
 
-				this.searchChildInFrustum( frustum, object.children[ x ] );
+				this._searchChildInFrustum( frustum, object.children[ x ] );
 
 			}
 

package/examples/jsm/interactive/SelectionHelper.js

@@ -1,67 +1,111 @@
 import { Vector2 } from 'three';
 
+/**
+ * A helper for {@link SelectionBox}.
+ *
+ * It visualizes the current selection box with a `div` container element.
+ */
 class SelectionHelper {
 
+	/**
+	 * Constructs a new selection helper.
+	 *
+	 * @param {(WebGPURenderer|WebGLRenderer)} renderer - The renderer.
+	 * @param {string} cssClassName - The CSS class name of the `div`.
+	 */
 	constructor( renderer, cssClassName ) {
 
+		/**
+		 * The visualization of the selection box.
+		 *
+		 * @type {HTMLDivElement}
+		 */
 		this.element = document.createElement( 'div' );
 		this.element.classList.add( cssClassName );
 		this.element.style.pointerEvents = 'none';
 
+		/**
+		 * A reference to the renderer.
+		 *
+		 * @type {(WebGPURenderer|WebGLRenderer)}
+		 */
 		this.renderer = renderer;
 
-		this.startPoint = new Vector2();
-		this.pointTopLeft = new Vector2();
-		this.pointBottomRight = new Vector2();
-
+		/**
+		 * Whether the mouse or pointer is pressed down.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.isDown = false;
+
+		/**
+		 * Whether helper is enabled or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.enabled = true;
 
-		this.onPointerDown = function ( event ) {
+		// private
+
+		this._startPoint = new Vector2();
+		this._pointTopLeft = new Vector2();
+		this._pointBottomRight = new Vector2();
+
+		this._onPointerDown = function ( event ) {
 
 			if ( this.enabled === false ) return;
 
 			this.isDown = true;
-			this.onSelectStart( event );
+			this._onSelectStart( event );
 
 		}.bind( this );
 
-		this.onPointerMove = function ( event ) {
+		this._onPointerMove = function ( event ) {
 
 			if ( this.enabled === false ) return;
 
 			if ( this.isDown ) {
 
-				this.onSelectMove( event );
+				this._onSelectMove( event );
 
 			}
 
 		}.bind( this );
 
-		this.onPointerUp = function ( ) {
+		this._onPointerUp = function ( ) {
 
 			if ( this.enabled === false ) return;
 
 			this.isDown = false;
-			this.onSelectOver();
+			this._onSelectOver();
 
 		}.bind( this );
 
-		this.renderer.domElement.addEventListener( 'pointerdown', this.onPointerDown );
-		this.renderer.domElement.addEventListener( 'pointermove', this.onPointerMove );
-		this.renderer.domElement.addEventListener( 'pointerup', this.onPointerUp );
+		this.renderer.domElement.addEventListener( 'pointerdown', this._onPointerDown );
+		this.renderer.domElement.addEventListener( 'pointermove', this._onPointerMove );
+		this.renderer.domElement.addEventListener( 'pointerup', this._onPointerUp );
 
 	}
 
+	/**
+	 * Call this method if you no longer want use to the controls. It frees all internal
+	 * resources and removes all event listeners.
+	 */
 	dispose() {
 
-		this.renderer.domElement.removeEventListener( 'pointerdown', this.onPointerDown );
-		this.renderer.domElement.removeEventListener( 'pointermove', this.onPointerMove );
-		this.renderer.domElement.removeEventListener( 'pointerup', this.onPointerUp );
+		this.renderer.domElement.removeEventListener( 'pointerdown', this._onPointerDown );
+		this.renderer.domElement.removeEventListener( 'pointermove', this._onPointerMove );
+		this.renderer.domElement.removeEventListener( 'pointerup', this._onPointerUp );
+
+		this.element.remove(); // in case disposal happens while dragging
 
 	}
 
-	onSelectStart( event ) {
+	// private
+
+	_onSelectStart( event ) {
 
 		this.element.style.display = 'none';
 
@@ -72,30 +116,30 @@ class SelectionHelper {
 		this.element.style.width = '0px';
 		this.element.style.height = '0px';
 
-		this.startPoint.x = event.clientX;
-		this.startPoint.y = event.clientY;
+		this._startPoint.x = event.clientX;
+		this._startPoint.y = event.clientY;
 
 	}
 
-	onSelectMove( event ) {
+	_onSelectMove( event ) {
 
 		this.element.style.display = 'block';
 
-		this.pointBottomRight.x = Math.max( this.startPoint.x, event.clientX );
-		this.pointBottomRight.y = Math.max( this.startPoint.y, event.clientY );
-		this.pointTopLeft.x = Math.min( this.startPoint.x, event.clientX );
-		this.pointTopLeft.y = Math.min( this.startPoint.y, event.clientY );
+		this._pointBottomRight.x = Math.max( this._startPoint.x, event.clientX );
+		this._pointBottomRight.y = Math.max( this._startPoint.y, event.clientY );
+		this._pointTopLeft.x = Math.min( this._startPoint.x, event.clientX );
+		this._pointTopLeft.y = Math.min( this._startPoint.y, event.clientY );
 
-		this.element.style.left = this.pointTopLeft.x + 'px';
-		this.element.style.top = this.pointTopLeft.y + 'px';
-		this.element.style.width = ( this.pointBottomRight.x - this.pointTopLeft.x ) + 'px';
-		this.element.style.height = ( this.pointBottomRight.y - this.pointTopLeft.y ) + 'px';
+		this.element.style.left = this._pointTopLeft.x + 'px';
+		this.element.style.top = this._pointTopLeft.y + 'px';
+		this.element.style.width = ( this._pointBottomRight.x - this._pointTopLeft.x ) + 'px';
+		this.element.style.height = ( this._pointBottomRight.y - this._pointTopLeft.y ) + 'px';
 
 	}
 
-	onSelectOver() {
+	_onSelectOver() {
 
-		this.element.parentElement.removeChild( this.element );
+		this.element.remove();
 
 	}
 

package/examples/jsm/libs/motion-controllers.module.js

@@ -338,7 +338,7 @@ class MotionController {
   /**
    * @param {Object} xrInputSource - The XRInputSource to build the MotionController around
    * @param {Object} profile - The best matched profile description for the supplied xrInputSource
-   * @param {Object} assetUrl
+   * @param {string} assetUrl
    */
   constructor(xrInputSource, profile, assetUrl) {
     if (!xrInputSource) {

package/examples/jsm/lighting/TiledLighting.js

@@ -1,14 +1,37 @@
 import { Lighting } from 'three/webgpu';
 import { tiledLights } from '../tsl/lighting/TiledLightsNode.js';
 
+/**
+ * A custom lighting implementation based on Tiled-Lighting that overwrites the default
+ * implementation in {@link WebGPURenderer}.
+ *
+ * ```js
+ * const lighting = new TiledLighting();
+ * renderer.lighting = lighting; // set lighting system
+ * ```
+ *
+ * @augments Lighting
+ */
 export class TiledLighting extends Lighting {
 
+	/**
+	 * Constructs a new lighting system.
+	 */
 	constructor() {
 
 		super();
 
 	}
 
+	/**
+	 * Creates a new tiled lights node for the given array of lights.
+	 *
+	 * This method is called internally by the renderer and must be overwritten by
+	 * all custom lighting implementations.
+	 *
+	 * @param {Array<Light>} lights - The render object.
+	 * @return {TiledLightsNode} The tiled lights node.
+	 */
 	createNode( lights = [] ) {
 
 		return tiledLights().setLights( lights );

package/examples/jsm/lights/LightProbeGenerator.js

@@ -11,11 +11,24 @@ import {
 	WebGLCoordinateSystem
 } from 'three';
 
+/**
+ * Utility class for creating instances of {@link LightProbe}.
+ *
+ * @hideconstructor
+ */
 class LightProbeGenerator {
 
-	// https://www.ppsloan.org/publications/StupidSH36.pdf
+	/**
+	 * Creates a light probe from the given (radiance) environment map.
+	 * The method expects that the environment map is represented as a cube texture.
+	 *
+	 * @param {CubeTexture} cubeTexture - The environment map.
+	 * @return {LightProbe} The created light probe.
+	 */
 	static fromCubeTexture( cubeTexture ) {
 
+		// https://www.ppsloan.org/publications/StupidSH36.pdf
+
 		let totalWeight = 0;
 
 		const coord = new Vector3();
@@ -127,6 +140,18 @@ class LightProbeGenerator {
 
 	}
 
+	/**
+	 * Creates a light probe from the given (radiance) environment map.
+	 * The method expects that the environment map is represented as a cube render target.
+	 *
+	 * The cube render target must be in RGBA so `cubeRenderTarget.texture.format` must be
+	 * set to {@link RGBAFormat}.
+	 *
+	 * @async
+	 * @param {WebGPURenderer|WebGLRenderer} renderer - The renderer.
+	 * @param {CubeRenderTarget|WebGLCubeRenderTarget} cubeRenderTarget - The environment map.
+	 * @return {Promise<LightProbe>} A Promise that resolves with the created light probe.
+	 */
 	static async fromCubeRenderTarget( renderer, cubeRenderTarget ) {
 
 		const flip = renderer.coordinateSystem === WebGLCoordinateSystem ? - 1 : 1;