super-three 0.172.0 → 0.173.1

package/src/renderers/common/Backend.js

@@ -3,7 +3,7 @@ let _color4 = null;
 
 import Color4 from './Color4.js';
 import { Vector2 } from '../../math/Vector2.js';
-import { createCanvasElement } from '../../utils.js';
+import { createCanvasElement, warnOnce } from '../../utils.js';
 import { REVISION } from '../../constants.js';
 
 /**
@@ -58,6 +58,16 @@ class Backend {
 		 */
 		this.domElement = null;
 
+		/**
+		 * A reference to the timestamp query pool.
+   		 *
+   		 * @type {{render: TimestampQueryPool?, compute: TimestampQueryPool?}}
+		 */
+		this.timestampQueryPool = {
+			'render': null,
+			'compute': null
+		};
+
 	}
 
 	/**
@@ -255,7 +265,7 @@ class Backend {
 	// textures
 
 	/**
-	 * Creates a sampler for the given texture.
+	 * Creates a GPU sampler for the given texture.
 	 *
 	 * @abstract
 	 * @param {Texture} texture - The texture to create the sampler for.
@@ -263,7 +273,7 @@ class Backend {
 	createSampler( /*texture*/ ) { }
 
 	/**
-	 * Destroys the sampler for the given texture.
+	 * Destroys the GPU sampler for the given texture.
 	 *
 	 * @abstract
 	 * @param {Texture} texture - The texture to destroy the sampler for.
@@ -298,7 +308,7 @@ class Backend {
 	updateTexture( /*texture, options = {}*/ ) { }
 
 	/**
-	 * Generates mipmaps for the given texture
+	 * Generates mipmaps for the given texture.
 	 *
 	 * @abstract
 	 * @param {Texture} texture - The texture.
@@ -317,15 +327,16 @@ class Backend {
 	 * Returns texture data as a typed array.
 	 *
 	 * @abstract
+	 * @async
 	 * @param {Texture} texture - The texture to copy.
 	 * @param {Number} x - The x coordinate of the copy origin.
 	 * @param {Number} y - The y coordinate of the copy origin.
 	 * @param {Number} width - The width of the copy.
 	 * @param {Number} height - The height of the copy.
 	 * @param {Number} faceIndex - The face index.
-	 * @return {TypedArray} The texture data as a typed array.
+	 * @return {Promise<TypedArray>} A Promise that resolves with a typed array when the copy operation has finished.
 	 */
-	copyTextureToBuffer( /*texture, x, y, width, height, faceIndex*/ ) {}
+	async copyTextureToBuffer( /*texture, x, y, width, height, faceIndex*/ ) {}
 
 	/**
 	 * Copies data of the given source texture to the given destination texture.
@@ -352,7 +363,7 @@ class Backend {
 	// attributes
 
 	/**
-	 * Creates the buffer of a shader attribute.
+	 * Creates the GPU buffer of a shader attribute.
 	 *
 	 * @abstract
 	 * @param {BufferAttribute} attribute - The buffer attribute.
@@ -360,7 +371,7 @@ class Backend {
 	createAttribute( /*attribute*/ ) { }
 
 	/**
-	 * Creates the buffer of an indexed shader attribute.
+	 * Creates the GPU buffer of an indexed shader attribute.
 	 *
 	 * @abstract
 	 * @param {BufferAttribute} attribute - The indexed buffer attribute.
@@ -368,7 +379,7 @@ class Backend {
 	createIndexAttribute( /*attribute*/ ) { }
 
 	/**
-	 * Creates the buffer of a storage attribute.
+	 * Creates the GPU buffer of a storage attribute.
 	 *
 	 * @abstract
 	 * @param {BufferAttribute} attribute - The buffer attribute.
@@ -376,7 +387,7 @@ class Backend {
 	createStorageAttribute( /*attribute*/ ) { }
 
 	/**
-	 * Updates the buffer of a shader attribute.
+	 * Updates the GPU buffer of a shader attribute.
 	 *
 	 * @abstract
 	 * @param {BufferAttribute} attribute - The buffer attribute to update.
@@ -384,7 +395,7 @@ class Backend {
 	updateAttribute( /*attribute*/ ) { }
 
 	/**
-	 * Destroys the buffer of a shader attribute.
+	 * Destroys the GPU buffer of a shader attribute.
 	 *
 	 * @abstract
 	 * @param {BufferAttribute} attribute - The buffer attribute to destroy.
@@ -436,11 +447,33 @@ class Backend {
 	 *
 	 * @async
 	 * @abstract
-	 * @param {RenderContext} renderContext - The render context.
-	 * @param {String} type - The render context.
-	 * @return {Promise} A Promise that resolves when the time stamp has been computed.
+	 * @param {String} [type='render'] - The type of the time stamp.
+	 * @return {Promise<Number>} A Promise that resolves with the time stamp.
 	 */
-	async resolveTimestampAsync( /*renderContext, type*/ ) { }
+	async resolveTimestampsAsync( type = 'render' ) {
+
+		if ( ! this.trackTimestamp ) {
+
+			warnOnce( 'WebGPURenderer: Timestamp tracking is disabled.' );
+			return;
+
+		}
+
+		const queryPool = this.timestampQueryPool[ type ];
+		if ( ! queryPool ) {
+
+			warnOnce( `WebGPURenderer: No timestamp query pool for type '${type}' found.` );
+			return;
+
+		}
+
+		const duration = await queryPool.resolveQueriesAsync();
+
+		this.renderer.info[ type ].timestamp = duration;
+
+		return duration;
+
+	}
 
 	/**
 	 * Can be used to synchronize CPU operations with GPU tasks. So when this method is called,
@@ -452,6 +485,16 @@ class Backend {
 	 */
 	async waitForGPU() {}
 
+	/**
+	 * This method performs a readback operation by moving buffer data from
+	 * a storage buffer attribute from the GPU to the CPU.
+	 *
+	 * @async
+	 * @param {StorageBufferAttribute} attribute - The storage buffer attribute.
+	 * @return {Promise<ArrayBuffer>} A promise that resolves with the buffer data when the data are ready.
+	 */
+	async getArrayBufferAsync( /* attribute */ ) {}
+
 	/**
 	 * Checks if the given feature is supported by the backend.
 	 *

package/src/renderers/common/Background.js

@@ -142,6 +142,20 @@ class Background extends DataMap {
 
 		//
 
+		const environmentBlendMode = renderer.xr.getEnvironmentBlendMode();
+
+		if ( environmentBlendMode === 'additive' ) {
+
+			_clearColor.set( 0, 0, 0, 1 );
+
+		} else if ( environmentBlendMode === 'alpha-blend' ) {
+
+			_clearColor.set( 0, 0, 0, 0 );
+
+		}
+
+		//
+
 		if ( renderer.autoClear === true || forceClear === true ) {
 
 			const clearColorValue = renderContext.clearColorValue;

package/src/renderers/common/Binding.js

@@ -27,7 +27,7 @@ class Binding {
 		 * A bitmask that defines in what shader stages the
 		 * binding's resource is accessible.
 		 *
-		 * @type {String}
+		 * @type {Number}
 		 */
 		this.visibility = 0;
 

package/src/renderers/common/BufferUtils.js

@@ -4,7 +4,7 @@ import { GPU_CHUNK_BYTES } from './Constants.js';
 
 /**
  * This function is usually called with the length in bytes of an array buffer.
- * It returns an padded value whic ensure chunk size alignment according to STD140 layout.
+ * It returns an padded value which ensure chunk size alignment according to STD140 layout.
  *
  * @function
  * @param {Number} floatLength - The buffer length.

package/src/renderers/common/BundleGroup.js

@@ -1,7 +1,7 @@
 import { Group } from '../../objects/Group.js';
 
 /**
- * A specialized group which eanbles applications access to the
+ * 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.

package/src/renderers/common/ChainMap.js

@@ -2,14 +2,14 @@
  * 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 perforamnce reasons.
+ * for performance reasons.
  *
  * @private
  */
-export default class ChainMap {
+class ChainMap {
 
 	/**
-	 * Constructs a new chained map.
+	 * Constructs a new Chain Map.
 	 */
 	constructor() {
 
@@ -32,7 +32,7 @@ export default class ChainMap {
 
 		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 ] );
 
@@ -49,13 +49,13 @@ export default class ChainMap {
 	 *
 	 * @param {Array<Object>} keys - List of keys.
 	 * @param {Any} value - The value to set.
-	 * @return {ChainMap} A reference to this chain map.
+	 * @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 ];
 
@@ -81,7 +81,7 @@ export default class ChainMap {
 
 		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 ] );
 
@@ -94,3 +94,5 @@ export default class ChainMap {
 	}
 
 }
+
+export default ChainMap;

package/src/renderers/common/ClippingContext.js

@@ -136,7 +136,7 @@ class ClippingContext {
 	 */
 	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 );

package/src/renderers/common/Color4.js

@@ -12,10 +12,12 @@ 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 - The red value.
-	 * @param {Number} g - The green value.
-	 * @param {Number} b - The blue value.
+	 * @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 ) {
@@ -28,6 +30,8 @@ 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.

package/src/renderers/common/Geometries.js

@@ -1,37 +1,16 @@
 import DataMap from './DataMap.js';
 import { AttributeType } from './Constants.js';
+import { arrayNeedsUint32 } from '../../utils.js';
 
 import { Uint16BufferAttribute, Uint32BufferAttribute } from '../../core/BufferAttribute.js';
 
-/**
- * Returns `true` if the given array has values that require an Uint32 array type.
- *
- * @private
- * @function
- * @param {Array<Number>} array - The array to test.
- * @return {Booolean} Whether the given array has values that require an Uint32 array type or not.
- */
-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 versio.
+ * @return {Number} The version.
  */
 function getWireframeVersion( geometry ) {
 

package/src/renderers/common/Info.js

@@ -52,9 +52,7 @@ class Info {
 		 * @property {Number} triangles - The number of rendered triangle primitives of the current frame.
 		 * @property {Number} points - The number of rendered point primitives of the current frame.
 		 * @property {Number} lines - The number of rendered line primitives of the current frame.
-		 * @property {Number} previousFrameCalls - The number of render calls of the previous frame.
 		 * @property {Number} timestamp - The timestamp of the frame when using `renderer.renderAsync()`.
-		 * @property {Number} timestampCalls - The number of render calls using `renderer.renderAsync()`.
 		 */
 		this.render = {
 			calls: 0,
@@ -64,8 +62,6 @@ class Info {
 			points: 0,
 			lines: 0,
 			timestamp: 0,
-			previousFrameCalls: 0,
-			timestampCalls: 0
 		};
 
 		/**
@@ -75,16 +71,12 @@ class Info {
 		 * @readonly
 		 * @property {Number} calls - The number of compute calls since the app has been started.
 		 * @property {Number} frameCalls - The number of compute calls of the current frame.
-		 * @property {Number} previousFrameCalls - The number of compute calls of the previous frame.
 		 * @property {Number} timestamp - The timestamp of the frame when using `renderer.computeAsync()`.
-		 * @property {Number} timestampCalls - The number of render calls using `renderer.computeAsync()`.
 		 */
 		this.compute = {
 			calls: 0,
 			frameCalls: 0,
-			timestamp: 0,
-			previousFrameCalls: 0,
-			timestampCalls: 0
+			timestamp: 0
 		};
 
 		/**
@@ -137,47 +129,11 @@ class Info {
 
 	}
 
-	/**
-	 * Used by async render methods to updated timestamp metrics.
-	 *
-	 * @param {('render'|'compute')} type - The type of render call.
-	 * @param {Number} time - The duration of the compute/render call in milliseconds.
-	 */
-	updateTimestamp( type, time ) {
-
-		if ( this[ type ].timestampCalls === 0 ) {
-
-			this[ type ].timestamp = 0;
-
-		}
-
-
-		this[ type ].timestamp += time;
-
-		this[ type ].timestampCalls ++;
-
-
-		if ( this[ type ].timestampCalls >= this[ type ].previousFrameCalls ) {
-
-			this[ type ].timestampCalls = 0;
-
-		}
-
-
-	}
-
 	/**
 	 * Resets frame related metrics.
 	 */
 	reset() {
 
-		const previousRenderFrameCalls = this.render.frameCalls;
-		this.render.previousFrameCalls = previousRenderFrameCalls;
-
-		const previousComputeFrameCalls = this.compute.frameCalls;
-		this.compute.previousFrameCalls = previousComputeFrameCalls;
-
-
 		this.render.drawCalls = 0;
 		this.render.frameCalls = 0;
 		this.compute.frameCalls = 0;

package/src/renderers/common/Lighting.js

@@ -2,6 +2,7 @@ import { LightsNode } from '../../nodes/Nodes.js';
 import ChainMap from './ChainMap.js';
 
 const _defaultLights = /*@__PURE__*/ new LightsNode();
+const _chainKeys = [];
 
 /**
  * This renderer module manages the lights nodes which are unique
@@ -28,7 +29,7 @@ class Lighting extends ChainMap {
 	 * Creates a new lights node for the given array of lights.
 	 *
 	 * @param {Array<Light>} lights - The render object.
-	 * @return {Boolean} Whether if the given render object has an initialized geometry or not.
+	 * @return {LightsNode} The lights node.
 	 */
 	createNode( lights = [] ) {
 
@@ -49,19 +50,20 @@ class Lighting extends ChainMap {
 
 		if ( scene.isQuadMesh ) return _defaultLights;
 
-		// tiled lighting
-
-		const keys = [ scene, camera ];
+		_chainKeys[ 0 ] = scene;
+		_chainKeys[ 1 ] = camera;
 
-		let node = this.get( keys );
+		let node = this.get( _chainKeys );
 
 		if ( node === undefined ) {
 
 			node = this.createNode();
-			this.set( keys, node );
+			this.set( _chainKeys, node );
 
 		}
 
+		_chainKeys.length = 0;
+
 		return node;
 
 	}

package/src/renderers/common/Pipelines.js

@@ -55,7 +55,7 @@ class Pipelines extends DataMap {
 
 		/**
 		 * This dictionary maintains for each shader stage type (vertex,
-		 * fragment and compute) the progammable stage objects which
+		 * fragment and compute) the programmable stage objects which
 		 * represent the actual shader code.
 		 *
 		 * @type {Object<String,Map>}
@@ -343,7 +343,7 @@ class Pipelines extends DataMap {
 	 * @param {ProgrammableStage} stageVertex - The programmable stage representing the vertex shader.
 	 * @param {ProgrammableStage} stageFragment - The programmable stage representing the fragment shader.
 	 * @param {String} cacheKey - The cache key.
-	 * @param {Array} promises - An array of compilation promises which is only relevant in context of `Renderer.compileAsync()`.
+	 * @param {Array<Promise>?} promises - An array of compilation promises which is only relevant in context of `Renderer.compileAsync()`.
 	 * @return {ComputePipeline} The compute pipeline.
 	 */
 	_getRenderPipeline( renderObject, stageVertex, stageFragment, cacheKey, promises ) {
@@ -419,7 +419,7 @@ class Pipelines extends DataMap {
 	 * Releases the shader program.
 	 *
 	 * @private
-	 * @param {Object} program - The shdaer program to release.
+	 * @param {Object} program - The shader program to release.
 	 */
 	_releaseProgram( program ) {
 

package/src/renderers/common/PostProcessing.js

@@ -3,9 +3,6 @@ import { vec4, renderOutput } from '../../nodes/TSL.js';
 import { LinearSRGBColorSpace, NoToneMapping } from '../../constants.js';
 import QuadMesh from '../../renderers/common/QuadMesh.js';
 
-const _material = /*@__PURE__*/ new NodeMaterial();
-const _quadMesh = /*@__PURE__*/ new QuadMesh( _material );
-
 /**
  * This module is responsible to manage the post processing setups in apps.
  * You usually create a single instance of this class and use it to define
@@ -71,7 +68,17 @@ class PostProcessing {
 		 */
 		this.needsUpdate = true;
 
-		_material.name = 'PostProcessing';
+		const material = new NodeMaterial();
+		material.name = 'PostProcessing';
+
+		/**
+		 * The full screen quad that is used to render
+		 * the effects.
+		 *
+		 * @private
+		 * @type {QuadMesh}
+		 */
+		this._quadMesh = new QuadMesh( material );
 
 	}
 
@@ -94,7 +101,7 @@ class PostProcessing {
 
 		//
 
-		_quadMesh.render( renderer );
+		this._quadMesh.render( renderer );
 
 		//
 
@@ -103,6 +110,15 @@ class PostProcessing {
 
 	}
 
+	/**
+	 * Frees internal resources.
+	 */
+	dispose() {
+
+		this._quadMesh.material.dispose();
+
+	}
+
 	/**
 	 * Updates the state of the module.
 	 *
@@ -117,8 +133,8 @@ class PostProcessing {
 			const toneMapping = renderer.toneMapping;
 			const outputColorSpace = renderer.outputColorSpace;
 
-			_quadMesh.material.fragmentNode = this.outputColorTransform === true ? renderOutput( this.outputNode, toneMapping, outputColorSpace ) : this.outputNode.context( { toneMapping, outputColorSpace } );
-			_quadMesh.material.needsUpdate = true;
+			this._quadMesh.material.fragmentNode = this.outputColorTransform === true ? renderOutput( this.outputNode, toneMapping, outputColorSpace ) : this.outputNode.context( { toneMapping, outputColorSpace } );
+			this._quadMesh.material.needsUpdate = true;
 
 			this.needsUpdate = false;
 
@@ -148,7 +164,7 @@ class PostProcessing {
 
 		//
 
-		await _quadMesh.renderAsync( renderer );
+		await this._quadMesh.renderAsync( renderer );
 
 		//
 

package/src/renderers/common/QuadMesh.js

@@ -43,7 +43,7 @@ const _geometry = /*@__PURE__*/ new QuadGeometry();
  * The intended usage is to reuse a single quad mesh for rendering
  * subsequent passes by just reassigning the `material` reference.
  *
- * @augments BufferGeometry
+ * @augments Mesh
  */
 class QuadMesh extends Mesh {
 

package/src/renderers/common/RenderBundles.js

@@ -1,6 +1,8 @@
 import ChainMap from './ChainMap.js';
 import RenderBundle from './RenderBundle.js';
 
+const _chainKeys = [];
+
 /**
  * This renderer module manages render bundles.
  *
@@ -32,17 +34,21 @@ class RenderBundles {
 	get( bundleGroup, camera ) {
 
 		const bundles = this.bundles;
-		const keys = [ bundleGroup, camera ];
 
-		let bundle = bundles.get( keys );
+		_chainKeys[ 0 ] = bundleGroup;
+		_chainKeys[ 1 ] = camera;
+
+		let bundle = bundles.get( _chainKeys );
 
 		if ( bundle === undefined ) {
 
 			bundle = new RenderBundle( bundleGroup, camera );
-			bundles.set( keys, bundle );
+			bundles.set( _chainKeys, bundle );
 
 		}
 
+		_chainKeys.length = 0;
+
 		return bundle;
 
 	}