@plastic-software/three 0.167.3 → 0.174.0

package/src/renderers/webgl-fallback/utils/WebGLAttributeUtils.js

@@ -2,6 +2,14 @@ import { IntType } from '../../../constants.js';
 
 let _id = 0;
 
+/**
+ * This module is internally used in context of compute shaders.
+ * This type of shader is not natively supported in WebGL 2 and
+ * thus implemented via Transform Feedback. `DualAttributeData`
+ * manages the related data.
+ *
+ * @private
+ */
 class DualAttributeData {
 
 	constructor( attributeData, dualBuffer ) {
@@ -46,14 +54,35 @@ class DualAttributeData {
 
 }
 
+/**
+ * A WebGL 2 backend utility module for managing shader attributes.
+ *
+ * @private
+ */
 class WebGLAttributeUtils {
 
+	/**
+	 * Constructs a new utility object.
+	 *
+	 * @param {WebGLBackend} backend - The WebGL 2 backend.
+	 */
 	constructor( backend ) {
 
+		/**
+		 * A reference to the WebGL 2 backend.
+		 *
+		 * @type {WebGLBackend}
+		 */
 		this.backend = backend;
 
 	}
 
+	/**
+	 * Creates the GPU buffer for the given buffer attribute.
+	 *
+	 * @param {BufferAttribute} attribute - The buffer attribute.
+	 * @param {GLenum } bufferType - A flag that indicates the buffer type and thus binding point target.
+	 */
 	createAttribute( attribute, bufferType ) {
 
 		const backend = this.backend;
@@ -141,7 +170,7 @@ class WebGLAttributeUtils {
 
 		if ( attribute.isStorageBufferAttribute || attribute.isStorageInstancedBufferAttribute ) {
 
-			// create buffer for tranform feedback use
+			// create buffer for transform feedback use
 			const bufferGPUDual = this._createBuffer( gl, bufferType, array, usage );
 			attributeData = new DualAttributeData( attributeData, bufferGPUDual );
 
@@ -151,6 +180,11 @@ class WebGLAttributeUtils {
 
 	}
 
+	/**
+	 * Updates the GPU buffer of the given buffer attribute.
+	 *
+	 * @param {BufferAttribute} attribute - The buffer attribute.
+	 */
 	updateAttribute( attribute ) {
 
 		const backend = this.backend;
@@ -190,6 +224,11 @@ class WebGLAttributeUtils {
 
 	}
 
+	/**
+	 * Destroys the GPU buffer of the given buffer attribute.
+	 *
+	 * @param {BufferAttribute} attribute - The buffer attribute.
+	 */
 	destroyAttribute( attribute ) {
 
 		const backend = this.backend;
@@ -209,6 +248,14 @@ class WebGLAttributeUtils {
 
 	}
 
+	/**
+	 * 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 ) {
 
 		const backend = this.backend;
@@ -233,14 +280,30 @@ class WebGLAttributeUtils {
 
 		const dstBuffer = new attribute.array.constructor( array.length );
 
+		// Ensure the buffer is bound before reading
+		gl.bindBuffer( gl.COPY_WRITE_BUFFER, writeBuffer );
+
 		gl.getBufferSubData( gl.COPY_WRITE_BUFFER, 0, dstBuffer );
 
 		gl.deleteBuffer( writeBuffer );
 
+		gl.bindBuffer( gl.COPY_READ_BUFFER, null );
+		gl.bindBuffer( gl.COPY_WRITE_BUFFER, null );
+
 		return dstBuffer.buffer;
 
 	}
 
+	/**
+	 * Creates a WebGL buffer with the given data.
+	 *
+	 * @private
+	 * @param {WebGL2RenderingContext} gl - The rendering context.
+	 * @param {GLenum } bufferType - A flag that indicates the buffer type and thus binding point target.
+	 * @param {TypedArray} array - The array of the buffer attribute.
+	 * @param {GLenum} usage - The usage.
+	 * @return {WebGLBuffer} The WebGL buffer.
+	 */
 	_createBuffer( gl, bufferType, array, usage ) {
 
 		const bufferGPU = gl.createBuffer();

package/src/renderers/webgl-fallback/utils/WebGLCapabilities.js

@@ -1,13 +1,41 @@
+/**
+ * A WebGL 2 backend utility module for managing the device's capabilities.
+ *
+ * @private
+ */
 class WebGLCapabilities {
 
+	/**
+	 * Constructs a new utility object.
+	 *
+	 * @param {WebGLBackend} backend - The WebGL 2 backend.
+	 */
 	constructor( backend ) {
 
+		/**
+		 * A reference to the WebGL 2 backend.
+		 *
+		 * @type {WebGLBackend}
+		 */
 		this.backend = backend;
 
+		/**
+		 * This value holds the cached max anisotropy value.
+		 *
+		 * @type {?number}
+		 * @default null
+		 */
 		this.maxAnisotropy = null;
 
 	}
 
+	/**
+	 * Returns the maximum anisotropy texture filtering value. This value
+	 * depends on the device and is reported by the `EXT_texture_filter_anisotropic`
+	 * WebGL extension.
+	 *
+	 * @return {number} The maximum anisotropy texture filtering value.
+	 */
 	getMaxAnisotropy() {
 
 		if ( this.maxAnisotropy !== null ) return this.maxAnisotropy;

package/src/renderers/webgl-fallback/utils/WebGLExtensions.js

@@ -1,16 +1,55 @@
+/**
+ * A WebGL 2 backend utility module for managing extensions.
+ *
+ * @private
+ */
 class WebGLExtensions {
 
+	/**
+	 * Constructs a new utility object.
+	 *
+	 * @param {WebGLBackend} backend - The WebGL 2 backend.
+	 */
 	constructor( backend ) {
 
+		/**
+		 * A reference to the WebGL 2 backend.
+		 *
+		 * @type {WebGLBackend}
+		 */
 		this.backend = backend;
 
+		/**
+		 * A reference to the rendering context.
+		 *
+		 * @type {WebGL2RenderingContext}
+		 */
 		this.gl = this.backend.gl;
+
+		/**
+		 * A list with all the supported WebGL extensions.
+		 *
+		 * @type {Array<string>}
+		 */
 		this.availableExtensions = this.gl.getSupportedExtensions();
 
+		/**
+		 * A dictionary with requested WebGL extensions.
+		 * The key is the name of the extension, the value
+		 * the requested extension object.
+		 *
+		 * @type {Object<string,Object>}
+		 */
 		this.extensions = {};
 
 	}
 
+	/**
+	 * Returns the extension object for the given extension name.
+	 *
+	 * @param {string} name - The extension name.
+	 * @return {Object} The extension object.
+	 */
 	get( name ) {
 
 		let extension = this.extensions[ name ];
@@ -27,6 +66,12 @@ class WebGLExtensions {
 
 	}
 
+	/**
+	 * Returns `true` if the requested extension is available.
+	 *
+	 * @param {string} name - The extension name.
+	 * @return {boolean} Whether the given extension is available or not.
+	 */
 	has( name ) {
 
 		return this.availableExtensions.includes( name );