super-three 0.171.0 → 0.173.0

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

@@ -1,12 +1,27 @@
 import DataMap from '../../common/DataMap.js';
 import { GPUTextureViewDimension, GPUIndexFormat, GPUFilterMode, GPUPrimitiveTopology, GPULoadOp, GPUStoreOp } from './WebGPUConstants.js';
 
+/**
+ * A WebGPU backend utility module used by {@link WebGPUTextureUtils}.
+ *
+ * @private
+ */
 class WebGPUTexturePassUtils extends DataMap {
 
+	/**
+	 * Constructs a new utility object.
+	 *
+	 * @param {GPUDevice} device - The WebGPU device.
+	 */
 	constructor( device ) {
 
 		super();
 
+		/**
+		 * The WebGPU device.
+		 *
+		 * @type {GPUDevice}
+		 */
 		this.device = device;
 
 		const mipmapVertexSource = `
@@ -71,23 +86,62 @@ fn main( @location( 0 ) vTex : vec2<f32> ) -> @location( 0 ) vec4<f32> {
 
 }
 `;
+
+		/**
+		 * The mipmap GPU sampler.
+		 *
+		 * @type {GPUSampler}
+		 */
 		this.mipmapSampler = device.createSampler( { minFilter: GPUFilterMode.Linear } );
+
+		/**
+		 * The flipY GPU sampler.
+		 *
+		 * @type {GPUSampler}
+		 */
 		this.flipYSampler = device.createSampler( { minFilter: GPUFilterMode.Nearest } ); //@TODO?: Consider using textureLoad()
 
-		// We'll need a new pipeline for every texture format used.
+		/**
+		 * A cache for GPU render pipelines used for copy/transfer passes.
+		 * Every texture format requires a unique pipeline.
+		 *
+		 * @type {Object<String,GPURenderPipeline>}
+		 */
 		this.transferPipelines = {};
+
+		/**
+		 * A cache for GPU render pipelines used for flipY passes.
+		 * Every texture format requires a unique pipeline.
+		 *
+		 * @type {Object<String,GPURenderPipeline>}
+		 */
 		this.flipYPipelines = {};
 
+		/**
+		 * The mipmap vertex shader module.
+		 *
+		 * @type {GPUShaderModule}
+		 */
 		this.mipmapVertexShaderModule = device.createShaderModule( {
 			label: 'mipmapVertex',
 			code: mipmapVertexSource
 		} );
 
+		/**
+		 * The mipmap fragment shader module.
+		 *
+		 * @type {GPUShaderModule}
+		 */
 		this.mipmapFragmentShaderModule = device.createShaderModule( {
 			label: 'mipmapFragment',
 			code: mipmapFragmentSource
 		} );
 
+		/**
+		 * The flipY fragment shader module.
+		 *
+		 * @type {GPUShaderModule}
+		 */
 		this.flipYFragmentShaderModule = device.createShaderModule( {
 			label: 'flipYFragment',
 			code: flipYFragmentSource
@@ -95,6 +149,13 @@ fn main( @location( 0 ) vTex : vec2<f32> ) -> @location( 0 ) vec4<f32> {
 
 	}
 
+	/**
+	 * Returns a render pipeline for the internal copy render pass. The pass
+	 * requires a unique render pipeline for each texture format.
+	 *
+	 * @param {String} format - The GPU texture format
+	 * @return {GPURenderPipeline} The GPU render pipeline.
+	 */
 	getTransferPipeline( format ) {
 
 		let pipeline = this.transferPipelines[ format ];
@@ -127,6 +188,13 @@ fn main( @location( 0 ) vTex : vec2<f32> ) -> @location( 0 ) vec4<f32> {
 
 	}
 
+	/**
+	 * Returns a render pipeline for the flipY render pass. The pass
+	 * requires a unique render pipeline for each texture format.
+	 *
+	 * @param {String} format - The GPU texture format
+	 * @return {GPURenderPipeline} The GPU render pipeline.
+	 */
 	getFlipYPipeline( format ) {
 
 		let pipeline = this.flipYPipelines[ format ];
@@ -159,6 +227,13 @@ fn main( @location( 0 ) vTex : vec2<f32> ) -> @location( 0 ) vec4<f32> {
 
 	}
 
+	/**
+	 * Flip the contents of the given GPU texture along its vertical axis.
+	 *
+	 * @param {GPUTexture} textureGPU - The GPU texture object.
+	 * @param {Object} textureGPUDescriptor - The texture descriptor.
+	 * @param {Number} [baseArrayLayer=0] - The index of the first array layer accessible to the texture view.
+	 */
 	flipY( textureGPU, textureGPUDescriptor, baseArrayLayer = 0 ) {
 
 		const format = textureGPUDescriptor.format;
@@ -229,6 +304,13 @@ fn main( @location( 0 ) vTex : vec2<f32> ) -> @location( 0 ) vec4<f32> {
 
 	}
 
+	/**
+	 * Generates mipmaps for the given GPU texture.
+	 *
+	 * @param {GPUTexture} textureGPU - The GPU texture object.
+	 * @param {Object} textureGPUDescriptor - The texture descriptor.
+	 * @param {Number} [baseArrayLayer=0] - The index of the first array layer accessible to the texture view.
+	 */
 	generateMipmaps( textureGPU, textureGPUDescriptor, baseArrayLayer = 0 ) {
 
 		const textureData = this.get( textureGPU );
@@ -254,6 +336,15 @@ fn main( @location( 0 ) vTex : vec2<f32> ) -> @location( 0 ) vec4<f32> {
 
 	}
 
+	/**
+	 * Since multiple copy render passes are required to generate mipmaps, the passes
+	 * are managed as render bundles to improve performance.
+	 *
+	 * @param {GPUTexture} textureGPU - The GPU texture object.
+	 * @param {Object} textureGPUDescriptor - The texture descriptor.
+	 * @param {Number} baseArrayLayer - The index of the first array layer accessible to the texture view.
+	 * @return {Array} An array of render bundles.
+	 */
 	_mipmapCreateBundles( textureGPU, textureGPUDescriptor, baseArrayLayer ) {
 
 		const pipeline = this.getTransferPipeline( textureGPUDescriptor.format );
@@ -319,6 +410,12 @@ fn main( @location( 0 ) vTex : vec2<f32> ) -> @location( 0 ) vec4<f32> {
 
 	}
 
+	/**
+	 * Executes the render bundles.
+	 *
+	 * @param {GPUCommandEncoder} commandEncoder - The GPU command encoder.
+	 * @param {Array} passes - An array of render bundles.
+	 */
 	_mipmapRunBundles( commandEncoder, passes ) {
 
 		const levels = passes.length;

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

@@ -32,25 +32,82 @@ const _compareToWebGPU = {
 
 const _flipMap = [ 0, 1, 3, 2, 4, 5 ];
 
+/**
+ * A WebGPU backend utility module for managing textures.
+ *
+ * @private
+ */
 class WebGPUTextureUtils {
 
+	/**
+	 * Constructs a new utility object.
+	 *
+	 * @param {WebGPUBackend} backend - The WebGPU backend.
+	 */
 	constructor( backend ) {
 
+		/**
+		 * A reference to the WebGPU backend.
+		 *
+		 * @type {WebGPUBackend}
+		 */
 		this.backend = backend;
 
+		/**
+		 * A reference to the pass utils.
+		 *
+		 * @type {WebGPUTexturePassUtils?}
+		 * @default null
+		 */
 		this._passUtils = null;
 
+		/**
+		 * A dictionary for managing default textures. The key
+		 * is the texture format, the value the texture object.
+		 *
+		 * @type {Object<String,Texture>}
+		 */
 		this.defaultTexture = {};
+
+		/**
+		 * A dictionary for managing default cube textures. The key
+		 * is the texture format, the value the texture object.
+		 *
+		 * @type {Object<String,CubeTexture>}
+		 */
 		this.defaultCubeTexture = {};
+
+		/**
+		 * A default video frame.
+		 *
+		 * @type {VideoFrame?}
+		 * @default null
+		 */
 		this.defaultVideoFrame = null;
 
+		/**
+		 * Represents the color attachment of the default framebuffer.
+		 *
+		 * @type {GPUTexture?}
+		 * @default null
+		 */
 		this.colorBuffer = null;
 
+		/**
+		 * Represents the depth attachment of the default framebuffer.
+		 *
+		 * @type {DepthTexture}
+		 */
 		this.depthTexture = new DepthTexture();
 		this.depthTexture.name = 'depthBuffer';
 
 	}
 
+	/**
+	 * Creates a GPU sampler for the given texture.
+	 *
+	 * @param {Texture} texture - The texture to create the sampler for.
+	 */
 	createSampler( texture ) {
 
 		const backend = this.backend;
@@ -86,6 +143,12 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Creates a default texture for the given texture that can be used
+	 * as a placeholder until the actual texture is ready for usage.
+	 *
+	 * @param {Texture} texture - The texture to create a default texture for.
+	 */
 	createDefaultTexture( texture ) {
 
 		let textureGPU;
@@ -110,6 +173,13 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Defines a texture on the GPU for the given texture object.
+	 *
+	 * @param {Texture} texture - The texture.
+	 * @param {Object} [options={}] - Optional configuration parameter.
+	 * @return {undefined}
+	 */
 	createTexture( texture, options = {} ) {
 
 		const backend = this.backend;
@@ -146,11 +216,7 @@ class WebGPUTextureUtils {
 
 		textureData.format = format;
 
-		let sampleCount = options.sampleCount !== undefined ? options.sampleCount : 1;
-
-		sampleCount = backend.utils.getSampleCount( sampleCount );
-
-		const primarySampleCount = texture.isRenderTargetTexture && ! texture.isMultisampleRenderTargetTexture ? 1 : sampleCount;
+		const { samples, primarySamples, isMSAA } = backend.utils.getTextureSampleData( texture );
 
 		let usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.COPY_SRC;
 
@@ -174,7 +240,7 @@ class WebGPUTextureUtils {
 				depthOrArrayLayers: depth,
 			},
 			mipLevelCount: levels,
-			sampleCount: primarySampleCount,
+			sampleCount: primarySamples,
 			dimension: dimension,
 			format: format,
 			usage: usage
@@ -208,12 +274,12 @@ class WebGPUTextureUtils {
 
 		}
 
-		if ( texture.isRenderTargetTexture && sampleCount > 1 && ! texture.isMultisampleRenderTargetTexture ) {
+		if ( isMSAA ) {
 
 			const msaaTextureDescriptorGPU = Object.assign( {}, textureDescriptorGPU );
 
 			msaaTextureDescriptorGPU.label = msaaTextureDescriptorGPU.label + '-msaa';
-			msaaTextureDescriptorGPU.sampleCount = sampleCount;
+			msaaTextureDescriptorGPU.sampleCount = samples;
 
 			textureData.msaaTexture = backend.device.createTexture( msaaTextureDescriptorGPU );
 
@@ -225,6 +291,11 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Destroys the GPU data for the given texture object.
+	 *
+	 * @param {Texture} texture - The texture.
+	 */
 	destroyTexture( texture ) {
 
 		const backend = this.backend;
@@ -238,6 +309,11 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Destroys the GPU sampler for the given texture.
+	 *
+	 * @param {Texture} texture - The texture to destroy the sampler for.
+	 */
 	destroySampler( texture ) {
 
 		const backend = this.backend;
@@ -247,6 +323,11 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Generates mipmaps for the given texture.
+	 *
+	 * @param {Texture} texture - The texture.
+	 */
 	generateMipmaps( texture ) {
 
 		const textureData = this.backend.get( texture );
@@ -273,6 +354,12 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Returns the color buffer representing the color
+	 * attachment of the default framebuffer.
+	 *
+	 * @return {GPUTexture} The color buffer.
+	 */
 	getColorBuffer() {
 
 		if ( this.colorBuffer ) this.colorBuffer.destroy();
@@ -296,6 +383,14 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Returns the depth buffer representing the depth
+	 * attachment of the default framebuffer.
+	 *
+	 * @param {Boolean} [depth=true] - Whether depth is enabled or not.
+	 * @param {Boolean} [stencil=false] -  Whether stencil is enabled or not.
+	 * @return {GPUTexture} The depth buffer.
+	 */
 	getDepthBuffer( depth = true, stencil = false ) {
 
 		const backend = this.backend;
@@ -336,12 +431,18 @@ class WebGPUTextureUtils {
 		depthTexture.image.width = width;
 		depthTexture.image.height = height;
 
-		this.createTexture( depthTexture, { sampleCount: backend.utils.getSampleCount( backend.renderer.samples ), width, height } );
+		this.createTexture( depthTexture, { width, height } );
 
 		return backend.get( depthTexture ).texture;
 
 	}
 
+	/**
+	 * Uploads the updated texture data to the GPU.
+	 *
+	 * @param {Texture} texture - The texture.
+	 * @param {Object} [options={}] - Optional configuration parameter.
+	 */
 	updateTexture( texture, options ) {
 
 		const textureData = this.backend.get( texture );
@@ -393,6 +494,18 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Returns texture data as a typed array.
+	 *
+	 * @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 {Promise<TypedArray>} A Promise that resolves with a typed array when the copy operation has finished.
+	 */
 	async copyTextureToBuffer( texture, x, y, width, height, faceIndex ) {
 
 		const device = this.backend.device;
@@ -442,6 +555,13 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Returns `true` if the given texture is an environment map.
+	 *
+	 * @private
+	 * @param {Texture} texture - The texture.
+	 * @return {Boolean} Whether the given texture is an environment map or not.
+	 */
 	_isEnvironmentTexture( texture ) {
 
 		const mapping = texture.mapping;
@@ -450,6 +570,13 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Returns the default GPU texture for the given format.
+	 *
+	 * @private
+	 * @param {String} format - The GPU format.
+	 * @return {GPUTexture} The GPU texture.
+	 */
 	_getDefaultTextureGPU( format ) {
 
 		let defaultTexture = this.defaultTexture[ format ];
@@ -470,6 +597,13 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Returns the default GPU cube texture for the given format.
+	 *
+	 * @private
+	 * @param {String} format - The GPU format.
+	 * @return {GPUTexture} The GPU texture.
+	 */
 	_getDefaultCubeTextureGPU( format ) {
 
 		let defaultCubeTexture = this.defaultTexture[ format ];
@@ -490,6 +624,12 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Returns the default video frame used as default data in context of video textures.
+	 *
+	 * @private
+	 * @return {VideoFrame} The video frame.
+	 */
 	_getDefaultVideoFrame() {
 
 		let defaultVideoFrame = this.defaultVideoFrame;
@@ -511,6 +651,15 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Uploads cube texture image data to the GPU memory.
+	 *
+	 * @private
+	 * @param {Array} images - The cube image data.
+	 * @param {GPUTexture} textureGPU - The GPU texture.
+	 * @param {Object} textureDescriptorGPU - The GPU texture descriptor.
+	 * @param {Boolean} flipY - Whether to flip texture data along their vertical axis or not.
+	 */
 	_copyCubeMapToTexture( images, textureGPU, textureDescriptorGPU, flipY ) {
 
 		for ( let i = 0; i < 6; i ++ ) {
@@ -533,13 +682,24 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Uploads texture image data to the GPU memory.
+	 *
+	 * @private
+	 * @param {HTMLImageElement|ImageBitmap|HTMLCanvasElement} image - The image data.
+	 * @param {GPUTexture} textureGPU - The GPU texture.
+	 * @param {Object} textureDescriptorGPU - The GPU texture descriptor.
+	 * @param {Number} originDepth - The origin depth.
+	 * @param {Boolean} flipY - Whether to flip texture data along their vertical axis or not.
+	 */
 	_copyImageToTexture( image, textureGPU, textureDescriptorGPU, originDepth, flipY ) {
 
 		const device = this.backend.device;
 
 		device.queue.copyExternalImageToTexture(
 			{
-				source: image
+				source: image,
+				flipY: flipY
 			}, {
 				texture: textureGPU,
 				mipLevel: 0,
@@ -551,14 +711,14 @@ class WebGPUTextureUtils {
 			}
 		);
 
-		if ( flipY === true ) {
-
-			this._flipY( textureGPU, textureDescriptorGPU, originDepth );
-
-		}
-
 	}
 
+	/**
+	 * Returns the pass utils singleton.
+	 *
+	 * @private
+	 * @return {WebGPUTexturePassUtils} The utils instance.
+	 */
 	_getPassUtils() {
 
 		let passUtils = this._passUtils;
@@ -573,18 +733,45 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Generates mipmaps for the given GPU texture.
+	 *
+	 * @private
+	 * @param {GPUTexture} textureGPU - The GPU texture object.
+	 * @param {Object} textureDescriptorGPU - The texture descriptor.
+	 * @param {Number} [baseArrayLayer=0] - The index of the first array layer accessible to the texture view.
+	 */
 	_generateMipmaps( textureGPU, textureDescriptorGPU, baseArrayLayer = 0 ) {
 
 		this._getPassUtils().generateMipmaps( textureGPU, textureDescriptorGPU, baseArrayLayer );
 
 	}
 
+	/**
+	 * Flip the contents of the given GPU texture along its vertical axis.
+	 *
+	 * @private
+	 * @param {GPUTexture} textureGPU - The GPU texture object.
+	 * @param {Object} textureDescriptorGPU - The texture descriptor.
+	 * @param {Number} [originDepth=0] - The origin depth.
+	 */
 	_flipY( textureGPU, textureDescriptorGPU, originDepth = 0 ) {
 
 		this._getPassUtils().flipY( textureGPU, textureDescriptorGPU, originDepth );
 
 	}
 
+	/**
+	 * Uploads texture buffer data to the GPU memory.
+	 *
+	 * @private
+	 * @param {Object} image - An object defining the image buffer data.
+	 * @param {GPUTexture} textureGPU - The GPU texture.
+	 * @param {Object} textureDescriptorGPU - The GPU texture descriptor.
+	 * @param {Number} originDepth - The origin depth.
+	 * @param {Boolean} flipY - Whether to flip texture data along their vertical axis or not.
+	 * @param {Number} [depth=0] - TODO.
+	 */
 	_copyBufferToTexture( image, textureGPU, textureDescriptorGPU, originDepth, flipY, depth = 0 ) {
 
 		// @TODO: Consider to use GPUCommandEncoder.copyBufferToTexture()
@@ -622,6 +809,14 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Uploads compressed texture data to the GPU memory.
+	 *
+	 * @private
+	 * @param {Array<Object>} mipmaps - An array with mipmap data.
+	 * @param {GPUTexture} textureGPU - The GPU texture.
+	 * @param {Object} textureDescriptorGPU - The GPU texture descriptor.
+	 */
 	_copyCompressedBufferToTexture( mipmaps, textureGPU, textureDescriptorGPU ) {
 
 		// @TODO: Consider to use GPUCommandEncoder.copyBufferToTexture()
@@ -669,10 +864,16 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * This method is only relevant for compressed texture formats. It returns a block
+	 * data descriptor for the given GPU compressed texture format.
+	 *
+	 * @private
+	 * @param {String} format - The GPU compressed texture format.
+	 * @return {Object} The block data descriptor.
+	 */
 	_getBlockData( format ) {
 
-		// this method is only relevant for compressed texture formats
-
 		if ( format === GPUTextureFormat.BC1RGBAUnorm || format === GPUTextureFormat.BC1RGBAUnormSRGB ) return { byteLength: 8, width: 4, height: 4 }; // DXT1
 		if ( format === GPUTextureFormat.BC2RGBAUnorm || format === GPUTextureFormat.BC2RGBAUnormSRGB ) return { byteLength: 16, width: 4, height: 4 }; // DXT3
 		if ( format === GPUTextureFormat.BC3RGBAUnorm || format === GPUTextureFormat.BC3RGBAUnormSRGB ) return { byteLength: 16, width: 4, height: 4 }; // DXT5
@@ -706,6 +907,13 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Converts the three.js uv wrapping constants to GPU address mode constants.
+	 *
+	 * @private
+	 * @param {Number} value - The three.js constant defining a uv wrapping mode.
+	 * @return {String} The GPU address mode.
+	 */
 	_convertAddressMode( value ) {
 
 		let addressMode = GPUAddressMode.ClampToEdge;
@@ -724,6 +932,13 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Converts the three.js filter constants to GPU filter constants.
+	 *
+	 * @private
+	 * @param {Number} value - The three.js constant defining a filter mode.
+	 * @return {String} The GPU filter mode.
+	 */
 	_convertFilterMode( value ) {
 
 		let filterMode = GPUFilterMode.Linear;
@@ -738,6 +953,13 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Returns the bytes-per-texel value for the given GPU texture format.
+	 *
+	 * @private
+	 * @param {String} format - The GPU texture format.
+	 * @return {Number} The bytes-per-texel.
+	 */
 	_getBytesPerTexel( format ) {
 
 		// 8-bit formats
@@ -794,6 +1016,13 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Returns the corresponding typed array type for the given GPU texture format.
+	 *
+	 * @private
+	 * @param {String} format - The GPU texture format.
+	 * @return {TypedArray.constructor} The typed array type.
+	 */
 	_getTypedArrayType( format ) {
 
 		if ( format === GPUTextureFormat.R8Uint ) return Uint8Array;
@@ -844,6 +1073,13 @@ class WebGPUTextureUtils {
 
 	}
 
+	/**
+	 * Returns the GPU dimensions for the given texture.
+	 *
+	 * @private
+	 * @param {Texture} texture - The texture.
+	 * @return {String} The GPU dimension.
+	 */
 	_getDimension( texture ) {
 
 		let dimension;
@@ -864,6 +1100,14 @@ class WebGPUTextureUtils {
 
 }
 
+/**
+ * Returns the GPU format for the given texture.
+ *
+ * @param {Texture} texture - The texture.
+ * @param {GPUDevice?} [device=null] - The GPU device which is used for feature detection.
+ * It is not necessary to apply the device for most formats.
+ * @return {String} The GPU format.
+ */
 export function getFormat( texture, device = null ) {
 
 	const format = texture.format;