@plastic-software/three 0.167.3 → 0.174.0

package/src/renderers/common/RenderBundles.js

@@ -1,35 +1,64 @@
 import ChainMap from './ChainMap.js';
 import RenderBundle from './RenderBundle.js';
 
+const _chainKeys = [];
+
+/**
+ * This renderer module manages render bundles.
+ *
+ * @private
+ */
 class RenderBundles {
 
+	/**
+	 * Constructs a new render bundle management component.
+	 */
 	constructor() {
 
-		this.lists = new ChainMap();
+		/**
+		 * A chain map for maintaining the render bundles.
+		 *
+		 * @type {ChainMap}
+		 */
+		this.bundles = new ChainMap();
 
 	}
 
-	get( scene, camera ) {
+	/**
+	 * Returns a render bundle for the given bundle group and camera.
+	 *
+	 * @param {BundleGroup} bundleGroup - The bundle group.
+	 * @param {Camera} camera - The camera the bundle group is rendered with.
+	 * @return {RenderBundle} The render bundle.
+	 */
+	get( bundleGroup, camera ) {
+
+		const bundles = this.bundles;
 
-		const lists = this.lists;
-		const keys = [ scene, camera ];
+		_chainKeys[ 0 ] = bundleGroup;
+		_chainKeys[ 1 ] = camera;
 
-		let list = lists.get( keys );
+		let bundle = bundles.get( _chainKeys );
 
-		if ( list === undefined ) {
+		if ( bundle === undefined ) {
 
-			list = new RenderBundle( scene, camera );
-			lists.set( keys, list );
+			bundle = new RenderBundle( bundleGroup, camera );
+			bundles.set( _chainKeys, bundle );
 
 		}
 
-		return list;
+		_chainKeys.length = 0;
+
+		return bundle;
 
 	}
 
+	/**
+	 * Frees all internal resources.
+	 */
 	dispose() {
 
-		this.lists = new ChainMap();
+		this.bundles = new ChainMap();
 
 	}
 

package/src/renderers/common/RenderContext.js

@@ -1,43 +1,235 @@
 import { Vector4 } from '../../math/Vector4.js';
+import { hashArray } from '../../nodes/core/NodeUtils.js';
 
-let id = 0;
+let _id = 0;
 
+/**
+ * Any render or compute command is executed in a specific context that defines
+ * the state of the renderer and its backend. Typical examples for such context
+ * data are the current clear values or data from the active framebuffer. This
+ * module is used to represent these contexts as objects.
+ *
+ * @private
+ */
 class RenderContext {
 
+	/**
+	 * Constructs a new render context.
+	 */
 	constructor() {
 
-		this.id = id ++;
+		/**
+		 * The context's ID.
+		 *
+		 * @type {number}
+		 */
+		this.id = _id ++;
 
+		/**
+		 * Whether the current active framebuffer has a color attachment.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.color = true;
+
+		/**
+		 * Whether the color attachment should be cleared or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.clearColor = true;
+
+		/**
+		 * The clear color value.
+		 *
+		 * @type {Object}
+		 * @default true
+		 */
 		this.clearColorValue = { r: 0, g: 0, b: 0, a: 1 };
 
+		/**
+		 * Whether the current active framebuffer has a depth attachment.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.depth = true;
+
+		/**
+		 * Whether the depth attachment should be cleared or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.clearDepth = true;
+
+		/**
+		 * The clear depth value.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.clearDepthValue = 1;
 
+		/**
+		 * Whether the current active framebuffer has a stencil attachment.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.stencil = false;
+
+		/**
+		 * Whether the stencil attachment should be cleared or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.clearStencil = true;
+
+		/**
+		 * The clear stencil value.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.clearStencilValue = 1;
 
+		/**
+		 * By default the viewport encloses the entire framebuffer If a smaller
+		 * viewport is manually defined, this property is to `true` by the renderer.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.viewport = false;
+
+		/**
+		 * The viewport value. This value is in physical pixels meaning it incorporates
+		 * the renderer's pixel ratio. The viewport property of render targets or
+		 * the renderer is in logical pixels.
+		 *
+		 * @type {Vector4}
+		 */
 		this.viewportValue = new Vector4();
 
+		/**
+		 * When the scissor test is active and scissor rectangle smaller than the
+		 * framebuffers dimensions, this property is to `true` by the renderer.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.scissor = false;
+
+		/**
+		 * The scissor rectangle.
+		 *
+		 * @type {Vector4}
+		 */
 		this.scissorValue = new Vector4();
 
+		/**
+		 * The active render target.
+		 *
+		 * @type {?RenderTarget}
+		 * @default null
+		 */
+		this.renderTarget = null;
+
+		/**
+		 * The textures of the active render target.
+		 * `null` when no render target is set.
+		 *
+		 * @type {?Array<Texture>}
+		 * @default null
+		 */
 		this.textures = null;
+
+		/**
+		 * The depth texture of the active render target.
+		 * `null` when no render target is set.
+		 *
+		 * @type {?DepthTexture}
+		 * @default null
+		 */
 		this.depthTexture = null;
+
+		/**
+		 * The active cube face.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.activeCubeFace = 0;
+
+		/**
+		 * The active mipmap level.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
+		this.activeMipmapLevel = 0;
+
+		/**
+		 * The number of MSAA samples. This value is always `1` when
+		 * MSAA isn't used.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.sampleCount = 1;
 
+		/**
+		 * The active render target's width in physical pixels.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.width = 0;
+
+		/**
+		 * The active render target's height in physical pixels.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.height = 0;
 
+		/**
+		 * The occlusion query count.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
+		this.occlusionQueryCount = 0;
+
+		/**
+		 * The current clipping context.
+		 *
+		 * @type {?ClippingContext}
+		 * @default null
+		 */
+		this.clippingContext = null;
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isRenderContext = true;
 
 	}
 
+	/**
+	 * Returns the cache key of this render context.
+	 *
+	 * @return {number} The cache key.
+	 */
 	getCacheKey() {
 
 		return getCacheKey( this );
@@ -46,21 +238,27 @@ class RenderContext {
 
 }
 
+/**
+ * Computes a cache key for the given render context. This key
+ * should identify the render target state so it is possible to
+ * configure the correct attachments in the respective backend.
+ *
+ * @param {RenderContext} renderContext - The render context.
+ * @return {number} The cache key.
+ */
 export function getCacheKey( renderContext ) {
 
 	const { textures, activeCubeFace } = renderContext;
 
-	let key = '';
+	const values = [ activeCubeFace ];
 
 	for ( const texture of textures ) {
 
-		key += texture.id + ',';
+		values.push( texture.id );
 
 	}
 
-	key += activeCubeFace;
-
-	return key;
+	return hashArray( values );
 
 }
 

package/src/renderers/common/RenderContexts.js

@@ -1,17 +1,46 @@
 import ChainMap from './ChainMap.js';
 import RenderContext from './RenderContext.js';
-
+import { Scene } from '../../scenes/Scene.js';
+import { Camera } from '../../cameras/Camera.js';
+
+const _chainKeys = [];
+const _defaultScene = /*@__PURE__*/ new Scene();
+const _defaultCamera = /*@__PURE__*/ new Camera();
+
+/**
+ * This module manages the render contexts of the renderer.
+ *
+ * @private
+ */
 class RenderContexts {
 
+	/**
+	 * Constructs a new render context management component.
+	 */
 	constructor() {
 
+		/**
+		 * A dictionary that manages render contexts in chain maps
+		 * for each attachment state.
+		 *
+		 * @type {Object<string,ChainMap>}
+		 */
 		this.chainMaps = {};
 
 	}
 
+	/**
+	 * Returns a render context for the given scene, camera and render target.
+	 *
+	 * @param {Scene} scene - The scene.
+	 * @param {Camera} camera - The camera that is used to render the scene.
+	 * @param {?RenderTarget} [renderTarget=null] - The active render target.
+	 * @return {RenderContext} The render context.
+	 */
 	get( scene, camera, renderTarget = null ) {
 
-		const chainKey = [ scene, camera ];
+		_chainKeys[ 0 ] = scene;
+		_chainKeys[ 1 ] = camera;
 
 		let attachmentState;
 
@@ -28,30 +57,54 @@ class RenderContexts {
 
 		}
 
-		const chainMap = this.getChainMap( attachmentState );
+		const chainMap = this._getChainMap( attachmentState );
 
-		let renderState = chainMap.get( chainKey );
+		let renderState = chainMap.get( _chainKeys );
 
 		if ( renderState === undefined ) {
 
 			renderState = new RenderContext();
 
-			chainMap.set( chainKey, renderState );
+			chainMap.set( _chainKeys, renderState );
 
 		}
 
+		_chainKeys.length = 0;
+
 		if ( renderTarget !== null ) renderState.sampleCount = renderTarget.samples === 0 ? 1 : renderTarget.samples;
 
 		return renderState;
 
 	}
 
-	getChainMap( attachmentState ) {
+	/**
+	 * Returns a render context intended for clear operations.
+	 *
+	 * @param {?RenderTarget} [renderTarget=null] - The active render target.
+	 * @return {RenderContext} The render context.
+	 */
+	getForClear( renderTarget = null ) {
+
+		return this.get( _defaultScene, _defaultCamera, renderTarget );
+
+	}
+
+	/**
+	 * Returns a chain map for the given attachment state.
+	 *
+	 * @private
+	 * @param {string} attachmentState - The attachment state.
+	 * @return {ChainMap} The chain map.
+	 */
+	_getChainMap( attachmentState ) {
 
 		return this.chainMaps[ attachmentState ] || ( this.chainMaps[ attachmentState ] = new ChainMap() );
 
 	}
 
+	/**
+	 * Frees internal resources.
+	 */
 	dispose() {
 
 		this.chainMaps = {};