@needle-tools/three 0.169.20-experimental.0 → 0.183.2-canary.0

package/src/renderers/webgpu/utils/WebGPUBindingUtils.js

@@ -1,180 +1,274 @@
 import {
-	GPUTextureAspect, GPUTextureViewDimension, GPUTextureSampleType
+	GPUTextureAspect, GPUTextureViewDimension, GPUTextureSampleType, GPUBufferBindingType, GPUStorageTextureAccess,
+	GPUSamplerBindingType, GPUShaderStage
 } from './WebGPUConstants.js';
 
-import { FloatType, IntType, UnsignedIntType } from '../../../constants.js';
+import { FloatType, IntType, UnsignedIntType, Compatibility } from '../../../constants.js';
+import { NodeAccess } from '../../../nodes/core/constants.js';
+import { isTypedArray, error } from '../../../utils.js';
+import { hashString } from '../../../nodes/core/NodeUtils.js';
+
+/**
+ * Class representing a WebGPU bind group layout.
+ *
+ * @private
+ */
+class BindGroupLayout {
+
+	/**
+	 * Constructs a new layout.
+	 *
+	 * @param {GPUBindGroupLayout} layoutGPU - A GPU Bind Group Layout.
+	 */
+	constructor( layoutGPU ) {
+
+		/**
+		 * The current GPUBindGroupLayout.
+		 *
+		 * @type {GPUBindGroupLayout}
+		 */
+		this.layoutGPU = layoutGPU;
+
+		/**
+		 * The number of bind groups that use this layout.
+		 *
+		 * @type {number}
+		 */
+		this.usedTimes = 0;
 
+	}
+
+}
+
+/**
+ * A WebGPU backend utility module for managing bindings.
+ *
+ * When reading the documentation it's helpful to keep in mind that
+ * all class definitions starting with 'GPU*' are modules from the
+ * WebGPU API. So for example `BindGroup` is a class from the engine
+ * whereas `GPUBindGroup` is a class from WebGPU.
+ *
+ * @private
+ */
 class WebGPUBindingUtils {
 
+	/**
+	 * Constructs a new utility object.
+	 *
+	 * @param {WebGPUBackend} backend - The WebGPU backend.
+	 */
 	constructor( backend ) {
 
+		/**
+		 * A reference to the WebGPU backend.
+		 *
+		 * @type {WebGPUBackend}
+		 */
 		this.backend = backend;
-		this.bindGroupLayoutCache = new WeakMap();
+
+		/**
+		 * A cache that maps combinations of layout entries to existing bind group layouts.
+		 *
+		 * @private
+		 * @type {Map<string, BindGroupLayout>}
+		 */
+		this._bindGroupLayoutCache = new Map();
 
 	}
 
+	/**
+	 * Creates a GPU bind group layout for the given bind group.
+	 *
+	 * @param {BindGroup} bindGroup - The bind group.
+	 * @return {GPUBindGroupLayout} The GPU bind group layout.
+	 */
 	createBindingsLayout( bindGroup ) {
 
 		const backend = this.backend;
 		const device = backend.device;
 
-		const entries = [];
-
-		let index = 0;
-
-		for ( const binding of bindGroup.bindings ) {
-
-			const bindingGPU = {
-				binding: index ++,
-				visibility: binding.visibility
-			};
-
-			if ( binding.isUniformBuffer || binding.isStorageBuffer ) {
+		const bindingsData = backend.get( bindGroup );
 
-				const buffer = {}; // GPUBufferBindingLayout
+		// check if the the bind group already has a layout
 
-				if ( binding.isStorageBuffer ) {
+		if ( bindingsData.layout ) {
 
-					buffer.type = binding.access;
+			return bindingsData.layout.layoutGPU;
 
-				}
+		}
 
-				bindingGPU.buffer = buffer;
+		// if not, assing one
 
-			} else if ( binding.isSampler ) {
+		const entries = this._createLayoutEntries( bindGroup );
+		const bindGroupLayoutKey = hashString( JSON.stringify( entries ) );
 
-				const sampler = {}; // GPUSamplerBindingLayout
+		// try to find an existing layout in the cache
 
-				if ( binding.texture.isDepthTexture ) {
+		let bindGroupLayout = this._bindGroupLayoutCache.get( bindGroupLayoutKey );
 
-					if ( binding.texture.compareFunction !== null ) {
+		// if not create a new one
 
-						sampler.type = 'comparison';
+		if ( bindGroupLayout === undefined ) {
 
-					}
+			bindGroupLayout = new BindGroupLayout( device.createBindGroupLayout( { entries } ) );
+			this._bindGroupLayoutCache.set( bindGroupLayoutKey, bindGroupLayout );
 
-				}
+		}
 
-				bindingGPU.sampler = sampler;
+		bindGroupLayout.usedTimes ++;
 
-			} else if ( binding.isSampledTexture && binding.texture.isVideoTexture ) {
+		bindingsData.layout = bindGroupLayout;
+		bindingsData.layoutKey = bindGroupLayoutKey;
 
-				bindingGPU.externalTexture = {}; // GPUExternalTextureBindingLayout
+		return bindGroupLayout.layoutGPU;
 
-			} else if ( binding.isSampledTexture && binding.store ) {
+	}
 
-				const format = this.backend.get( binding.texture ).texture.format;
-				const access = binding.access;
+	/**
+	 * Creates bindings from the given bind group definition.
+	 *
+	 * @param {BindGroup} bindGroup - The bind group.
+	 * @param {Array<BindGroup>} bindings - Array of bind groups.
+	 * @param {number} cacheIndex - The cache index.
+	 * @param {number} version - The version.
+	 */
+	createBindings( bindGroup, bindings, cacheIndex, version = 0 ) {
+
+		const { backend } = this;
+		const bindingsData = backend.get( bindGroup );
 
-				bindingGPU.storageTexture = { format, access }; // GPUStorageTextureBindingLayout
+		// setup (static) binding layout and (dynamic) binding group
 
-			} else if ( binding.isSampledTexture ) {
+		const bindLayoutGPU = this.createBindingsLayout( bindGroup );
 
-				const texture = {}; // GPUTextureBindingLayout
+		let bindGroupGPU;
 
-				if ( binding.texture.isMultisampleRenderTargetTexture === true ) {
+		if ( cacheIndex > 0 ) {
 
-					texture.multisampled = true;
+			if ( bindingsData.groups === undefined ) {
 
-				}
+				bindingsData.groups = [];
+				bindingsData.versions = [];
 
-				if ( binding.texture.isDepthTexture ) {
+			}
 
-					texture.sampleType = GPUTextureSampleType.Depth;
+			if ( bindingsData.versions[ cacheIndex ] === version ) {
 
-				} else if ( binding.texture.isDataTexture || binding.texture.isDataArrayTexture || binding.texture.isData3DTexture ) {
+				bindGroupGPU = bindingsData.groups[ cacheIndex ];
 
-					const type = binding.texture.type;
+			}
 
-					if ( type === IntType ) {
+		}
 
-						texture.sampleType = GPUTextureSampleType.SInt;
+		if ( bindGroupGPU === undefined ) {
 
-					} else if ( type === UnsignedIntType ) {
+			bindGroupGPU = this.createBindGroup( bindGroup, bindLayoutGPU );
 
-						texture.sampleType = GPUTextureSampleType.UInt;
+			if ( cacheIndex > 0 ) {
 
-					} else if ( type === FloatType ) {
+				bindingsData.groups[ cacheIndex ] = bindGroupGPU;
+				bindingsData.versions[ cacheIndex ] = version;
 
-						if ( this.backend.hasFeature( 'float32-filterable' ) ) {
+			}
 
-							texture.sampleType = GPUTextureSampleType.Float;
+		}
 
-						} else {
+		bindingsData.group = bindGroupGPU;
 
-							texture.sampleType = GPUTextureSampleType.UnfilterableFloat;
+	}
 
-						}
+	/**
+	 * Updates a buffer binding.
+	 *
+	 *  @param {Buffer} binding - The buffer binding to update.
+	 */
+	updateBinding( binding ) {
 
-					}
+		const backend = this.backend;
+		const device = backend.device;
 
-				}
+		const array = binding.buffer; // cpu
+		const buffer = backend.get( binding ).buffer; // gpu
 
-				if ( binding.isSampledCubeTexture ) {
+		const updateRanges = binding.updateRanges;
 
-					texture.viewDimension = GPUTextureViewDimension.Cube;
+		if ( updateRanges.length === 0 ) {
 
-				} else if ( binding.texture.isDataArrayTexture || binding.texture.isCompressedArrayTexture ) {
+			device.queue.writeBuffer(
+				buffer,
+				0,
+				array,
+				0
+			);
 
-					texture.viewDimension = GPUTextureViewDimension.TwoDArray;
+		} else {
 
-				} else if ( binding.isSampledTexture3D ) {
+			const isTyped = isTypedArray( array );
+			const byteOffsetFactor = isTyped ? 1 : array.BYTES_PER_ELEMENT;
 
-					texture.viewDimension = GPUTextureViewDimension.ThreeD;
+			for ( let i = 0, l = updateRanges.length; i < l; i ++ ) {
 
-				}
+				const range = updateRanges[ i ];
 
-				bindingGPU.texture = texture;
+				const dataOffset = range.start * byteOffsetFactor;
+				const size = range.count * byteOffsetFactor;
 
-			} else {
+				const bufferOffset = dataOffset * ( isTyped ? array.BYTES_PER_ELEMENT : 1 ); // bufferOffset is always in bytes
 
-				console.error( `WebGPUBindingUtils: Unsupported binding "${ binding }".` );
+				device.queue.writeBuffer(
+					buffer,
+					bufferOffset,
+					array,
+					dataOffset,
+					size
+				);
 
 			}
 
-			entries.push( bindingGPU );
-
 		}
 
-		return device.createBindGroupLayout( { entries } );
-
 	}
 
-	createBindings( bindGroup ) {
+	/**
+	 * Creates a GPU bind group for the camera index.
+	 *
+	 * @param {Uint32Array} data - The index data.
+	 * @param {GPUBindGroupLayout} layoutGPU - The GPU bind group layout.
+	 * @return {GPUBindGroup} The GPU bind group.
+	 */
+	createBindGroupIndex( data, layoutGPU ) {
 
-		const { backend, bindGroupLayoutCache } = this;
-		const bindingsData = backend.get( bindGroup );
-
-		// setup (static) binding layout and (dynamic) binding group
-
-		let bindLayoutGPU = bindGroupLayoutCache.get( bindGroup.bindingsReference );
-
-		if ( bindLayoutGPU === undefined ) {
-
-			bindLayoutGPU = this.createBindingsLayout( bindGroup );
-			bindGroupLayoutCache.set( bindGroup.bindingsReference, bindLayoutGPU );
-
-		}
-
-		const bindGroupGPU = this.createBindGroup( bindGroup, bindLayoutGPU );
-
-		bindingsData.layout = bindLayoutGPU;
-		bindingsData.group = bindGroupGPU;
+		const backend = this.backend;
+		const device = backend.device;
 
-	}
+		const usage = GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST;
+		const index = data[ 0 ];
 
-	updateBinding( binding ) {
+		const buffer = device.createBuffer( {
+			label: 'bindingCameraIndex_' + index,
+			size: 16, // uint(4) * 4
+			usage: usage
+		} );
 
-		const backend = this.backend;
-		const device = backend.device;
+		device.queue.writeBuffer( buffer, 0, data, 0 );
 
-		const buffer = binding.buffer;
-		const bufferGPU = backend.get( binding ).buffer;
+		const entries = [ { binding: 0, resource: { buffer } } ];
 
-		device.queue.writeBuffer( bufferGPU, 0, buffer, 0 );
+		return device.createBindGroup( {
+			label: 'bindGroupCameraIndex_' + index,
+			layout: layoutGPU,
+			entries
+		} );
 
 	}
 
+	/**
+	 * Creates a GPU bind group for the given bind group and GPU layout.
+	 *
+	 * @param {BindGroup} bindGroup - The bind group.
+	 * @param {GPUBindGroupLayout} layoutGPU - The GPU bind group layout.
+	 * @return {GPUBindGroup} The GPU bind group.
+	 */
 	createBindGroup( bindGroup, layoutGPU ) {
 
 		const backend = this.backend;
@@ -195,40 +289,44 @@ class WebGPUBindingUtils {
 
 					const usage = GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST;
 
-					const bufferGPU = device.createBuffer( {
-						label: 'bindingBuffer_' + binding.name,
-						size: byteLength,
-						usage: usage
-					} );
+					const visibilities = [];
+					if ( binding.visibility & GPUShaderStage.VERTEX ) {
 
-					bindingData.buffer = bufferGPU;
+						visibilities.push( 'vertex' );
 
-				}
+					}
 
-				entriesGPU.push( { binding: bindingPoint, resource: { buffer: bindingData.buffer } } );
+					if ( binding.visibility & GPUShaderStage.FRAGMENT ) {
 
-			} else if ( binding.isStorageBuffer ) {
+						visibilities.push( 'fragment' );
 
-				const bindingData = backend.get( binding );
+					}
 
-				if ( bindingData.buffer === undefined ) {
+					if ( binding.visibility & GPUShaderStage.COMPUTE ) {
 
-					const attribute = binding.attribute;
-					//const usage = GPUBufferUsage.STORAGE | GPUBufferUsage.VERTEX | /*GPUBufferUsage.COPY_SRC |*/ GPUBufferUsage.COPY_DST;
+						visibilities.push( 'compute' );
 
-					//backend.attributeUtils.createAttribute( attribute, usage ); // @TODO: Move it to universal renderer
+					}
+
+					const bufferVisibility = `(${visibilities.join( ',' )})`;
+
+					const bufferGPU = device.createBuffer( {
+						label: `bindingBuffer${binding.id}_${binding.name}_${bufferVisibility}`,
+						size: byteLength,
+						usage: usage
+					} );
 
-					bindingData.buffer = backend.get( attribute ).buffer;
+					bindingData.buffer = bufferGPU;
 
 				}
 
 				entriesGPU.push( { binding: bindingPoint, resource: { buffer: bindingData.buffer } } );
 
-			} else if ( binding.isSampler ) {
+			} else if ( binding.isStorageBuffer ) {
 
-				const textureGPU = backend.get( binding.texture );
+				const buffer = backend.get( binding.attribute ).buffer;
 
-				entriesGPU.push( { binding: bindingPoint, resource: textureGPU.sampler } );
+				entriesGPU.push( { binding: bindingPoint, resource: { buffer: buffer } } );
 
 			} else if ( binding.isSampledTexture ) {
 
@@ -243,7 +341,16 @@ class WebGPUBindingUtils {
 				} else {
 
 					const mipLevelCount = binding.store ? 1 : textureData.texture.mipLevelCount;
-					const propertyName = `view-${ textureData.texture.width }-${ textureData.texture.height }-${ mipLevelCount }`;
+					const baseMipLevel = binding.store ? binding.mipLevel : 0;
+					let propertyName = `view-${ textureData.texture.width }-${ textureData.texture.height }`;
+
+					if ( textureData.texture.depthOrArrayLayers > 1 ) {
+
+						propertyName += `-${ textureData.texture.depthOrArrayLayers }`;
+
+					}
+
+					propertyName += `-${ mipLevelCount }-${ baseMipLevel }`;
 
 					resourceGPU = textureData[ propertyName ];
 
@@ -261,7 +368,7 @@ class WebGPUBindingUtils {
 
 							dimensionViewGPU = GPUTextureViewDimension.ThreeD;
 
-						} else if ( binding.texture.isDataArrayTexture || binding.texture.isCompressedArrayTexture ) {
+						} else if ( binding.texture.isArrayTexture || binding.texture.isDataArrayTexture || binding.texture.isCompressedArrayTexture ) {
 
 							dimensionViewGPU = GPUTextureViewDimension.TwoDArray;
 
@@ -271,7 +378,7 @@ class WebGPUBindingUtils {
 
 						}
 
-						resourceGPU = textureData[ propertyName ] = textureData.texture.createView( { aspect: aspectGPU, dimension: dimensionViewGPU, mipLevelCount } );
+						resourceGPU = textureData[ propertyName ] = textureData.texture.createView( { aspect: aspectGPU, dimension: dimensionViewGPU, mipLevelCount, baseMipLevel } );
 
 					}
 
@@ -279,6 +386,12 @@ class WebGPUBindingUtils {
 
 				entriesGPU.push( { binding: bindingPoint, resource: resourceGPU } );
 
+			} else if ( binding.isSampler ) {
+
+				const textureGPU = backend.get( binding.texture );
+
+				entriesGPU.push( { binding: bindingPoint, resource: textureGPU.sampler } );
+
 			}
 
 			bindingPoint ++;
@@ -293,6 +406,237 @@ class WebGPUBindingUtils {
 
 	}
 
+	/**
+	 * Creates a GPU bind group layout entries for the given bind group.
+	 *
+	 * @private
+	 * @param {BindGroup} bindGroup - The bind group.
+	 * @return {Array<GPUBindGroupLayoutEntry>} The GPU bind group layout entries.
+	 */
+	_createLayoutEntries( bindGroup ) {
+
+		const entries = [];
+		let index = 0;
+
+		for ( const binding of bindGroup.bindings ) {
+
+			const backend = this.backend;
+
+			const bindingGPU = {
+				binding: index,
+				visibility: binding.visibility
+			};
+
+			if ( binding.isUniformBuffer || binding.isStorageBuffer ) {
+
+				const buffer = {}; // GPUBufferBindingLayout
+
+				if ( binding.isStorageBuffer ) {
+
+					if ( binding.visibility & GPUShaderStage.COMPUTE ) {
+
+						// compute
+
+						if ( binding.access === NodeAccess.READ_WRITE || binding.access === NodeAccess.WRITE_ONLY ) {
+
+							buffer.type = GPUBufferBindingType.Storage;
+
+						} else {
+
+							buffer.type = GPUBufferBindingType.ReadOnlyStorage;
+
+						}
+
+					} else {
+
+						buffer.type = GPUBufferBindingType.ReadOnlyStorage;
+
+					}
+
+				}
+
+				bindingGPU.buffer = buffer;
+
+			} else if ( binding.isSampledTexture && binding.store ) {
+
+				const storageTexture = {}; // GPUStorageTextureBindingLayout
+				storageTexture.format = this.backend.get( binding.texture ).texture.format;
+
+				const access = binding.access;
+
+				if ( access === NodeAccess.READ_WRITE ) {
+
+					storageTexture.access = GPUStorageTextureAccess.ReadWrite;
+
+				} else if ( access === NodeAccess.WRITE_ONLY ) {
+
+					storageTexture.access = GPUStorageTextureAccess.WriteOnly;
+
+				} else {
+
+					storageTexture.access = GPUStorageTextureAccess.ReadOnly;
+
+				}
+
+				if ( binding.texture.isArrayTexture ) {
+
+					storageTexture.viewDimension = GPUTextureViewDimension.TwoDArray;
+
+				} else if ( binding.texture.is3DTexture ) {
+
+					storageTexture.viewDimension = GPUTextureViewDimension.ThreeD;
+
+				}
+
+				bindingGPU.storageTexture = storageTexture;
+
+			} else if ( binding.isSampledTexture ) {
+
+				const texture = {}; // GPUTextureBindingLayout
+
+				const { primarySamples } = backend.utils.getTextureSampleData( binding.texture );
+
+				if ( primarySamples > 1 ) {
+
+					texture.multisampled = true;
+
+					if ( ! binding.texture.isDepthTexture ) {
+
+						texture.sampleType = GPUTextureSampleType.UnfilterableFloat;
+
+					}
+
+				}
+
+				if ( binding.texture.isDepthTexture ) {
+
+					if ( backend.compatibilityMode && binding.texture.compareFunction === null ) {
+
+						texture.sampleType = GPUTextureSampleType.UnfilterableFloat;
+
+					} else {
+
+						texture.sampleType = GPUTextureSampleType.Depth;
+
+					}
+
+				} else if ( binding.texture.isDataTexture || binding.texture.isDataArrayTexture || binding.texture.isData3DTexture ) {
+
+					const type = binding.texture.type;
+
+					if ( type === IntType ) {
+
+						texture.sampleType = GPUTextureSampleType.SInt;
+
+					} else if ( type === UnsignedIntType ) {
+
+						texture.sampleType = GPUTextureSampleType.UInt;
+
+					} else if ( type === FloatType ) {
+
+						if ( this.backend.hasFeature( 'float32-filterable' ) ) {
+
+							texture.sampleType = GPUTextureSampleType.Float;
+
+						} else {
+
+							texture.sampleType = GPUTextureSampleType.UnfilterableFloat;
+
+						}
+
+					}
+
+				}
+
+				if ( binding.isSampledCubeTexture ) {
+
+					texture.viewDimension = GPUTextureViewDimension.Cube;
+
+				} else if ( binding.texture.isArrayTexture || binding.texture.isDataArrayTexture || binding.texture.isCompressedArrayTexture ) {
+
+					texture.viewDimension = GPUTextureViewDimension.TwoDArray;
+
+				} else if ( binding.isSampledTexture3D ) {
+
+					texture.viewDimension = GPUTextureViewDimension.ThreeD;
+
+				}
+
+				bindingGPU.texture = texture;
+
+			} else if ( binding.isSampler ) {
+
+				const sampler = {}; // GPUSamplerBindingLayout
+
+				if ( binding.texture.isDepthTexture ) {
+
+					if ( binding.texture.compareFunction !== null && backend.hasCompatibility( Compatibility.TEXTURE_COMPARE ) ) {
+
+						sampler.type = GPUSamplerBindingType.Comparison;
+
+					} else {
+
+						// Depth textures without compare must use non-filtering sampler
+						sampler.type = GPUSamplerBindingType.NonFiltering;
+
+					}
+
+				}
+
+				bindingGPU.sampler = sampler;
+
+			} else {
+
+				error( `WebGPUBindingUtils: Unsupported binding "${ binding }".` );
+
+			}
+
+			entries.push( bindingGPU );
+			index ++;
+
+		}
+
+		return entries;
+
+	}
+
+	/**
+	 * Delete the data associated with a bind group.
+	 *
+	 * @param {BindGroup} bindGroup - The bind group.
+	 */
+	deleteBindGroupData( bindGroup ) {
+
+		const { backend } = this;
+
+		const bindingsData = backend.get( bindGroup );
+
+		if ( bindingsData.layout ) {
+
+			bindingsData.layout.usedTimes --;
+
+			if ( bindingsData.layout.usedTimes === 0 ) {
+
+				this._bindGroupLayoutCache.delete( bindingsData.layoutKey );
+
+			}
+
+			bindingsData.layout = undefined;
+			bindingsData.layoutKey = undefined;
+
+		}
+
+	}
+
+	/**
+	 * Frees internal resources.
+	 */
+	dispose() {
+
+		this._bindGroupLayoutCache.clear();
+
+	}
+
 }
 
 export default WebGPUBindingUtils;