@plastic-software/three 0.167.3 → 0.174.0

package/src/renderers/common/RendererUtils.js

@@ -0,0 +1,191 @@
+import { Color } from '../../math/Color.js';
+
+/**
+ * Saves the state of the given renderer and stores it into the given state object.
+ *
+ * If not state object is provided, the function creates one.
+ *
+ * @function
+ * @param {Renderer} renderer - The renderer.
+ * @param {Object} [state={}] - The state.
+ * @return {Object} The state.
+ */
+export function saveRendererState( renderer, state = {} ) {
+
+	state.toneMapping = renderer.toneMapping;
+	state.toneMappingExposure = renderer.toneMappingExposure;
+	state.outputColorSpace = renderer.outputColorSpace;
+	state.renderTarget = renderer.getRenderTarget();
+	state.activeCubeFace = renderer.getActiveCubeFace();
+	state.activeMipmapLevel = renderer.getActiveMipmapLevel();
+	state.renderObjectFunction = renderer.getRenderObjectFunction();
+	state.pixelRatio = renderer.getPixelRatio();
+	state.mrt = renderer.getMRT();
+	state.clearColor = renderer.getClearColor( state.clearColor || new Color() );
+	state.clearAlpha = renderer.getClearAlpha();
+	state.autoClear = renderer.autoClear;
+	state.scissorTest = renderer.getScissorTest();
+
+	return state;
+
+}
+
+/**
+ * Saves the state of the given renderer and stores it into the given state object.
+ * Besides, the function also resets the state of the renderer to its default values.
+ *
+ * If not state object is provided, the function creates one.
+ *
+ * @function
+ * @param {Renderer} renderer - The renderer.
+ * @param {Object} [state={}] - The state.
+ * @return {Object} The state.
+ */
+export function resetRendererState( renderer, state ) {
+
+	state = saveRendererState( renderer, state );
+
+	renderer.setMRT( null );
+	renderer.setRenderObjectFunction( null );
+	renderer.setClearColor( 0x000000, 1 );
+	renderer.autoClear = true;
+
+	return state;
+
+}
+
+/**
+ * Restores the state of the given renderer from the given state object.
+ *
+ * @function
+ * @param {Renderer} renderer - The renderer.
+ * @param {Object} state - The state to restore.
+ */
+export function restoreRendererState( renderer, state ) {
+
+	renderer.toneMapping = state.toneMapping;
+	renderer.toneMappingExposure = state.toneMappingExposure;
+	renderer.outputColorSpace = state.outputColorSpace;
+	renderer.setRenderTarget( state.renderTarget, state.activeCubeFace, state.activeMipmapLevel );
+	renderer.setRenderObjectFunction( state.renderObjectFunction );
+	renderer.setPixelRatio( state.pixelRatio );
+	renderer.setMRT( state.mrt );
+	renderer.setClearColor( state.clearColor, state.clearAlpha );
+	renderer.autoClear = state.autoClear;
+	renderer.setScissorTest( state.scissorTest );
+
+}
+
+/**
+ * Saves the state of the given scene and stores it into the given state object.
+ *
+ * If not state object is provided, the function creates one.
+ *
+ * @function
+ * @param {Scene} scene - The scene.
+ * @param {Object} [state={}] - The state.
+ * @return {Object} The state.
+ */
+export function saveSceneState( scene, state = {} ) {
+
+	state.background = scene.background;
+	state.backgroundNode = scene.backgroundNode;
+	state.overrideMaterial = scene.overrideMaterial;
+
+	return state;
+
+}
+
+/**
+ * Saves the state of the given scene and stores it into the given state object.
+ * Besides, the function also resets the state of the scene to its default values.
+ *
+ * If not state object is provided, the function creates one.
+ *
+ * @function
+ * @param {Scene} scene - The scene.
+ * @param {Object} [state={}] - The state.
+ * @return {Object} The state.
+ */
+export function resetSceneState( scene, state ) {
+
+	state = saveSceneState( scene, state );
+
+	scene.background = null;
+	scene.backgroundNode = null;
+	scene.overrideMaterial = null;
+
+	return state;
+
+}
+
+/**
+ * Restores the state of the given scene from the given state object.
+ *
+ * @function
+ * @param {Scene} scene - The scene.
+ * @param {Object} state - The state to restore.
+ */
+export function restoreSceneState( scene, state ) {
+
+	scene.background = state.background;
+	scene.backgroundNode = state.backgroundNode;
+	scene.overrideMaterial = state.overrideMaterial;
+
+}
+
+/**
+ * Saves the state of the given renderer and scene and stores it into the given state object.
+ *
+ * If not state object is provided, the function creates one.
+ *
+ * @function
+ * @param {Renderer} renderer - The renderer.
+ * @param {Scene} scene - The scene.
+ * @param {Object} [state={}] - The state.
+ * @return {Object} The state.
+ */
+export function saveRendererAndSceneState( renderer, scene, state = {} ) {
+
+	state = saveRendererState( renderer, state );
+	state = saveSceneState( scene, state );
+
+	return state;
+
+}
+
+/**
+ * Saves the state of the given renderer and scene and stores it into the given state object.
+ * Besides, the function also resets the state of the renderer and scene to its default values.
+ *
+ * If not state object is provided, the function creates one.
+ *
+ * @function
+ * @param {Renderer} renderer - The renderer.
+ * @param {Scene} scene - The scene.
+ * @param {Object} [state={}] - The state.
+ * @return {Object} The state.
+ */
+export function resetRendererAndSceneState( renderer, scene, state ) {
+
+	state = resetRendererState( renderer, state );
+	state = resetSceneState( scene, state );
+
+	return state;
+
+}
+
+/**
+ * Restores the state of the given renderer and scene from the given state object.
+ *
+ * @function
+ * @param {Renderer} renderer - The renderer.
+ * @param {Scene} scene - The scene.
+ * @param {Object} state - The state to restore.
+ */
+export function restoreRendererAndSceneState( renderer, scene, state ) {
+
+	restoreRendererState( renderer, state );
+	restoreSceneState( scene, state );
+
+}

package/src/renderers/common/SampledTexture.js

@@ -2,30 +2,102 @@ import Binding from './Binding.js';
 
 let _id = 0;
 
+/**
+ * Represents a sampled texture binding type.
+ *
+ * @private
+ * @augments Binding
+ */
 class SampledTexture extends Binding {
 
+	/**
+	 * Constructs a new sampled texture.
+	 *
+	 * @param {string} name - The sampled texture's name.
+	 * @param {?Texture} texture - The texture this binding is referring to.
+	 */
 	constructor( name, texture ) {
 
 		super( name );
 
+		/**
+		 * This identifier.
+		 *
+		 * @type {number}
+		 */
 		this.id = _id ++;
 
+		/**
+		 * The texture this binding is referring to.
+		 *
+		 * @type {?Texture}
+		 */
 		this.texture = texture;
+
+		/**
+		 * The binding's version.
+		 *
+		 * @type {number}
+		 */
 		this.version = texture ? texture.version : 0;
+
+		/**
+		 * Whether the texture is a storage texture or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.store = false;
 
+		/**
+		 * The binding's generation which is an additional version
+		 * qualifier.
+		 *
+		 * @type {?number}
+		 * @default null
+		 */
+		this.generation = null;
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSampledTexture = true;
 
 	}
 
-	get needsBindingsUpdate() {
+	/**
+	 * Returns `true` whether this binding requires an update for the
+	 * given generation.
+	 *
+	 * @param {number} generation - The generation.
+	 * @return {boolean} Whether an update is required or not.
+	 */
+	needsBindingsUpdate( generation ) {
 
-		const { texture, version } = this;
+		const { texture } = this;
+
+		if ( generation !== this.generation ) {
+
+			this.generation = generation;
+
+			return true;
+
+		}
 
-		return texture.isVideoTexture ? true : version !== texture.version; // @TODO: version === 0 && texture.version > 0 ( add it just to External Textures like PNG,JPG )
+		return texture.isVideoTexture;
 
 	}
 
+	/**
+	 * Updates the binding.
+	 *
+	 * @return {boolean} Whether the texture has been updated and must be
+	 * uploaded to the GPU.
+	 */
 	update() {
 
 		const { texture, version } = this;
@@ -44,36 +116,93 @@ class SampledTexture extends Binding {
 
 }
 
+/**
+ * Represents a sampled array texture binding type.
+ *
+ * @private
+ * @augments SampledTexture
+ */
 class SampledArrayTexture extends SampledTexture {
 
+	/**
+	 * Constructs a new sampled array texture.
+	 *
+	 * @param {string} name - The sampled array texture's name.
+	 * @param {?(DataArrayTexture|CompressedArrayTexture)} texture - The texture this binding is referring to.
+	 */
 	constructor( name, texture ) {
 
 		super( name, texture );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSampledArrayTexture = true;
 
 	}
 
 }
 
+/**
+ * Represents a sampled 3D texture binding type.
+ *
+ * @private
+ * @augments SampledTexture
+ */
 class Sampled3DTexture extends SampledTexture {
 
+	/**
+	 * Constructs a new sampled 3D texture.
+	 *
+	 * @param {string} name - The sampled 3D texture's name.
+	 * @param {?Data3DTexture} texture - The texture this binding is referring to.
+	 */
 	constructor( name, texture ) {
 
 		super( name, texture );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSampled3DTexture = true;
 
 	}
 
 }
 
+/**
+ * Represents a sampled cube texture binding type.
+ *
+ * @private
+ * @augments SampledTexture
+ */
 class SampledCubeTexture extends SampledTexture {
 
+	/**
+	 * Constructs a new sampled cube texture.
+	 *
+	 * @param {string} name - The sampled cube texture's name.
+	 * @param {?(CubeTexture|CompressedCubeTexture)} texture - The texture this binding is referring to.
+	 */
 	constructor( name, texture ) {
 
 		super( name, texture );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSampledCubeTexture = true;
 
 	}

package/src/renderers/common/Sampler.js

@@ -1,14 +1,44 @@
 import Binding from './Binding.js';
 
+/**
+ * Represents a sampler binding type.
+ *
+ * @private
+ * @augments Binding
+ */
 class Sampler extends Binding {
 
+	/**
+	 * Constructs a new sampler.
+	 *
+	 * @param {string} name - The samplers's name.
+	 * @param {?Texture} texture - The texture this binding is referring to.
+	 */
 	constructor( name, texture ) {
 
 		super( name );
 
+		/**
+		 * The texture the sampler is referring to.
+		 *
+		 * @type {?Texture}
+		 */
 		this.texture = texture;
+
+		/**
+		 * The binding's version.
+		 *
+		 * @type {number}
+		 */
 		this.version = texture ? texture.version : 0;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSampler = true;
 
 	}

package/src/renderers/common/StorageBuffer.js

@@ -1,13 +1,37 @@
 import Buffer from './Buffer.js';
 
+/**
+ * Represents a storage buffer binding type.
+ *
+ * @private
+ * @augments Buffer
+ */
 class StorageBuffer extends Buffer {
 
+	/**
+	 * Constructs a new uniform buffer.
+	 *
+	 * @param {string} name - The buffer's name.
+	 * @param {BufferAttribute} attribute - The buffer attribute.
+	 */
 	constructor( name, attribute ) {
 
 		super( name, attribute ? attribute.array : null );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {BufferAttribute}
+		 */
 		this.attribute = attribute;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isStorageBuffer = true;
 
 	}

package/src/renderers/common/StorageBufferAttribute.js

@@ -1,13 +1,42 @@
 import { BufferAttribute } from '../../core/BufferAttribute.js';
 
+/**
+ * This special type of buffer attribute is intended for compute shaders.
+ * In earlier three.js versions it was only possible to update attribute data
+ * on the CPU via JavaScript and then upload the data to the GPU. With the
+ * new material system and renderer it is now possible to use compute shaders
+ * to compute the data for an attribute more efficiently on the GPU.
+ *
+ * The idea is to create an instance of this class and provide it as an input
+ * to {@link StorageBufferNode}.
+ *
+ * Note: This type of buffer attribute can only be used with `WebGPURenderer`.
+ *
+ * @augments BufferAttribute
+ */
 class StorageBufferAttribute extends BufferAttribute {
 
-	constructor( array, itemSize, typeClass = Float32Array ) {
+	/**
+	 * Constructs a new storage buffer attribute.
+	 *
+	 * @param {number|TypedArray} count - The item count. It is also valid to pass a typed array as an argument.
+	 * The subsequent parameters are then obsolete.
+	 * @param {number} itemSize - The item size.
+	 * @param {TypedArray.constructor} [typeClass=Float32Array] - A typed array constructor.
+	 */
+	constructor( count, itemSize, typeClass = Float32Array ) {
 
-		if ( ArrayBuffer.isView( array ) === false ) array = new typeClass( array * itemSize );
+		const array = ArrayBuffer.isView( count ) ? count : new typeClass( count * itemSize );
 
 		super( array, itemSize );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isStorageBufferAttribute = true;
 
 	}

package/src/renderers/common/StorageInstancedBufferAttribute.js

@@ -1,13 +1,42 @@
 import { InstancedBufferAttribute } from '../../core/InstancedBufferAttribute.js';
 
+/**
+ * This special type of instanced buffer attribute is intended for compute shaders.
+ * In earlier three.js versions it was only possible to update attribute data
+ * on the CPU via JavaScript and then upload the data to the GPU. With the
+ * new material system and renderer it is now possible to use compute shaders
+ * to compute the data for an attribute more efficiently on the GPU.
+ *
+ * The idea is to create an instance of this class and provide it as an input
+ * to {@link StorageBufferNode}.
+ *
+ * Note: This type of buffer attribute can only be used with `WebGPURenderer`.
+ *
+ * @augments InstancedBufferAttribute
+ */
 class StorageInstancedBufferAttribute extends InstancedBufferAttribute {
 
-	constructor( array, itemSize, typeClass = Float32Array ) {
+	/**
+	 * Constructs a new storage instanced buffer attribute.
+	 *
+	 * @param {number|TypedArray} count - The item count. It is also valid to pass a typed array as an argument.
+	 * The subsequent parameters are then obsolete.
+	 * @param {number} itemSize - The item size.
+	 * @param {TypedArray.constructor} [typeClass=Float32Array] - A typed array constructor.
+	 */
+	constructor( count, itemSize, typeClass = Float32Array ) {
 
-		if ( ArrayBuffer.isView( array ) === false ) array = new typeClass( array * itemSize );
+		const array = ArrayBuffer.isView( count ) ? count : new typeClass( count * itemSize );
 
 		super( array, itemSize );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isStorageInstancedBufferAttribute = true;
 
 	}

package/src/renderers/common/StorageTexture.js

@@ -1,17 +1,55 @@
 import { Texture } from '../../textures/Texture.js';
 import { LinearFilter } from '../../constants.js';
 
+/**
+ * This special type of texture is intended for compute shaders.
+ * It can be used to compute the data of a texture with a compute shader.
+ *
+ * Note: This type of texture can only be used with `WebGPURenderer`
+ * and a WebGPU backend.
+ *
+ * @augments Texture
+ */
 class StorageTexture extends Texture {
 
+	/**
+	 * Constructs a new storage texture.
+	 *
+	 * @param {number} [width=1] - The storage texture's width.
+	 * @param {number} [height=1] - The storage texture's height.
+	 */
 	constructor( width = 1, height = 1 ) {
 
 		super();
 
+		/**
+		 * The image object which just represents the texture's dimension.
+		 *
+		 * @type {{width: number, height: number}}
+		 */
 		this.image = { width, height };
 
+		/**
+		 * The default `magFilter` for storage textures is `THREE.LinearFilter`.
+		 *
+		 * @type {number}
+		 */
 		this.magFilter = LinearFilter;
+
+		/**
+		 * The default `minFilter` for storage textures is `THREE.LinearFilter`.
+		 *
+		 * @type {number}
+		 */
 		this.minFilter = LinearFilter;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isStorageTexture = true;
 
 	}