@plastic-software/three 0.167.3 → 0.174.0

package/src/renderers/common/BundleGroup.js

@@ -0,0 +1,83 @@
+import { Group } from '../../objects/Group.js';
+
+/**
+ * A specialized group which enables applications access to the
+ * Render Bundle API of WebGPU. The group with all its descendant nodes
+ * are considered as one render bundle and processed as such by
+ * the renderer.
+ *
+ * This module is only fully supported by `WebGPURenderer` with a WebGPU backend.
+ * With a WebGL backend, the group can technically be rendered but without
+ * any performance improvements.
+ *
+ * @augments Group
+ */
+class BundleGroup extends Group {
+
+	/**
+	 * Constructs a new bundle group.
+	 */
+	constructor() {
+
+		super();
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isBundleGroup = true;
+
+		/**
+		 * This property is only relevant for detecting types
+		 * during serialization/deserialization. It should always
+		 * match the class name.
+		 *
+		 * @type {string}
+		 * @readonly
+		 * @default 'BundleGroup'
+		 */
+		this.type = 'BundleGroup';
+
+		/**
+		 * Whether the bundle is static or not. When set to `true`, the structure
+		 * is assumed to be static and does not change. E.g. no new objects are
+		 * added to the group
+		 *
+		 * If a change is required, an update can still be forced by setting the
+		 * `needsUpdate` flag to `true`.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
+		this.static = true;
+
+		/**
+		 * The bundle group's version.
+		 *
+		 * @type {number}
+		 * @readonly
+		 * @default 0
+		 */
+		this.version = 0;
+
+	}
+
+	/**
+	 * Set this property to `true` when the bundle group has changed.
+	 *
+	 * @type {boolean}
+	 * @default false
+	 * @param {boolean} value
+	 */
+	set needsUpdate( value ) {
+
+		if ( value === true ) this.version ++;
+
+	}
+
+}
+
+export default BundleGroup;

package/src/renderers/common/ChainMap.js

@@ -1,16 +1,38 @@
-export default class ChainMap {
-
+/**
+ * Data structure for the renderer. It allows defining values
+ * with chained, hierarchical keys. Keys are meant to be
+ * objects since the module internally works with Weak Maps
+ * for performance reasons.
+ *
+ * @private
+ */
+class ChainMap {
+
+	/**
+	 * Constructs a new Chain Map.
+	 */
 	constructor() {
 
+		/**
+		 * The root Weak Map.
+		 *
+		 * @type {WeakMap}
+		 */
 		this.weakMap = new WeakMap();
 
 	}
 
+	/**
+	 * Returns the value for the given array of keys.
+	 *
+	 * @param {Array<Object>} keys - List of keys.
+	 * @return {any} The value. Returns `undefined` if no value was found.
+	 */
 	get( keys ) {
 
 		let map = this.weakMap;
 
-		for ( let i = 0; i < keys.length; i ++ ) {
+		for ( let i = 0; i < keys.length - 1; i ++ ) {
 
 			map = map.get( keys[ i ] );
 
@@ -22,11 +44,18 @@ export default class ChainMap {
 
 	}
 
+	/**
+	 * Sets the value for the given keys.
+	 *
+	 * @param {Array<Object>} keys - List of keys.
+	 * @param {any} value - The value to set.
+	 * @return {ChainMap} A reference to this Chain Map.
+	 */
 	set( keys, value ) {
 
 		let map = this.weakMap;
 
-		for ( let i = 0; i < keys.length; i ++ ) {
+		for ( let i = 0; i < keys.length - 1; i ++ ) {
 
 			const key = keys[ i ];
 
@@ -36,15 +65,23 @@ export default class ChainMap {
 
 		}
 
-		return map.set( keys[ keys.length - 1 ], value );
+		map.set( keys[ keys.length - 1 ], value );
+
+		return this;
 
 	}
 
+	/**
+	 * Deletes a value for the given keys.
+	 *
+	 * @param {Array<Object>} keys - The keys.
+	 * @return {boolean} Returns `true` if the value has been removed successfully and `false` if the value has not be found.
+	 */
 	delete( keys ) {
 
 		let map = this.weakMap;
 
-		for ( let i = 0; i < keys.length; i ++ ) {
+		for ( let i = 0; i < keys.length - 1; i ++ ) {
 
 			map = map.get( keys[ i ] );
 
@@ -57,3 +94,5 @@ export default class ChainMap {
 	}
 
 }
+
+export default ChainMap;

package/src/renderers/common/ClippingContext.js

@@ -4,37 +4,119 @@ import { Vector4 } from '../../math/Vector4.js';
 
 const _plane = /*@__PURE__*/ new Plane();
 
-let _clippingContextVersion = 0;
-
+/**
+ * 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 {
 
-	constructor() {
-
-		this.version = ++ _clippingContextVersion;
-
-		this.globalClippingCount = 0;
-
-		this.localClippingCount = 0;
-		this.localClippingEnabled = false;
-		this.localClipIntersection = false;
+	/**
+	 * 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;
+
+		/**
+		 * The clipping context's cache key.
+		 *
+		 * @type {string}
+		 */
+		this.cacheKey = '';
+
+		/**
+		 * 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();
 
-		this.planes = [];
+		/**
+		 * 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;
+
+		if ( parentContext !== null ) {
+
+			this.viewNormalMatrix = parentContext.viewNormalMatrix;
+			this.clippingGroupContexts = parentContext.clippingGroupContexts;
+
+			this.shadowPass = parentContext.shadowPass;
+			this.viewMatrix = parentContext.viewMatrix;
 
-		this.parentVersion = 0;
-		this.viewNormalMatrix = new Matrix3();
+		}
 
 	}
 
-	projectPlanes( source, offset ) {
+	/**
+	 * 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;
-		const planes = this.planes;
 
 		for ( let i = 0; i < l; i ++ ) {
 
 			_plane.copy( source[ i ] ).applyMatrix4( this.viewMatrix, this.viewNormalMatrix );
 
-			const v = planes[ offset + i ];
+			const v = destination[ offset + i ];
 			const normal = _plane.normal;
 
 			v.x = - normal.x;
@@ -46,119 +128,132 @@ class ClippingContext {
 
 	}
 
-	updateGlobal( renderer, camera ) {
+	/**
+	 * 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 ) {
 
-		const rendererClippingPlanes = renderer.clippingPlanes;
+		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;
 
-		if ( Array.isArray( rendererClippingPlanes ) && rendererClippingPlanes.length !== 0 ) {
+		if ( parentContext.version !== this.parentVersion ) {
 
-			const l = rendererClippingPlanes.length;
+			this.intersectionPlanes = Array.from( parentContext.intersectionPlanes );
+			this.unionPlanes = Array.from( parentContext.unionPlanes );
+			this.parentVersion = parentContext.version;
 
-			if ( l !== this.globalClippingCount ) {
+		}
 
-				const planes = [];
+		if ( this.clipIntersection !== clippingGroup.clipIntersection ) {
 
-				for ( let i = 0; i < l; i ++ ) {
+			this.clipIntersection = clippingGroup.clipIntersection;
 
-					planes.push( new Vector4() );
+			if ( this.clipIntersection ) {
 
-				}
+				this.unionPlanes.length = parentContext.unionPlanes.length;
 
-				this.globalClippingCount = l;
-				this.planes = planes;
+			} else {
 
-				update = true;
+				this.intersectionPlanes.length = parentContext.intersectionPlanes.length;
 
 			}
 
-			this.projectPlanes( rendererClippingPlanes, 0 );
+		}
 
-		} else if ( this.globalClippingCount !== 0 ) {
+		const srcClippingPlanes = clippingGroup.clippingPlanes;
+		const l = srcClippingPlanes.length;
 
-			this.globalClippingCount = 0;
-			this.planes = [];
-			update = true;
+		let dstClippingPlanes;
+		let offset;
 
-		}
+		if ( this.clipIntersection ) {
 
-		if ( renderer.localClippingEnabled !== this.localClippingEnabled ) {
+			dstClippingPlanes = this.intersectionPlanes;
+			offset = parentContext.intersectionPlanes.length;
 
-			this.localClippingEnabled = renderer.localClippingEnabled;
-			update = true;
+		} else {
 
-		}
+			dstClippingPlanes = this.unionPlanes;
+			offset = parentContext.unionPlanes.length;
 
-		if ( update ) this.version = _clippingContextVersion ++;
+		}
 
-	}
+		if ( dstClippingPlanes.length !== offset + l ) {
 
-	update( parent, material ) {
+			dstClippingPlanes.length = offset + l;
 
-		let update = false;
+			for ( let i = 0; i < l; i ++ ) {
 
-		if ( this !== parent && parent.version !== this.parentVersion ) {
+				dstClippingPlanes[ offset + i ] = new Vector4();
 
-			this.globalClippingCount = material.isShadowNodeMaterial ? 0 : parent.globalClippingCount;
-			this.localClippingEnabled = parent.localClippingEnabled;
-			this.planes = Array.from( parent.planes );
-			this.parentVersion = parent.version;
-			this.viewMatrix = parent.viewMatrix;
-			this.viewNormalMatrix = parent.viewNormalMatrix;
+			}
 
 			update = true;
 
 		}
 
-		if ( this.localClippingEnabled ) {
-
-			const localClippingPlanes = material.clippingPlanes;
-
-			if ( ( Array.isArray( localClippingPlanes ) && localClippingPlanes.length !== 0 ) ) {
-
-				const l = localClippingPlanes.length;
-				const planes = this.planes;
-				const offset = this.globalClippingCount;
-
-				if ( update || l !== this.localClippingCount ) {
+		this.projectPlanes( srcClippingPlanes, dstClippingPlanes, offset );
 
-					planes.length = offset + l;
+		if ( update ) {
 
-					for ( let i = 0; i < l; i ++ ) {
+			this.version ++;
+			this.cacheKey = `${ this.intersectionPlanes.length }:${ this.unionPlanes.length }`;
 
-						planes[ offset + i ] = new Vector4();
-
-					}
+		}
 
-					this.localClippingCount = l;
-					update = true;
+	}
 
-				}
+	/**
+	 * Returns a clipping context for the given clipping group.
+	 *
+	 * @param {ClippingGroup} clippingGroup - The clipping group.
+	 * @return {ClippingContext} The clipping context.
+	 */
+	getGroupContext( clippingGroup ) {
 
-				this.projectPlanes( localClippingPlanes, offset );
+		if ( this.shadowPass && ! clippingGroup.clipShadows ) return this;
 
+		let context = this.clippingGroupContexts.get( clippingGroup );
 
-			} else if ( this.localClippingCount !== 0 ) {
+		if ( context === undefined ) {
 
-				this.localClippingCount = 0;
-				update = true;
+			context = new ClippingContext( this );
+			this.clippingGroupContexts.set( clippingGroup, context );
 
-			}
+		}
 
-			if ( this.localClipIntersection !== material.clipIntersection ) {
+		context.update( this, clippingGroup );
 
-				this.localClipIntersection = material.clipIntersection;
-				update = true;
+		return context;
 
-			}
+	}
 
-		}
+	/**
+	 * The count of union clipping planes.
+	 *
+	 * @type {number}
+	 * @readonly
+	 */
+	get unionClippingCount() {
 
-		if ( update ) this.version = _clippingContextVersion ++;
+		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/Constants.js

@@ -1,7 +1,8 @@
 export const AttributeType = {
 	VERTEX: 1,
 	INDEX: 2,
-	STORAGE: 4
+	STORAGE: 3,
+	INDIRECT: 4
 };
 
 // size of a chunk in bytes (STD140 layout)

package/src/renderers/common/CubeRenderTarget.js

@@ -1,7 +1,7 @@
 import { equirectUV } from '../../nodes/utils/EquirectUVNode.js';
 import { texture as TSL_Texture } from '../../nodes/accessors/TextureNode.js';
-import { positionWorldDirection } from '../../nodes/accessors/PositionNode.js';
-import { createNodeMaterialFromType } from '../../nodes/materials/NodeMaterial.js';
+import { positionWorldDirection } from '../../nodes/accessors/Position.js';
+import NodeMaterial from '../../materials/nodes/NodeMaterial.js';
 
 import { WebGLCubeRenderTarget } from '../../renderers/WebGLCubeRenderTarget.js';
 import { Scene } from '../../scenes/Scene.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;
@@ -40,7 +53,7 @@ class CubeRenderTarget extends WebGLCubeRenderTarget {
 
 		const uvNode = equirectUV( positionWorldDirection );
 
-		const material = createNodeMaterialFromType( 'MeshBasicNodeMaterial' );
+		const material = new NodeMaterial();
 		material.colorNode = TSL_Texture( texture, uvNode, 0 );
 		material.side = BackSide;
 		material.blending = NoBlending;
@@ -54,8 +67,14 @@ class CubeRenderTarget extends WebGLCubeRenderTarget {
 		if ( texture.minFilter === LinearMipmapLinearFilter ) texture.minFilter = LinearFilter;
 
 		const camera = new CubeCamera( 1, 10, this );
+
+		const currentMRT = renderer.getMRT();
+		renderer.setMRT( null );
+
 		camera.update( renderer, scene );
 
+		renderer.setMRT( currentMRT );
+
 		texture.minFilter = currentMinFilter;
 		texture.currentGenerateMipmaps = currentGenerateMipmaps;