@plastic-software/three 0.174.0 → 0.175.1

package/src/core/InterleavedBufferAttribute.js

@@ -4,40 +4,113 @@ import { denormalize, normalize } from '../math/MathUtils.js';
 
 const _vector = /*@__PURE__*/ new Vector3();
 
+/**
+ * An alternative version of a buffer attribute with interleaved data. Interleaved
+ * attributes share a common interleaved data storage ({@link InterleavedBuffer}) and refer with
+ * different offsets into the buffer.
+ */
 class InterleavedBufferAttribute {
 
+	/**
+	 * Constructs a new interleaved buffer attribute.
+	 *
+	 * @param {InterleavedBuffer} interleavedBuffer - The buffer holding the interleaved data.
+	 * @param {number} itemSize - The item size.
+	 * @param {number} offset - The attribute offset into the buffer.
+	 * @param {boolean} [normalized=false] - Whether the data are normalized or not.
+	 */
 	constructor( interleavedBuffer, itemSize, offset, normalized = false ) {
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isInterleavedBufferAttribute = true;
 
+		/**
+		 * The name of the buffer attribute.
+		 *
+		 * @type {string}
+		 */
 		this.name = '';
 
+		/**
+		 * The buffer holding the interleaved data.
+		 *
+		 * @type {InterleavedBuffer}
+		 */
 		this.data = interleavedBuffer;
+
+		/**
+		 * The item size, see {@link BufferAttribute#itemSize}.
+		 *
+		 * @type {number}
+		 */
 		this.itemSize = itemSize;
+
+		/**
+		 * The attribute offset into the buffer.
+		 *
+		 * @type {number}
+		 */
 		this.offset = offset;
 
+		/**
+		 * Whether the data are normalized or not, see {@link BufferAttribute#normalized}
+		 *
+		 * @type {InterleavedBuffer}
+		 */
 		this.normalized = normalized;
 
 	}
 
+	/**
+	 * The item count of this buffer attribute.
+	 *
+	 * @type {number}
+	 * @readonly
+	 */
 	get count() {
 
 		return this.data.count;
 
 	}
 
+	/**
+	 * The array holding the interleaved buffer attribute data.
+	 *
+	 * @type {TypedArray}
+	 */
 	get array() {
 
 		return this.data.array;
 
 	}
 
+	/**
+	 * Flag to indicate that this attribute has changed and should be re-sent to
+	 * the GPU. Set this to `true` when you modify the value of the array.
+	 *
+	 * @type {number}
+	 * @default false
+	 * @param {boolean} value
+	 */
 	set needsUpdate( value ) {
 
 		this.data.needsUpdate = value;
 
 	}
 
+	/**
+	 * Applies the given 4x4 matrix to the given attribute. Only works with
+	 * item size `3`.
+	 *
+	 * @param {Matrix4} m - The matrix to apply.
+	 * @return {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	applyMatrix4( m ) {
 
 		for ( let i = 0, l = this.data.count; i < l; i ++ ) {
@@ -54,6 +127,13 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Applies the given 3x3 normal matrix to the given attribute. Only works with
+	 * item size `3`.
+	 *
+	 * @param {Matrix3} m - The normal matrix to apply.
+	 * @return {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	applyNormalMatrix( m ) {
 
 		for ( let i = 0, l = this.count; i < l; i ++ ) {
@@ -70,6 +150,13 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Applies the given 4x4 matrix to the given attribute. Only works with
+	 * item size `3` and with direction vectors.
+	 *
+	 * @param {Matrix4} m - The matrix to apply.
+	 * @return {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	transformDirection( m ) {
 
 		for ( let i = 0, l = this.count; i < l; i ++ ) {
@@ -86,6 +173,13 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Returns the given component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} component - The component index.
+	 * @return {number} The returned value.
+	 */
 	getComponent( index, component ) {
 
 		let value = this.array[ index * this.data.stride + this.offset + component ];
@@ -96,6 +190,14 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Sets the given value to the given component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} component - The component index.
+	 * @param {number} value - The value to set.
+	 * @return {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setComponent( index, component, value ) {
 
 		if ( this.normalized ) value = normalize( value, this.array );
@@ -106,6 +208,13 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Sets the x component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} x - The value to set.
+	 * @return {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setX( index, x ) {
 
 		if ( this.normalized ) x = normalize( x, this.array );
@@ -116,6 +225,13 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Sets the y component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} y - The value to set.
+	 * @return {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setY( index, y ) {
 
 		if ( this.normalized ) y = normalize( y, this.array );
@@ -126,6 +242,13 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Sets the z component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} z - The value to set.
+	 * @return {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setZ( index, z ) {
 
 		if ( this.normalized ) z = normalize( z, this.array );
@@ -136,6 +259,13 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Sets the w component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} w - The value to set.
+	 * @return {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setW( index, w ) {
 
 		if ( this.normalized ) w = normalize( w, this.array );
@@ -146,6 +276,12 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Returns the x component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @return {number} The x component.
+	 */
 	getX( index ) {
 
 		let x = this.data.array[ index * this.data.stride + this.offset ];
@@ -156,6 +292,12 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Returns the y component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @return {number} The y component.
+	 */
 	getY( index ) {
 
 		let y = this.data.array[ index * this.data.stride + this.offset + 1 ];
@@ -166,6 +308,12 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Returns the z component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @return {number} The z component.
+	 */
 	getZ( index ) {
 
 		let z = this.data.array[ index * this.data.stride + this.offset + 2 ];
@@ -176,6 +324,12 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Returns the w component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @return {number} The w component.
+	 */
 	getW( index ) {
 
 		let w = this.data.array[ index * this.data.stride + this.offset + 3 ];
@@ -186,6 +340,14 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Sets the x and y component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} x - The value for the x component to set.
+	 * @param {number} y - The value for the y component to set.
+	 * @return {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setXY( index, x, y ) {
 
 		index = index * this.data.stride + this.offset;
@@ -204,6 +366,15 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Sets the x, y and z component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} x - The value for the x component to set.
+	 * @param {number} y - The value for the y component to set.
+	 * @param {number} z - The value for the z component to set.
+	 * @return {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setXYZ( index, x, y, z ) {
 
 		index = index * this.data.stride + this.offset;
@@ -224,6 +395,16 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Sets the x, y, z and w component of the vector at the given index.
+	 *
+	 * @param {number} index - The index into the buffer attribute.
+	 * @param {number} x - The value for the x component to set.
+	 * @param {number} y - The value for the y component to set.
+	 * @param {number} z - The value for the z component to set.
+	 * @param {number} w - The value for the w component to set.
+	 * @return {InterleavedBufferAttribute} A reference to this instance.
+	 */
 	setXYZW( index, x, y, z, w ) {
 
 		index = index * this.data.stride + this.offset;
@@ -246,6 +427,14 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Returns a new buffer attribute with copied values from this instance.
+	 *
+	 * If no parameter is provided, cloning an interleaved buffer attribute will de-interleave buffer data.
+	 *
+	 * @param {Object} [data] - An object with interleaved buffers that allows to retain the interleaved property.
+	 * @return {BufferAttribute|InterleavedBufferAttribute} A clone of this instance.
+	 */
 	clone( data ) {
 
 		if ( data === undefined ) {
@@ -288,6 +477,14 @@ class InterleavedBufferAttribute {
 
 	}
 
+	/**
+	 * Serializes the buffer attribute into JSON.
+	 *
+	 * If no parameter is provided, cloning an interleaved buffer attribute will de-interleave buffer data.
+	 *
+	 * @param {Object} [data] - An optional value holding meta information about the serialization.
+	 * @return {Object} A JSON object representing the serialized buffer attribute.
+	 */
 	toJSON( data ) {
 
 		if ( data === undefined ) {

package/src/core/Layers.js

@@ -1,56 +1,117 @@
+/**
+ * A layers object assigns an 3D object to 1 or more of 32
+ * layers numbered `0` to `31` - internally the layers are stored as a
+ * bit mask], and by default all 3D objects are a member of layer `0`.
+ *
+ * This can be used to control visibility - an object must share a layer with
+ * a camera to be visible when that camera's view is
+ * rendered.
+ *
+ * All classes that inherit from {@link Object3D} have an `layers` property which
+ * is an instance of this class.
+ */
 class Layers {
 
+	/**
+	 * Constructs a new layers instance, with membership
+	 * initially set to layer `0`.
+	 */
 	constructor() {
 
+		/**
+		 * A bit mask storing which of the 32 layers this layers object is currently
+		 * a member of.
+		 *
+		 * @type {number}
+		 */
 		this.mask = 1 | 0;
 
 	}
 
-	set( channel ) {
+	/**
+	 * Sets membership to the given layer, and remove membership all other layers.
+	 *
+	 * @param {number} layer - The layer to set.
+	 */
+	set( layer ) {
 
-		this.mask = ( 1 << channel | 0 ) >>> 0;
+		this.mask = ( 1 << layer | 0 ) >>> 0;
 
 	}
 
-	enable( channel ) {
+	/**
+	 * Adds membership of the given layer.
+	 *
+	 * @param {number} layer - The layer to enable.
+	 */
+	enable( layer ) {
 
-		this.mask |= 1 << channel | 0;
+		this.mask |= 1 << layer | 0;
 
 	}
 
+	/**
+	 * Adds membership to all layers.
+	 */
 	enableAll() {
 
 		this.mask = 0xffffffff | 0;
 
 	}
 
-	toggle( channel ) {
+	/**
+	 * Toggles the membership of the given layer.
+	 *
+	 * @param {number} layer - The layer to toggle.
+	 */
+	toggle( layer ) {
 
-		this.mask ^= 1 << channel | 0;
+		this.mask ^= 1 << layer | 0;
 
 	}
 
-	disable( channel ) {
+	/**
+	 * Removes membership of the given layer.
+	 *
+	 * @param {number} layer - The layer to enable.
+	 */
+	disable( layer ) {
 
-		this.mask &= ~ ( 1 << channel | 0 );
+		this.mask &= ~ ( 1 << layer | 0 );
 
 	}
 
+	/**
+	 * Removes the membership from all layers.
+	 */
 	disableAll() {
 
 		this.mask = 0;
 
 	}
 
+	/**
+	 * Returns `true` if this and the given layers object have at least one
+	 * layer in common.
+	 *
+	 * @param {Layers} layers - The layers to test.
+	 * @return {boolean } Whether this and the given layers object have at least one layer in common or not.
+	 */
 	test( layers ) {
 
 		return ( this.mask & layers.mask ) !== 0;
 
 	}
 
-	isEnabled( channel ) {
+	/**
+	 * Returns `true` if the given layer is enabled.
+	 *
+	 * @param {number} layer - The layer to test.
+	 * @return {boolean } Whether the given layer is enabled or not.
+	 */
+	isEnabled( layer ) {
 
-		return ( this.mask & ( 1 << channel | 0 ) ) !== 0;
+		return ( this.mask & ( 1 << layer | 0 ) ) !== 0;
 
 	}
 

package/src/core/Object3D.js

@@ -330,6 +330,29 @@ class Object3D extends EventDispatcher {
 		 */
 		this.animations = [];
 
+		/**
+		 * Custom depth material to be used when rendering to the depth map. Can only be used
+		 * in context of meshes. When shadow-casting with a {@link DirectionalLight} or {@link SpotLight},
+		 * if you are modifying vertex positions in the vertex shader you must specify a custom depth
+		 * material for proper shadows.
+		 *
+		 * Only relevant in context of {@link WebGLRenderer}.
+		 *
+		 * @type {(Material|undefined)}
+		 * @default undefined
+		 */
+		this.customDepthMaterial = undefined;
+
+		/**
+		 * Same as {@link Object3D#customDepthMaterial}, but used with {@link PointLight}.
+		 *
+		 * Only relevant in context of {@link WebGLRenderer}.
+		 *
+		 * @type {(Material|undefined)}
+		 * @default undefined
+		 */
+		this.customDistanceMaterial = undefined;
+
 		/**
 		 * An object that can be used to store custom data about the 3D object. It
 		 * should not hold references to functions as these will not be cloned.

package/src/core/Raycaster.js

@@ -4,18 +4,86 @@ import { Layers } from './Layers.js';
 
 const _matrix = /*@__PURE__*/ new Matrix4();
 
+/**
+ * This class is designed to assist with raycasting. Raycasting is used for
+ * mouse picking (working out what objects in the 3d space the mouse is over)
+ * amongst other things.
+ */
 class Raycaster {
 
+	/**
+	 * Constructs a new raycaster.
+	 *
+	 * @param {Vector3} origin - The origin vector where the ray casts from.
+	 * @param {Vector3} direction - The (normalized) direction vector that gives direction to the ray.
+	 * @param {number} [near=0] - All results returned are further away than near. Near can't be negative.
+	 * @param {number} [far=Infinity] - All results returned are closer than far. Far can't be lower than near.
+	 */
 	constructor( origin, direction, near = 0, far = Infinity ) {
 
+		/**
+		 * The ray used for raycasting.
+		 *
+		 * @type {Ray}
+		 */
 		this.ray = new Ray( origin, direction );
-		// direction is assumed to be normalized (for accurate distance calculations)
 
+		/**
+		 * All results returned are further away than near. Near can't be negative.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.near = near;
+
+		/**
+		 * All results returned are further away than near. Near can't be negative.
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.far = far;
+
+		/**
+		 * The camera to use when raycasting against view-dependent objects such as
+		 * billboarded objects like sprites. This field can be set manually or
+		 * is set when calling `setFromCamera()`.
+		 *
+		 * @type {?Camera}
+		 * @default null
+		 */
 		this.camera = null;
+
+		/**
+		 * Allows to selectively ignore 3D objects when performing intersection tests.
+		 * The following code example ensures that only 3D objects on layer `1` will be
+		 * honored by raycaster.
+		 * ```js
+		 * raycaster.layers.set( 1 );
+		 * object.layers.enable( 1 );
+		 * ```
+		 *
+		 * @type {Layers}
+		 */
 		this.layers = new Layers();
 
+
+		/**
+		 * A parameter object that configures the raycasting. It has the structure:
+		 *
+		 * ```
+		 * {
+		 * 	Mesh: {},
+		 * 	Line: { threshold: 1 },
+		 * 	LOD: {},
+		 * 	Points: { threshold: 1 },
+		 * 	Sprite: {}
+		 * }
+		 * ```
+		 * Where `threshold` is the precision of the raycaster when intersecting objects, in world units.
+		 *
+		 * @type {Object}
+		 */
 		this.params = {
 			Mesh: {},
 			Line: { threshold: 1 },
@@ -26,6 +94,12 @@ class Raycaster {
 
 	}
 
+	/**
+	 * Updates the ray with a new origin and direction by copying the values from the arguments.
+	 *
+	 * @param {Vector3} origin - The origin vector where the ray casts from.
+	 * @param {Vector3} direction - The (normalized) direction vector that gives direction to the ray.
+	 */
 	set( origin, direction ) {
 
 		// direction is assumed to be normalized (for accurate distance calculations)
@@ -34,6 +108,13 @@ class Raycaster {
 
 	}
 
+	/**
+	 * Uses the given coordinates and camera to compute a new origin and direction for the internal ray.
+	 *
+	 * @param {Vector2} coords - 2D coordinates of the mouse, in normalized device coordinates (NDC).
+	 * X and Y components should be between `-1` and `1`.
+	 * @param {Camera} camera - The camera from which the ray should originate.
+	 */
 	setFromCamera( coords, camera ) {
 
 		if ( camera.isPerspectiveCamera ) {
@@ -56,6 +137,12 @@ class Raycaster {
 
 	}
 
+	/**
+	 * Uses the given WebXR controller to compute a new origin and direction for the internal ray.
+	 *
+	 * @param {WebXRController} controller - The controller to copy the position and direction from.
+	 * @return {Raycaster} A reference to this raycaster.
+	 */
 	setFromXRController( controller ) {
 
 		_matrix.identity().extractRotation( controller.matrixWorld );
@@ -67,6 +154,42 @@ class Raycaster {
 
 	}
 
+	/**
+	 * The intersection point of a raycaster intersection test.
+	 * @typedef {Object} Raycaster~Intersection
+	 * @property {number} distance - The distance from the ray's origin to the intersection point.
+	 * @property {number} distanceToRay -  Some 3D objects e.g. {@link Points} provide the distance of the
+	 * intersection to the nearest point on the ray. For other objects it will be `undefined`.
+	 * @property {Vector3} point - The intersection point, in world coordinates.
+	 * @property {Object} face - The face that has been intersected.
+	 * @property {number} faceIndex - The face index.
+	 * @property {Object3D} object - The 3D object that has been intersected.
+	 * @property {Vector2} uv - U,V coordinates at point of intersection.
+	 * @property {Vector2} uv1 - Second set of U,V coordinates at point of intersection.
+	 * @property {Vector3} uv1 - Interpolated normal vector at point of intersection.
+	 * @property {number} instanceId - The index number of the instance where the ray
+	 * intersects the {@link InstancedMesh}.
+	 */
+
+	/**
+	 * Checks all intersection between the ray and the object with or without the
+	 * descendants. Intersections are returned sorted by distance, closest first.
+	 *
+	 * `Raycaster` delegates to the `raycast()` method of the passed 3D object, when
+	 * evaluating whether the ray intersects the object or not. This allows meshes to respond
+	 * differently to ray casting than lines or points.
+	 *
+	 * Note that for meshes, faces must be pointed towards the origin of the ray in order
+	 * to be detected; intersections of the ray passing through the back of a face will not
+	 * be detected. To raycast against both faces of an object, you'll want to set  {@link Material#side}
+	 * to `THREE.DoubleSide`.
+	 *
+	 * @param {Object3D} object - The 3D object to check for intersection with the ray.
+	 * @param {boolean} [recursive=true] - If set to `true`, it also checks all descendants.
+	 * Otherwise it only checks intersection with the object.
+	 * @param {Array<Raycaster~Intersection>} [intersects=[]] The target array that holds the result of the method.
+	 * @return {Array<Raycaster~Intersection>} An array holding the intersection points.
+	 */
 	intersectObject( object, recursive = true, intersects = [] ) {
 
 		intersect( object, this, intersects, recursive );
@@ -77,6 +200,16 @@ class Raycaster {
 
 	}
 
+	/**
+	 * Checks all intersection between the ray and the objects with or without
+	 * the descendants. Intersections are returned sorted by distance, closest first.
+	 *
+	 * @param {Array<Object3D>} objects - The 3D objects to check for intersection with the ray.
+	 * @param {boolean} [recursive=true] - If set to `true`, it also checks all descendants.
+	 * Otherwise it only checks intersection with the object.
+	 * @param {Array<Raycaster~Intersection>} [intersects=[]] The target array that holds the result of the method.
+	 * @return {Array<Raycaster~Intersection>} An array holding the intersection points.
+	 */
 	intersectObjects( objects, recursive = true, intersects = [] ) {
 
 		for ( let i = 0, l = objects.length; i < l; i ++ ) {