super-three 0.171.0 → 0.173.0

package/src/renderers/common/ClippingContext.js

@@ -4,41 +4,110 @@ import { Vector4 } from '../../math/Vector4.js';
 
 const _plane = /*@__PURE__*/ new Plane();
 
+/**
+ * Represents the state that is used to perform clipping via clipping planes.
+ * There is a default clipping context for each render context. When the
+ * scene holds instances of `ClippingGroup`, there will be a context for each
+ * group.
+ *
+ * @private
+ */
 class ClippingContext {
 
+	/**
+	 * Constructs a new clipping context.
+	 *
+	 * @param {ClippingContext?} [parentContext=null] - A reference to the parent clipping context.
+	 */
 	constructor( parentContext = null ) {
 
+		/**
+		 * The clipping context's version.
+		 *
+		 * @type {Number}
+		 * @readonly
+		 */
 		this.version = 0;
 
+		/**
+		 * Whether the intersection of the clipping planes is used to clip objects, rather than their union.
+		 *
+		 * @type {Boolean?}
+		 * @default null
+		 */
 		this.clipIntersection = null;
-		this.cacheKey = '';
-
-
-		if ( parentContext === null ) {
 
-			this.intersectionPlanes = [];
-			this.unionPlanes = [];
-
-			this.viewNormalMatrix = new Matrix3();
-			this.clippingGroupContexts = new WeakMap();
+		/**
+		 * The clipping context's cache key.
+		 *
+		 * @type {String}
+		 */
+		this.cacheKey = '';
 
-			this.shadowPass = false;
+		/**
+		 * Whether the shadow pass is active or not.
+		 *
+		 * @type {Boolean}
+		 * @default false
+		 */
+		this.shadowPass = false;
+
+		/**
+		 * The view normal matrix.
+		 *
+		 * @type {Matrix3}
+		 */
+		this.viewNormalMatrix = new Matrix3();
+
+		/**
+		 * Internal cache for maintaining clipping contexts.
+		 *
+		 * @type {WeakMap<ClippingGroup,ClippingContext>}
+		 */
+		this.clippingGroupContexts = new WeakMap();
+
+		/**
+		 * The intersection planes.
+		 *
+		 * @type {Array<Vector4>}
+		 */
+		this.intersectionPlanes = [];
+
+		/**
+		 * The intersection planes.
+		 *
+		 * @type {Array<Vector4>}
+		 */
+		this.unionPlanes = [];
+
+		/**
+		 * The version of the clipping context's parent context.
+		 *
+		 * @type {Number?}
+		 * @readonly
+		 */
+		this.parentVersion = null;
 
-		} else {
+		if ( parentContext !== null ) {
 
 			this.viewNormalMatrix = parentContext.viewNormalMatrix;
 			this.clippingGroupContexts = parentContext.clippingGroupContexts;
 
 			this.shadowPass = parentContext.shadowPass;
-
 			this.viewMatrix = parentContext.viewMatrix;
 
 		}
 
-		this.parentVersion = null;
-
 	}
 
+	/**
+	 * Projects the given source clipping planes and writes the result into the
+	 * destination array.
+	 *
+	 * @param {Array<Plane>} source - The source clipping planes.
+	 * @param {Array<Vector4>} destination - The destination.
+	 * @param {Number} offset - The offset.
+	 */
 	projectPlanes( source, destination, offset ) {
 
 		const l = source.length;
@@ -59,15 +128,27 @@ class ClippingContext {
 
 	}
 
+	/**
+	 * Updates the root clipping context of a scene.
+	 *
+	 * @param {Scene} scene - The scene.
+	 * @param {Camera} camera - The camera that is used to render the scene.
+	 */
 	updateGlobal( scene, camera ) {
 
-		this.shadowPass = ( scene.overrideMaterial !== null && scene.overrideMaterial.isShadowNodeMaterial );
+		this.shadowPass = ( scene.overrideMaterial !== null && scene.overrideMaterial.isShadowPassMaterial );
 		this.viewMatrix = camera.matrixWorldInverse;
 
 		this.viewNormalMatrix.getNormalMatrix( this.viewMatrix );
 
 	}
 
+	/**
+	 * Updates the clipping context.
+	 *
+	 * @param {ClippingContext} parentContext - The parent context.
+	 * @param {ClippingGroup} clippingGroup - The clipping group this context belongs to.
+	 */
 	update( parentContext, clippingGroup ) {
 
 		let update = false;
@@ -139,6 +220,12 @@ class ClippingContext {
 
 	}
 
+	/**
+	 * Returns a clipping context for the given clipping group.
+	 *
+	 * @param {ClippingGroup} clippingGroup - The clipping group.
+	 * @return {ClippingContext} The clipping context.
+	 */
 	getGroupContext( clippingGroup ) {
 
 		if ( this.shadowPass && ! clippingGroup.clipShadows ) return this;
@@ -158,6 +245,12 @@ class ClippingContext {
 
 	}
 
+	/**
+	 * The count of union clipping planes.
+	 *
+	 * @type {Number}
+	 * @readonly
+	 */
 	get unionClippingCount() {
 
 		return this.unionPlanes.length;

package/src/renderers/common/Color4.js

@@ -1,7 +1,25 @@
 import { Color } from '../../math/Color.js';
 
+/**
+ * A four-component version of {@link Color} which is internally
+ * used by the renderer to represents clear color with alpha as
+ * one object.
+ *
+ * @private
+ * @augments Color
+ */
 class Color4 extends Color {
 
+	/**
+	 * Constructs a new four-component color.
+	 * You can also pass a single THREE.Color, hex or
+	 * string argument to this constructor.
+	 *
+	 * @param {Number|String} [r=1] - The red value.
+	 * @param {Number} [g=1] - The green value.
+	 * @param {Number} [b=1] - The blue value.
+	 * @param {Number} [a=1] - The alpha value.
+	 */
 	constructor( r, g, b, a = 1 ) {
 
 		super( r, g, b );
@@ -10,6 +28,17 @@ class Color4 extends Color {
 
 	}
 
+	/**
+	 * Overwrites the default to honor alpha.
+	 * You can also pass a single THREE.Color, hex or
+	 * string argument to this method.
+	 *
+	 * @param {Number|String} r - The red value.
+	 * @param {Number} g - The green value.
+	 * @param {Number} b - The blue value.
+	 * @param {Number} [a=1] - The alpha value.
+	 * @return {Color4} A reference to this object.
+	 */
 	set( r, g, b, a = 1 ) {
 
 		this.a = a;
@@ -18,6 +47,12 @@ class Color4 extends Color {
 
 	}
 
+	/**
+	 * Overwrites the default to honor alpha.
+	 *
+	 * @param {Color4} color - The color to copy.
+	 * @return {Color4} A reference to this object.
+	 */
 	copy( color ) {
 
 		if ( color.a !== undefined ) this.a = color.a;
@@ -26,6 +61,11 @@ class Color4 extends Color {
 
 	}
 
+	/**
+	 * Overwrites the default to honor alpha.
+	 *
+	 * @return {Color4} The cloned color.
+	 */
 	clone() {
 
 		return new this.constructor( this.r, this.g, this.b, this.a );

package/src/renderers/common/ComputePipeline.js

@@ -1,13 +1,37 @@
 import Pipeline from './Pipeline.js';
 
+/**
+ * Class for representing compute pipelines.
+ *
+ * @private
+ * @augments Pipeline
+ */
 class ComputePipeline extends Pipeline {
 
+	/**
+	 * Constructs a new render pipeline.
+	 *
+	 * @param {String} cacheKey - The pipeline's cache key.
+	 * @param {ProgrammableStage} computeProgram - The pipeline's compute shader.
+	 */
 	constructor( cacheKey, computeProgram ) {
 
 		super( cacheKey );
 
+		/**
+		 * The pipeline's compute shader.
+		 *
+		 * @type {ProgrammableStage}
+		 */
 		this.computeProgram = computeProgram;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isComputePipeline = true;
 
 	}

package/src/renderers/common/CubeRenderTarget.js

@@ -12,6 +12,12 @@ import { BackSide, NoBlending, LinearFilter, LinearMipmapLinearFilter } from '..
 
 // @TODO: Consider rename WebGLCubeRenderTarget to just CubeRenderTarget
 
+/**
+ * This class represents a cube render target. It is a special version
+ * of `WebGLCubeRenderTarget` which is compatible with `WebGPURenderer`.
+ *
+ * @augments WebGLCubeRenderTarget
+ */
 class CubeRenderTarget extends WebGLCubeRenderTarget {
 
 	constructor( size = 1, options = {} ) {
@@ -22,6 +28,13 @@ class CubeRenderTarget extends WebGLCubeRenderTarget {
 
 	}
 
+	/**
+	 * Converts the given equirectangular texture to a cube map.
+	 *
+	 * @param {Renderer} renderer - The renderer.
+	 * @param {Texture} texture - The equirectangular texture.
+	 * @return {CubeRenderTarget} A reference to this cube render target.
+	 */
 	fromEquirectangularTexture( renderer, texture ) {
 
 		const currentMinFilter = texture.minFilter;

package/src/renderers/common/DataMap.js

@@ -1,11 +1,32 @@
+/**
+ * Data structure for the renderer. It is intended to manage
+ * data of objects in dictionaries.
+ *
+ * @private
+ */
 class DataMap {
 
+	/**
+	 * Constructs a new data map.
+	 */
 	constructor() {
 
+		/**
+		 * `DataMap` internally uses a weak map
+		 * to manage its data.
+		 *
+		 * @type {WeakMap}
+		 */
 		this.data = new WeakMap();
 
 	}
 
+	/**
+	 * Returns the dictionary for the given object.
+	 *
+	 * @param {Object} object - The object.
+	 * @return {Object} The dictionary.
+	 */
 	get( object ) {
 
 		let map = this.data.get( object );
@@ -21,9 +42,15 @@ class DataMap {
 
 	}
 
+	/**
+	 * Deletes the dictionary for the given object.
+	 *
+	 * @param {Object} object - The object.
+	 * @return {Object?} The deleted dictionary.
+	 */
 	delete( object ) {
 
-		let map;
+		let map = null;
 
 		if ( this.data.has( object ) ) {
 
@@ -37,12 +64,21 @@ class DataMap {
 
 	}
 
+	/**
+	 * Returns `true` if the given object has a dictionary defined.
+	 *
+	 * @param {Object} object - The object to test.
+	 * @return {Boolean} Whether a dictionary is defined or not.
+	 */
 	has( object ) {
 
 		return this.data.has( object );
 
 	}
 
+	/**
+	 * Frees internal resources.
+	 */
 	dispose() {
 
 		this.data = new WeakMap();

package/src/renderers/common/Geometries.js

@@ -1,28 +1,31 @@
 import DataMap from './DataMap.js';
 import { AttributeType } from './Constants.js';
+import { arrayNeedsUint32 } from '../../utils.js';
 
 import { Uint16BufferAttribute, Uint32BufferAttribute } from '../../core/BufferAttribute.js';
 
-function arrayNeedsUint32( array ) {
-
-	// assumes larger values usually on last
-
-	for ( let i = array.length - 1; i >= 0; -- i ) {
-
-		if ( array[ i ] >= 65535 ) return true; // account for PRIMITIVE_RESTART_FIXED_INDEX, #24565
-
-	}
-
-	return false;
-
-}
-
+/**
+ * Returns the wireframe version for the given geometry.
+ *
+ * @private
+ * @function
+ * @param {BufferGeometry} geometry - The geometry.
+ * @return {Number} The version.
+ */
 function getWireframeVersion( geometry ) {
 
 	return ( geometry.index !== null ) ? geometry.index.version : geometry.attributes.position.version;
 
 }
 
+/**
+ * Returns a wireframe index attribute for the given geometry.
+ *
+ * @private
+ * @function
+ * @param {BufferGeometry} geometry - The geometry.
+ * @return {BufferAttribute} The wireframe index attribute.
+ */
 function getWireframeIndex( geometry ) {
 
 	const indices = [];
@@ -67,21 +70,61 @@ function getWireframeIndex( geometry ) {
 
 }
 
+/**
+ * This renderer module manages geometries.
+ *
+ * @private
+ * @augments DataMap
+ */
 class Geometries extends DataMap {
 
+	/**
+	 * Constructs a new geometry management component.
+	 *
+	 * @param {Attributes} attributes - Renderer component for managing attributes.
+	 * @param {Info} info - Renderer component for managing metrics and monitoring data.
+	 */
 	constructor( attributes, info ) {
 
 		super();
 
+		/**
+		 * Renderer component for managing attributes.
+		 *
+		 * @type {Attributes}
+		 */
 		this.attributes = attributes;
+
+		/**
+		 * Renderer component for managing metrics and monitoring data.
+		 *
+		 * @type {Info}
+		 */
 		this.info = info;
 
+		/**
+		 * Weak Map for managing attributes for wireframe rendering.
+		 *
+		 * @type {WeakMap<BufferGeometry,BufferAttribute>}
+		 */
 		this.wireframes = new WeakMap();
 
+		/**
+		 * This Weak Map is used to make sure buffer attributes are
+		 * updated only once per render call.
+		 *
+		 * @type {WeakMap<BufferAttribute,Number>}
+		 */
 		this.attributeCall = new WeakMap();
 
 	}
 
+	/**
+	 * Returns `true` if the given render object has an initialized geometry.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 * @return {Boolean} Whether if the given render object has an initialized geometry or not.
+	 */
 	has( renderObject ) {
 
 		const geometry = renderObject.geometry;
@@ -90,6 +133,11 @@ class Geometries extends DataMap {
 
 	}
 
+	/**
+	 * Prepares the geometry of the given render object for rendering.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 */
 	updateForRender( renderObject ) {
 
 		if ( this.has( renderObject ) === false ) this.initGeometry( renderObject );
@@ -98,6 +146,11 @@ class Geometries extends DataMap {
 
 	}
 
+	/**
+	 * Initializes the geometry of the given render object.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 */
 	initGeometry( renderObject ) {
 
 		const geometry = renderObject.geometry;
@@ -142,6 +195,11 @@ class Geometries extends DataMap {
 
 	}
 
+	/**
+	 * Updates the geometry attributes of the given render object.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 */
 	updateAttributes( renderObject ) {
 
 		// attributes
@@ -184,6 +242,12 @@ class Geometries extends DataMap {
 
 	}
 
+	/**
+	 * Updates the given attribute.
+	 *
+	 * @param {BufferAttribute} attribute - The attribute to update.
+	 * @param {Number} type - The attribute type.
+	 */
 	updateAttribute( attribute, type ) {
 
 		const callId = this.info.render.calls;
@@ -220,12 +284,25 @@ class Geometries extends DataMap {
 
 	}
 
+	/**
+	 * Returns the indirect buffer attribute of the given render object.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 * @return {BufferAttribute?} The indirect attribute. `null` if no indirect drawing is used.
+	 */
 	getIndirect( renderObject ) {
 
 		return renderObject.geometry.indirect;
 
 	}
 
+	/**
+	 * Returns the index of the given render object's geometry. This is implemented
+	 * in a method to return a wireframe index if necessary.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 * @return {BufferAttribute?} The index. Returns `null` for non-indexed geometries.
+	 */
 	getIndex( renderObject ) {
 
 		const { geometry, material } = renderObject;

package/src/renderers/common/IndirectStorageBufferAttribute.js

@@ -1,11 +1,34 @@
 import StorageBufferAttribute from './StorageBufferAttribute.js';
 
+/**
+ * This special type of buffer attribute is intended for compute shaders.
+ * It can be used to encode draw parameters for indirect draw calls.
+ *
+ * Note: This type of buffer attribute can only be used with `WebGPURenderer`
+ * and a WebGPU backend.
+ *
+ * @augments StorageBufferAttribute
+ */
 class IndirectStorageBufferAttribute extends StorageBufferAttribute {
 
-	constructor( array, itemSize ) {
+	/**
+	 * Constructs a new storage buffer attribute.
+	 *
+	 * @param {Number|Uint32Array} count - The item count. It is also valid to pass a `Uint32Array` as an argument.
+	 * The subsequent parameter is then obsolete.
+	 * @param {Number} itemSize - The item size.
+	 */
+	constructor( count, itemSize ) {
 
-		super( array, itemSize, Uint32Array );
+		super( count, itemSize, Uint32Array );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isIndirectStorageBufferAttribute = true;
 
 	}