@plastic-software/three 0.167.3 → 0.174.0

package/src/renderers/common/Background.js

@@ -1,24 +1,58 @@
 import DataMap from './DataMap.js';
 import Color4 from './Color4.js';
-import { vec4, context, normalWorld, backgroundBlurriness, backgroundIntensity, NodeMaterial, modelViewProjection } from '../../nodes/Nodes.js';
+import { vec4, context, normalWorld, backgroundBlurriness, backgroundIntensity, backgroundRotation, modelViewProjection } from '../../nodes/TSL.js';
+import NodeMaterial from '../../materials/nodes/NodeMaterial.js';
 
 import { Mesh } from '../../objects/Mesh.js';
 import { SphereGeometry } from '../../geometries/SphereGeometry.js';
-import { BackSide, LinearSRGBColorSpace } from '../../constants.js';
+import { BackSide } from '../../constants.js';
 
 const _clearColor = /*@__PURE__*/ new Color4();
 
+/**
+ * This renderer module manages the background.
+ *
+ * @private
+ * @augments DataMap
+ */
 class Background extends DataMap {
 
+	/**
+	 * Constructs a new background management component.
+	 *
+	 * @param {Renderer} renderer - The renderer.
+	 * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+	 */
 	constructor( renderer, nodes ) {
 
 		super();
 
+		/**
+		 * The renderer.
+		 *
+		 * @type {Renderer}
+		 */
 		this.renderer = renderer;
+
+		/**
+		 * Renderer component for managing nodes related logic.
+		 *
+		 * @type {Nodes}
+		 */
 		this.nodes = nodes;
 
 	}
 
+	/**
+	 * Updates the background for the given scene. Depending on how `Scene.background`
+	 * or `Scene.backgroundNode` are configured, this method might configure a simple clear
+	 * or add a mesh to the render list for rendering the background as a textured plane
+	 * or skybox.
+	 *
+	 * @param {Scene} scene - The scene.
+	 * @param {RenderList} renderList - The current render list.
+	 * @param {RenderContext} renderContext - The current render context.
+	 */
 	update( scene, renderList, renderContext ) {
 
 		const renderer = this.renderer;
@@ -30,14 +64,14 @@ class Background extends DataMap {
 
 			// no background settings, use clear color configuration from the renderer
 
-			renderer._clearColor.getRGB( _clearColor, LinearSRGBColorSpace );
+			renderer._clearColor.getRGB( _clearColor );
 			_clearColor.a = renderer._clearColor.a;
 
 		} else if ( background.isColor === true ) {
 
 			// background is an opaque color
 
-			background.getRGB( _clearColor, LinearSRGBColorSpace );
+			background.getRGB( _clearColor );
 			_clearColor.a = 1;
 
 			forceClear = true;
@@ -55,11 +89,11 @@ class Background extends DataMap {
 
 				const backgroundMeshNode = context( vec4( backgroundNode ).mul( backgroundIntensity ), {
 					// @TODO: Add Texture2D support using node context
-					getUV: () => normalWorld,
+					getUV: () => backgroundRotation.mul( normalWorld ),
 					getTextureLevel: () => backgroundBlurriness
 				} );
 
-				let viewProj = modelViewProjection();
+				let viewProj = modelViewProjection;
 				viewProj = viewProj.setZ( viewProj.w );
 
 				const nodeMaterial = new NodeMaterial();
@@ -98,7 +132,7 @@ class Background extends DataMap {
 
 			}
 
-			renderList.unshift( backgroundMesh, backgroundMesh.geometry, backgroundMesh.material, 0, 0, null );
+			renderList.unshift( backgroundMesh, backgroundMesh.geometry, backgroundMesh.material, 0, 0, null, null );
 
 		} else {
 
@@ -108,9 +142,21 @@ class Background extends DataMap {
 
 		//
 
-		if ( renderer.autoClear === true || forceClear === true ) {
+		const environmentBlendMode = renderer.xr.getEnvironmentBlendMode();
+
+		if ( environmentBlendMode === 'additive' ) {
+
+			_clearColor.set( 0, 0, 0, 1 );
+
+		} else if ( environmentBlendMode === 'alpha-blend' ) {
 
-			_clearColor.multiplyScalar( _clearColor.a );
+			_clearColor.set( 0, 0, 0, 0 );
+
+		}
+
+		//
+
+		if ( renderer.autoClear === true || forceClear === true ) {
 
 			const clearColorValue = renderContext.clearColorValue;
 
@@ -119,6 +165,18 @@ class Background extends DataMap {
 			clearColorValue.b = _clearColor.b;
 			clearColorValue.a = _clearColor.a;
 
+			// premultiply alpha
+
+			if ( renderer.backend.isWebGLBackend === true || renderer.alpha === true ) {
+
+				clearColorValue.r *= clearColorValue.a;
+				clearColorValue.g *= clearColorValue.a;
+				clearColorValue.b *= clearColorValue.a;
+
+			}
+
+			//
+
 			renderContext.depthClearValue = renderer._clearDepth;
 			renderContext.stencilClearValue = renderer._clearStencil;
 

package/src/renderers/common/BindGroup.js

@@ -1,13 +1,57 @@
 let _id = 0;
 
+/**
+ * A bind group represents a collection of bindings and thus a collection
+ * or resources. Bind groups are assigned to pipelines to provide them
+ * with the required resources (like uniform buffers or textures).
+ *
+ * @private
+ */
 class BindGroup {
 
-	constructor( name = '', bindings = [], index = 0 ) {
+	/**
+	 * Constructs a new bind group.
+	 *
+	 * @param {string} name - The bind group's name.
+	 * @param {Array<Binding>} bindings - An array of bindings.
+	 * @param {number} index - The group index.
+	 * @param {Array<Binding>} bindingsReference - An array of reference bindings.
+	 */
+	constructor( name = '', bindings = [], index = 0, bindingsReference = [] ) {
 
+		/**
+		 * The bind group's name.
+		 *
+		 * @type {string}
+		 */
 		this.name = name;
+
+		/**
+		 * An array of bindings.
+		 *
+		 * @type {Array<Binding>}
+		 */
 		this.bindings = bindings;
+
+		/**
+		 * The group index.
+		 *
+		 * @type {number}
+		 */
 		this.index = index;
 
+		/**
+		 * An array of reference bindings.
+		 *
+		 * @type {Array<Binding>}
+		 */
+		this.bindingsReference = bindingsReference;
+
+		/**
+		 * The group's ID.
+		 *
+		 * @type {number}
+		 */
 		this.id = _id ++;
 
 	}

package/src/renderers/common/Binding.js

@@ -1,19 +1,54 @@
+/**
+ * A binding represents the connection between a resource (like a texture, sampler
+ * or uniform buffer) and the resource definition in a shader stage.
+ *
+ * This module is an abstract base class for all concrete bindings types.
+ *
+ * @abstract
+ * @private
+ */
 class Binding {
 
+	/**
+	 * Constructs a new binding.
+	 *
+	 * @param {string} [name=''] - The binding's name.
+	 */
 	constructor( name = '' ) {
 
+		/**
+		 * The binding's name.
+		 *
+		 * @type {string}
+		 */
 		this.name = name;
 
+		/**
+		 * A bitmask that defines in what shader stages the
+		 * binding's resource is accessible.
+		 *
+		 * @type {number}
+		 */
 		this.visibility = 0;
 
 	}
 
+	/**
+	 * Makes sure binding's resource is visible for the given shader stage.
+	 *
+	 * @param {number} visibility - The shader stage.
+	 */
 	setVisibility( visibility ) {
 
 		this.visibility |= visibility;
 
 	}
 
+	/**
+	 * Clones the binding.
+	 *
+	 * @return {Binding} The cloned binding.
+	 */
 	clone() {
 
 		return Object.assign( new this.constructor(), this );

package/src/renderers/common/Bindings.js

@@ -1,23 +1,80 @@
 import DataMap from './DataMap.js';
 import { AttributeType } from './Constants.js';
 
+/**
+ * This renderer module manages the bindings of the renderer.
+ *
+ * @private
+ * @augments DataMap
+ */
 class Bindings extends DataMap {
 
+	/**
+	 * Constructs a new bindings management component.
+	 *
+	 * @param {Backend} backend - The renderer's backend.
+	 * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+	 * @param {Textures} textures - Renderer component for managing textures.
+	 * @param {Attributes} attributes - Renderer component for managing attributes.
+	 * @param {Pipelines} pipelines - Renderer component for managing pipelines.
+	 * @param {Info} info - Renderer component for managing metrics and monitoring data.
+	 */
 	constructor( backend, nodes, textures, attributes, pipelines, info ) {
 
 		super();
 
+		/**
+		 * The renderer's backend.
+		 *
+		 * @type {Backend}
+		 */
 		this.backend = backend;
+
+		/**
+		 * Renderer component for managing textures.
+		 *
+		 * @type {Textures}
+		 */
 		this.textures = textures;
+
+		/**
+		 * Renderer component for managing pipelines.
+		 *
+		 * @type {Pipelines}
+		 */
 		this.pipelines = pipelines;
+
+		/**
+		 * Renderer component for managing attributes.
+		 *
+		 * @type {Attributes}
+		 */
 		this.attributes = attributes;
+
+		/**
+		 * Renderer component for managing nodes related logic.
+		 *
+		 * @type {Nodes}
+		 */
 		this.nodes = nodes;
+
+		/**
+		 * Renderer component for managing metrics and monitoring data.
+		 *
+		 * @type {Info}
+		 */
 		this.info = info;
 
 		this.pipelines.bindings = this; // assign bindings to pipelines
 
 	}
 
+	/**
+	 * Returns the bind groups for the given render object.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 * @return {Array<BindGroup>} The bind groups.
+	 */
 	getForRender( renderObject ) {
 
 		const bindings = renderObject.getBindings();
@@ -32,7 +89,7 @@ class Bindings extends DataMap {
 
 				this._init( bindGroup );
 
-				this.backend.createBindings( bindGroup, bindings );
+				this.backend.createBindings( bindGroup, bindings, 0 );
 
 				groupData.bindGroup = bindGroup;
 
@@ -44,6 +101,12 @@ class Bindings extends DataMap {
 
 	}
 
+	/**
+	 * Returns the bind groups for the given compute node.
+	 *
+	 * @param {Node} computeNode - The compute node.
+	 * @return {Array<BindGroup>} The bind groups.
+	 */
 	getForCompute( computeNode ) {
 
 		const bindings = this.nodes.getForCompute( computeNode ).bindings;
@@ -56,7 +119,7 @@ class Bindings extends DataMap {
 
 				this._init( bindGroup );
 
-				this.backend.createBindings( bindGroup, bindings );
+				this.backend.createBindings( bindGroup, bindings, 0 );
 
 				groupData.bindGroup = bindGroup;
 
@@ -68,28 +131,48 @@ class Bindings extends DataMap {
 
 	}
 
+	/**
+	 * Updates the bindings for the given compute node.
+	 *
+	 * @param {Node} computeNode - The compute node.
+	 */
 	updateForCompute( computeNode ) {
 
-		this._updateBindings( computeNode, this.getForCompute( computeNode ) );
+		this._updateBindings( this.getForCompute( computeNode ) );
 
 	}
 
+	/**
+	 * Updates the bindings for the given render object.
+	 *
+	 * @param {RenderObject} renderObject - The render object.
+	 */
 	updateForRender( renderObject ) {
 
-		this._updateBindings( renderObject, this.getForRender( renderObject ) );
+		this._updateBindings( this.getForRender( renderObject ) );
 
 	}
 
-	_updateBindings( object, bindings ) {
+	/**
+	 * Updates the given array of bindings.
+	 *
+	 * @param {Array<BindGroup>} bindings - The bind groups.
+	 */
+	_updateBindings( bindings ) {
 
 		for ( const bindGroup of bindings ) {
 
-			this._update( object, bindGroup, bindings );
+			this._update( bindGroup, bindings );
 
 		}
 
 	}
 
+	/**
+	 * Initializes the given bind group.
+	 *
+	 * @param {BindGroup} bindGroup - The bind group to initialize.
+	 */
 	_init( bindGroup ) {
 
 		for ( const binding of bindGroup.bindings ) {
@@ -101,8 +184,9 @@ class Bindings extends DataMap {
 			} else if ( binding.isStorageBuffer ) {
 
 				const attribute = binding.attribute;
+				const attributeType = attribute.isIndirectStorageBufferAttribute ? AttributeType.INDIRECT : AttributeType.STORAGE;
 
-				this.attributes.update( attribute, AttributeType.STORAGE );
+				this.attributes.update( attribute, attributeType );
 
 			}
 
@@ -110,11 +194,20 @@ class Bindings extends DataMap {
 
 	}
 
-	_update( object, bindGroup, bindings ) {
+	/**
+	 * Updates the given bind group.
+	 *
+	 * @param {BindGroup} bindGroup - The bind group to update.
+	 * @param {Array<BindGroup>} bindings - The bind groups.
+	 */
+	_update( bindGroup, bindings ) {
 
 		const { backend } = this;
 
 		let needsBindingsUpdate = false;
+		let cacheBindings = true;
+		let cacheIndex = 0;
+		let version = 0;
 
 		// iterate over all bindings and check if buffer updates or a new binding group is required
 
@@ -124,7 +217,20 @@ class Bindings extends DataMap {
 
 				const updated = this.nodes.updateGroup( binding );
 
-				if ( ! updated ) continue;
+				// every uniforms group is a uniform buffer. So if no update is required,
+				// we move one with the next binding. Otherwise the next if block will update the group.
+
+				if ( updated === false ) continue;
+
+			}
+
+			if ( binding.isStorageBuffer ) {
+
+				const attribute = binding.attribute;
+				const attributeType = attribute.isIndirectStorageBufferAttribute ? AttributeType.INDIRECT : AttributeType.STORAGE;
+
+				this.attributes.update( attribute, attributeType );
+
 
 			}
 
@@ -144,26 +250,39 @@ class Bindings extends DataMap {
 
 			} else if ( binding.isSampledTexture ) {
 
-				const texture = binding.texture;
+				const texturesTextureData = this.textures.get( binding.texture );
 
-				if ( binding.needsBindingsUpdate ) needsBindingsUpdate = true;
+				if ( binding.needsBindingsUpdate( texturesTextureData.generation ) ) needsBindingsUpdate = true;
 
 				const updated = binding.update();
 
+				const texture = binding.texture;
+
 				if ( updated ) {
 
-					this.textures.updateTexture( binding.texture );
+					this.textures.updateTexture( texture );
 
 				}
 
-				const textureData = backend.get( binding.texture );
+				const textureData = backend.get( texture );
+
+				if ( textureData.externalTexture !== undefined || texturesTextureData.isDefaultTexture ) {
+
+					cacheBindings = false;
+
+				} else {
+
+					cacheIndex = cacheIndex * 10 + texture.id;
+					version += texture.version;
+
+				}
 
 				if ( backend.isWebGPUBackend === true && textureData.texture === undefined && textureData.externalTexture === undefined ) {
 
 					// TODO: Remove this once we found why updated === false isn't bound to a texture in the WebGPU backend
-					console.error( 'Bindings._update: binding should be available:', binding, updated, binding.texture, binding.textureNode.value );
+					console.error( 'Bindings._update: binding should be available:', binding, updated, texture, binding.textureNode.value, needsBindingsUpdate );
 
-					this.textures.updateTexture( binding.texture );
+					this.textures.updateTexture( texture );
 					needsBindingsUpdate = true;
 
 				}
@@ -176,7 +295,7 @@ class Bindings extends DataMap {
 
 						textureData.needsMipmap = true;
 
-					} else if ( texture.generateMipmaps === true && this.textures.needsMipmaps( texture ) && textureData.needsMipmap === true ) {
+					} else if ( this.textures.needsMipmaps( texture ) && textureData.needsMipmap === true ) {
 
 						this.backend.generateMipmaps( texture );
 
@@ -192,9 +311,7 @@ class Bindings extends DataMap {
 
 		if ( needsBindingsUpdate === true ) {
 
-			const pipeline = this.pipelines.getForRender( object );
-
-			this.backend.updateBindings( bindGroup, bindings, pipeline );
+			this.backend.updateBindings( bindGroup, bindings, cacheBindings ? cacheIndex : 0, version );
 
 		}
 

package/src/renderers/common/Buffer.js

@@ -1,32 +1,81 @@
 import Binding from './Binding.js';
 import { getFloatLength } from './BufferUtils.js';
 
+/**
+ * Represents a buffer binding type.
+ *
+ * @private
+ * @abstract
+ * @augments Binding
+ */
 class Buffer extends Binding {
 
+	/**
+	 * Constructs a new buffer.
+	 *
+	 * @param {string} name - The buffer's name.
+	 * @param {TypedArray} [buffer=null] - The buffer.
+	 */
 	constructor( name, buffer = null ) {
 
 		super( name );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isBuffer = true;
 
+		/**
+		 * The bytes per element.
+		 *
+		 * @type {number}
+		 */
 		this.bytesPerElement = Float32Array.BYTES_PER_ELEMENT;
 
+		/**
+		 * A reference to the internal buffer.
+		 *
+		 * @private
+		 * @type {TypedArray}
+		 */
 		this._buffer = buffer;
 
 	}
 
+	/**
+	 * The buffer's byte length.
+	 *
+	 * @type {number}
+	 * @readonly
+	 */
 	get byteLength() {
 
 		return getFloatLength( this._buffer.byteLength );
 
 	}
 
+	/**
+	 * A reference to the internal buffer.
+	 *
+	 * @type {Float32Array}
+	 * @readonly
+	 */
 	get buffer() {
 
 		return this._buffer;
 
 	}
 
+	/**
+	 * Updates the binding.
+	 *
+	 * @return {boolean} Whether the buffer has been updated and must be
+	 * uploaded to the GPU.
+	 */
 	update() {
 
 		return true;

package/src/renderers/common/BufferUtils.js

@@ -1,5 +1,13 @@
 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 which ensure chunk size alignment according to STD140 layout.
+ *
+ * @function
+ * @param {number} floatLength - The buffer length.
+ * @return {number} The padded length.
+ */
 function getFloatLength( floatLength ) {
 
 	// ensure chunk size alignment (STD140 layout)
@@ -8,6 +16,15 @@ function getFloatLength( floatLength ) {
 
 }
 
+/**
+ * Given the count of vectors and their vector length, this function computes
+ * a total length in bytes with buffer alignment according to STD140 layout.
+ *
+ * @function
+ * @param {number} count - The number of vectors.
+ * @param {number} [vectorLength=4] - The vector length.
+ * @return {number} The padded length.
+ */
 function getVectorLength( count, vectorLength = 4 ) {
 
 	const strideLength = getStrideLength( vectorLength );
@@ -18,6 +35,14 @@ function getVectorLength( count, vectorLength = 4 ) {
 
 }
 
+/**
+ * This function is called with a vector length and ensure the computed length
+ * matches a predefined stride (in this case `4`).
+ *
+ * @function
+ * @param {number} vectorLength - The vector length.
+ * @return {number} The padded length.
+ */
 function getStrideLength( vectorLength ) {
 
 	const strideLength = 4;