super-three 0.173.4 → 0.175.0

package/src/renderers/webgpu/utils/WebGPUUtils.js

@@ -28,7 +28,7 @@ class WebGPUUtils {
 	 * Returns the depth/stencil GPU format for the given render context.
 	 *
 	 * @param {RenderContext} renderContext - The render context.
-	 * @return {String} The depth/stencil GPU texture format.
+	 * @return {string} The depth/stencil GPU texture format.
 	 */
 	getCurrentDepthStencilFormat( renderContext ) {
 
@@ -56,7 +56,7 @@ class WebGPUUtils {
 	 * Returns the GPU format for the given texture.
 	 *
 	 * @param {Texture} texture - The texture.
-	 * @return {String} The GPU texture format.
+	 * @return {string} The GPU texture format.
 	 */
 	getTextureFormatGPU( texture ) {
 
@@ -104,7 +104,7 @@ class WebGPUUtils {
 	 * Returns the default color attachment's GPU format of the current render context.
 	 *
 	 * @param {RenderContext} renderContext - The render context.
-	 * @return {String} The GPU texture format of the default color attachment.
+	 * @return {string} The GPU texture format of the default color attachment.
 	 */
 	getCurrentColorFormat( renderContext ) {
 
@@ -128,7 +128,7 @@ class WebGPUUtils {
 	 * Returns the output color space of the current render context.
 	 *
 	 * @param {RenderContext} renderContext - The render context.
-	 * @return {String} The output color space.
+	 * @return {string} The output color space.
 	 */
 	getCurrentColorSpace( renderContext ) {
 
@@ -147,7 +147,7 @@ class WebGPUUtils {
 	 *
 	 * @param {Object3D} object - The 3D object.
 	 * @param {Material} material - The material.
-	 * @return {String} The GPU primitive topology.
+	 * @return {string} The GPU primitive topology.
 	 */
 	getPrimitiveTopology( object, material ) {
 
@@ -163,8 +163,8 @@ class WebGPUUtils {
 	 *
 	 * That is required since WebGPU does not support arbitrary sample counts.
 	 *
-	 * @param {Number} sampleCount - The input sample count.
-	 * @return {Number} The (potentially updated) output sample count.
+	 * @param {number} sampleCount - The input sample count.
+	 * @return {number} The (potentially updated) output sample count.
 	 */
 	getSampleCount( sampleCount ) {
 
@@ -191,7 +191,7 @@ class WebGPUUtils {
 	 * Returns the sample count of the given render context.
 	 *
 	 * @param {RenderContext} renderContext - The render context.
-	 * @return {Number} The sample count.
+	 * @return {number} The sample count.
 	 */
 	getSampleCountRenderContext( renderContext ) {
 
@@ -211,7 +211,7 @@ class WebGPUUtils {
 	 * There is a separate method for this so it's possible to
 	 * honor edge cases for specific devices.
 	 *
-	 * @return {String} The GPU texture format of the canvas.
+	 * @return {string} The GPU texture format of the canvas.
 	 */
 	getPreferredCanvasFormat() {
 

package/src/renderers/webxr/WebXRController.js

@@ -3,16 +3,56 @@ import { Group } from '../../objects/Group.js';
 
 const _moveEvent = { type: 'move' };
 
+/**
+ * Class for representing a XR controller with its
+ * different coordinate systems.
+ *
+ * @private
+ */
 class WebXRController {
 
+	/**
+	 * Constructs a new XR controller.
+	 */
 	constructor() {
 
+		/**
+		 * A group representing the target ray space
+		 * of the XR controller.
+		 *
+		 * @private
+		 * @type {?Group}
+		 * @default null
+		 */
 		this._targetRay = null;
+
+		/**
+		 * A group representing the grip space
+		 * of the XR controller.
+		 *
+		 * @private
+		 * @type {?Group}
+		 * @default null
+		 */
 		this._grip = null;
+
+		/**
+		 * A group representing the hand space
+		 * of the XR controller.
+		 *
+		 * @private
+		 * @type {?Group}
+		 * @default null
+		 */
 		this._hand = null;
 
 	}
 
+	/**
+	 * Returns a group representing the hand space of the XR controller.
+	 *
+	 * @return {Group} A group representing the hand space of the XR controller.
+	 */
 	getHandSpace() {
 
 		if ( this._hand === null ) {
@@ -30,6 +70,11 @@ class WebXRController {
 
 	}
 
+	/**
+	 * Returns a group representing the target ray space of the XR controller.
+	 *
+	 * @return {Group} A group representing the target ray space of the XR controller.
+	 */
 	getTargetRaySpace() {
 
 		if ( this._targetRay === null ) {
@@ -48,6 +93,11 @@ class WebXRController {
 
 	}
 
+	/**
+	 * Returns a group representing the grip space of the XR controller.
+	 *
+	 * @return {Group} A group representing the grip space of the XR controller.
+	 */
 	getGripSpace() {
 
 		if ( this._grip === null ) {
@@ -66,6 +116,13 @@ class WebXRController {
 
 	}
 
+	/**
+	 * Dispatches the given event to the groups representing
+	 * the different coordinate spaces of the XR controller.
+	 *
+	 * @param {Object} event - The event to dispatch.
+	 * @return {WebXRController} A reference to this instance.
+	 */
 	dispatchEvent( event ) {
 
 		if ( this._targetRay !== null ) {
@@ -90,6 +147,12 @@ class WebXRController {
 
 	}
 
+	/**
+	 * Connects the controller with the given XR input source.
+	 *
+	 * @param {XRInputSource} inputSource - The input source.
+	 * @return {WebXRController} A reference to this instance.
+	 */
 	connect( inputSource ) {
 
 		if ( inputSource && inputSource.hand ) {
@@ -115,6 +178,12 @@ class WebXRController {
 
 	}
 
+	/**
+	 * Disconnects the controller from the given XR input source.
+	 *
+	 * @param {XRInputSource} inputSource - The input source.
+	 * @return {WebXRController} A reference to this instance.
+	 */
 	disconnect( inputSource ) {
 
 		this.dispatchEvent( { type: 'disconnected', data: inputSource } );
@@ -141,6 +210,16 @@ class WebXRController {
 
 	}
 
+	/**
+	 * Updates the controller with the given input source, XR frame and reference space.
+	 * This updates the transformations of the groups that represent the different
+	 * coordinate systems of the controller.
+	 *
+	 * @param {XRInputSource} inputSource - The input source.
+	 * @param {XRFrame} frame - The XR frame.
+	 * @param {XRReferenceSpace} referenceSpace - The reference space.
+	 * @return {WebXRController} A reference to this instance.
+	 */
 	update( inputSource, frame, referenceSpace ) {
 
 		let inputPose = null;
@@ -318,8 +397,14 @@ class WebXRController {
 
 	}
 
-	// private method
-
+	/**
+	 * Returns a group representing the hand joint for the given input joint.
+	 *
+	 * @private
+	 * @param {Group} hand - The group representing the hand space.
+	 * @param {XRHandJoint} inputjoint - The XR frame.
+	 * @return {Group} A group representing the hand joint for the given input joint.
+	 */
 	_getHandJoint( hand, inputjoint ) {
 
 		if ( hand.joints[ inputjoint.jointName ] === undefined ) {

package/src/renderers/webxr/WebXRDepthSensing.js

@@ -31,18 +31,53 @@ void main() {
 
 }`;
 
+/**
+ * A XR module that manages the access to the Depth Sensing API.
+ */
 class WebXRDepthSensing {
 
+	/**
+	 * Constructs a new depth sensing module.
+	 */
 	constructor() {
 
+		/**
+		 * A texture representing the depth of the user's environment.
+		 *
+		 * @type {?Texture}
+		 */
 		this.texture = null;
+
+		/**
+		 * A plane mesh for visualizing the depth texture.
+		 *
+		 * @type {?Mesh}
+		 */
 		this.mesh = null;
 
+		/**
+		 * The depth near value.
+		 *
+		 * @type {number}
+		 */
 		this.depthNear = 0;
+
+		/**
+		 * The depth near far.
+		 *
+		 * @type {number}
+		 */
 		this.depthFar = 0;
 
 	}
 
+	/**
+	 * Inits the depth sensing module
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 * @param {XRWebGLDepthInformation} depthData - The XR depth data.
+	 * @param {XRRenderState} renderState - The XR render state.
+	 */
 	init( renderer, depthData, renderState ) {
 
 		if ( this.texture === null ) {
@@ -65,6 +100,12 @@ class WebXRDepthSensing {
 
 	}
 
+	/**
+	 * Returns a plane mesh that visualizes the depth texture.
+	 *
+	 * @param {ArrayCamera} cameraXR - The XR camera.
+	 * @return {?Mesh} The plane mesh.
+	 */
 	getMesh( cameraXR ) {
 
 		if ( this.texture !== null ) {
@@ -92,6 +133,9 @@ class WebXRDepthSensing {
 
 	}
 
+	/**
+	 * Resets the module
+	 */
 	reset() {
 
 		this.texture = null;
@@ -99,6 +143,11 @@ class WebXRDepthSensing {
 
 	}
 
+	/**
+	 * Returns a texture representing the depth of the user's environment.
+	 *
+	 * @return {?Texture} The depth texture.
+	 */
 	getDepthTexture() {
 
 		return this.texture;

package/src/renderers/webxr/WebXRManager.js

@@ -13,8 +13,23 @@ import { DepthTexture } from '../../textures/DepthTexture.js';
 import { DepthFormat, DepthStencilFormat, RGBAFormat, UnsignedByteType, UnsignedIntType, UnsignedInt248Type } from '../../constants.js';
 import { WebXRDepthSensing } from './WebXRDepthSensing.js';
 
+/**
+ * This class represents an abstraction of the WebXR Device API and is
+ * internally used by {@link WebGLRenderer}. `WebXRManager` also provides a public
+ * interface that allows users to enable/disable XR and perform XR related
+ * tasks like for instance retrieving controllers.
+ *
+ * @augments EventDispatcher
+ * @hideconstructor
+ */
 class WebXRManager extends EventDispatcher {
 
+	/**
+	 * Constructs a new WebGL renderer.
+	 *
+	 * @param {WebGLRenderer} renderer - The renderer.
+	 * @param {WebGL2RenderingContext} gl - The rendering context.
+	 */
 	constructor( renderer, gl, extensions, useMultiview ) {
 
 		super();
@@ -67,11 +82,32 @@ class WebXRManager extends EventDispatcher {
 		let _currentDepthNear = null;
 		let _currentDepthFar = null;
 
-		//
+		/**
+		 * Whether the manager's XR camera should be automatically updated or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.cameraAutoUpdate = true;
-		this.layersEnabled = false;
+
+		/**
+		 * This flag notifies the renderer to be ready for XR rendering. Set it to `true`
+		 * if you are going to use XR in your app.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.enabled = false;
 
+		this.layersEnabled = false;
+
+		/**
+		 * Whether XR presentation is active or not.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default false
+		 */
 		this.isPresenting = false;
 		this.isMultiview = false;
 
@@ -81,6 +117,14 @@ class WebXRManager extends EventDispatcher {
 
 		};
 
+		/**
+		 * Returns a group representing the `target ray` space of the XR controller.
+		 * Use this space for visualizing 3D objects that support the user in pointing
+		 * tasks like UI interaction.
+		 *
+		 * @param {number} index - The index of the controller.
+		 * @return {Group} A group representing the `target ray` space.
+		 */
 		this.getController = function ( index ) {
 
 			let controller = controllers[ index ];
@@ -96,6 +140,21 @@ class WebXRManager extends EventDispatcher {
 
 		};
 
+		/**
+		 * Returns a group representing the `grip` space of the XR controller.
+		 * Use this space for visualizing 3D objects that support the user in pointing
+		 * tasks like UI interaction.
+		 *
+		 * Note: If you want to show something in the user's hand AND offer a
+		 * pointing ray at the same time, you'll want to attached the handheld object
+		 * to the group returned by `getControllerGrip()` and the ray to the
+		 * group returned by `getController()`. The idea is to have two
+		 * different groups in two different coordinate spaces for the same WebXR
+		 * controller.
+		 *
+		 * @param {number} index - The index of the controller.
+		 * @return {Group} A group representing the `grip` space.
+		 */
 		this.getControllerGrip = function ( index ) {
 
 			let controller = controllers[ index ];
@@ -111,6 +170,14 @@ class WebXRManager extends EventDispatcher {
 
 		};
 
+		/**
+		 * Returns a group representing the `hand` space of the XR controller.
+		 * Use this space for visualizing 3D objects that support the user in pointing
+		 * tasks like UI interaction.
+		 *
+		 * @param {number} index - The index of the controller.
+		 * @return {Group} A group representing the `hand` space.
+		 */
 		this.getHand = function ( index ) {
 
 			let controller = controllers[ index ];
@@ -179,6 +246,8 @@ class WebXRManager extends EventDispatcher {
 
 			// restore framebuffer/rendering state
 
+			scope.isPresenting = false;
+
 			renderer.setRenderTarget( initialRenderTarget );
 
 			glBaseLayer = null;
@@ -191,8 +260,6 @@ class WebXRManager extends EventDispatcher {
 
 			animation.stop();
 
-			scope.isPresenting = false;
-
 			renderer.setPixelRatio( currentPixelRatio );
 			renderer.setSize( currentSize.width, currentSize.height, false );
 
@@ -200,6 +267,13 @@ class WebXRManager extends EventDispatcher {
 
 		}
 
+		/**
+		 * Sets the framebuffer scale factor.
+		 *
+		 * This method can not be used during a XR session.
+		 *
+		 * @param {number} value - The framebuffer scale factor.
+		 */
 		this.setFramebufferScaleFactor = function ( value ) {
 
 			framebufferScaleFactor = value;
@@ -212,6 +286,15 @@ class WebXRManager extends EventDispatcher {
 
 		};
 
+		/**
+		 * Sets the reference space type. Can be used to configure a spatial relationship with the user's physical
+		 * environment. Depending on how the user moves in 3D space, setting an appropriate reference space can
+		 * improve tracking. Default is `local-floor`.
+		 *
+		 * This method can not be used during a XR session.
+		 *
+		 * @param {string} value - The reference space type.
+		 */
 		this.setReferenceSpaceType = function ( value ) {
 
 			referenceSpaceType = value;
@@ -224,48 +307,87 @@ class WebXRManager extends EventDispatcher {
 
 		};
 
+		/**
+		 * Returns the XR reference space.
+		 *
+		 * @return {XRReferenceSpace} The XR reference space.
+		 */
 		this.getReferenceSpace = function () {
 
 			return customReferenceSpace || referenceSpace;
 
 		};
 
+		/**
+		 * Sets a custom XR reference space.
+		 *
+		 * @param {XRReferenceSpace} space - The XR reference space.
+		 */
 		this.setReferenceSpace = function ( space ) {
 
 			customReferenceSpace = space;
 
 		};
 
+		/**
+		 * Returns the current base layer.
+		 *
+		 * @return {?(XRWebGLLayer|XRProjectionLayer)} The XR base layer.
+		 */
 		this.getBaseLayer = function () {
 
 			return glProjLayer !== null ? glProjLayer : glBaseLayer;
 
 		};
 
+		/**
+		 * Returns the current XR binding.
+		 *
+		 * @return {?XRWebGLBinding} The XR binding.
+		 */
 		this.getBinding = function () {
 
 			return glBinding;
 
 		};
 
-		this.getRenderTarget = function () {
+		/**
+		 * Returns the current XR frame.
+		 *
+		 * @return {?XRFrame} The XR frame. Returns `null` when used outside a XR session.
+		 */
+		this.getFrame = function () {
 
-			return newRenderTarget;
+			return xrFrame;
 
 		};
 
-		this.getFrame = function () {
+		this.getRenderTarget = function () {
 
-			return xrFrame;
+			return newRenderTarget;
 
 		};
 
+		/**
+		 * Returns the current XR session.
+		 *
+		 * @return {?XRSession} The XR session. Returns `null` when used outside a XR session.
+		 */
 		this.getSession = function () {
 
 			return session;
 
 		};
 
+		/**
+		 * After a XR session has been requested usually with one of the `*Button` modules, it
+		 * is injected into the renderer with this method. This method triggers the start of
+		 * the actual XR rendering.
+		 *
+		 * @async
+		 * @param {XRSession} value - The XR session to set.
+		 * @return {Promise} A Promise that resolves when the session has been set.
+		 */
 		this.setSession = async function ( value ) {
 
 			session = value;
@@ -320,7 +442,10 @@ class WebXRManager extends EventDispatcher {
 							format: RGBAFormat,
 							type: UnsignedByteType,
 							colorSpace: renderer.outputColorSpace,
-							stencilBuffer: attributes.stencil
+							stencilBuffer: attributes.stencil,
+							resolveDepthBuffer: ( glBaseLayer.ignoreDepthValues === false ),
+							resolveStencilBuffer: ( glBaseLayer.ignoreDepthValues === false )
+
 						}
 					);
 
@@ -368,7 +493,8 @@ class WebXRManager extends EventDispatcher {
 						stencilBuffer: attributes.stencil,
 						colorSpace: renderer.outputColorSpace,
 						samples: attributes.antialias ? 4 : 0,
-						resolveDepthBuffer: ( glProjLayer.ignoreDepthValues === false )
+						resolveDepthBuffer: ( glProjLayer.ignoreDepthValues === false ),
+						resolveStencilBuffer: ( glProjLayer.ignoreDepthValues === false )
 					};
 
 					if ( scope.isMultiview ) {
@@ -408,6 +534,11 @@ class WebXRManager extends EventDispatcher {
 
 		};
 
+		/**
+		 * Returns the environment blend mode from the current XR session.
+		 *
+		 * @return {'opaque'|'additive'|'alpha-blend'|undefined} The environment blend mode. Returns `undefined` when used outside of a XR session.
+		 */
 		this.getEnvironmentBlendMode = function () {
 
 			if ( session !== null ) {
@@ -439,6 +570,11 @@ class WebXRManager extends EventDispatcher {
 			session.updateRenderState( { layers: layersCopy } );
 		}
 
+		/**
+		 * Returns the current depth texture computed via depth sensing.
+		 *
+		 * @return {?Texture} The depth texture.
+		 */
 		this.getDepthTexture = function () {
 
 			return depthSensing.getDepthTexture();
@@ -611,6 +747,15 @@ class WebXRManager extends EventDispatcher {
 
 		};
 
+		/**
+		 * Updates the state of the XR camera. Use this method on app level if you
+		 * set cameraAutoUpdate` to `false`. The method requires the non-XR
+		 * camera of the scene as a parameter. The passed in camera's transformation
+		 * is automatically adjusted to the position of the XR camera when calling
+		 * this method.
+		 *
+		 * @param {Camera} camera - The camera.
+		 */
 		this.updateCamera = function ( camera ) {
 
 			if ( session === null ) return;
@@ -707,12 +852,27 @@ class WebXRManager extends EventDispatcher {
 
 		}
 
+		/**
+		 * Returns an instance of {@link ArrayCamera} which represents the XR camera
+		 * of the active XR session. For each view it holds a separate camera object.
+		 *
+		 * The camera's `fov` is currently not used and does not reflect the fov of
+		 * the XR camera. If you need the fov on app level, you have to compute in
+		 * manually from the XR camera's projection matrices.
+		 *
+		 * @return {ArrayCamera} The XR camera.
+		 */
 		this.getCamera = function () {
 
 			return cameraXR;
 
 		};
 
+		/**
+		 * Returns the amount of foveation used by the XR compositor for the projection layer.
+		 *
+		 * @return {number} The amount of foveation.
+		 */
 		this.getFoveation = function () {
 
 			if ( glProjLayer === null && glBaseLayer === null ) {
@@ -725,6 +885,12 @@ class WebXRManager extends EventDispatcher {
 
 		};
 
+		/**
+		 * Sets the foveation value.
+		 *
+		 * @param {number} value - A number in the range `[0,1]` where `0` means no foveation (full resolution)
+		 * and `1` means maximum foveation (the edges render at lower resolution).
+		 */
 		this.setFoveation = function ( value ) {
 
 			// 0 = no foveation = full resolution
@@ -746,12 +912,22 @@ class WebXRManager extends EventDispatcher {
 
 		};
 
+		/**
+		 * Returns `true` if depth sensing is supported.
+		 *
+		 * @return {boolean} Whether depth sensing is supported or not.
+		 */
 		this.hasDepthSensing = function () {
 
 			return depthSensing.texture !== null;
 
 		};
 
+		/**
+		 * Returns the depth sensing mesh.
+		 *
+		 * @return {Mesh} The depth sensing mesh.
+		 */
 		this.getDepthSensingMesh = function () {
 
 			return depthSensing.getMesh( cameraXR );
@@ -810,7 +986,7 @@ class WebXRManager extends EventDispatcher {
 							renderer.setRenderTargetTextures(
 								newRenderTarget,
 								glSubImage.colorTexture,
-								glProjLayer.ignoreDepthValues ? undefined : glSubImage.depthStencilTexture );
+								glSubImage.depthStencilTexture );
 
 							renderer.setRenderTarget( newRenderTarget );