super-three 0.170.1 → 0.172.0

package/src/nodes/utils/ViewportUtils.js

@@ -3,6 +3,19 @@ import { screenUV } from '../display/ScreenNode.js';
 import { viewportDepthTexture } from '../display/ViewportDepthTextureNode.js';
 import { linearDepth } from '../display/ViewportDepthNode.js';
 
+/** @module ViewportUtils **/
+
+/**
+ * A special version of a screen uv function that involves a depth comparison
+ * when computing the final uvs. The function mitigates visual errors when
+ * using viewport texture nodes for refraction purposes. Without this function
+ * objects in front of a refractive surface might appear on the refractive surface
+ * which is incorrect.
+ *
+ * @method
+ * @param {Node<vec2>?} uv - Optional uv coordinates. By default `screenUV` is used.
+ * @return {Node<vec2>} The update uv coordinates.
+ */
 export const viewportSafeUV = /*@__PURE__*/ Fn( ( [ uv = null ] ) => {
 
 	const depth = linearDepth();

package/src/objects/BatchedMesh.js

@@ -1,10 +1,9 @@
 import { BufferAttribute } from '../core/BufferAttribute.js';
 import { BufferGeometry } from '../core/BufferGeometry.js';
 import { DataTexture } from '../textures/DataTexture.js';
-import { FloatType, RedIntegerFormat, UnsignedIntType } from '../constants.js';
+import { FloatType, RedIntegerFormat, UnsignedIntType, RGBAFormat } from '../constants.js';
 import { Matrix4 } from '../math/Matrix4.js';
 import { Mesh } from './Mesh.js';
-import { RGBAFormat } from '../constants.js';
 import { ColorManagement } from '../math/ColorManagement.js';
 import { Box3 } from '../math/Box3.js';
 import { Sphere } from '../math/Sphere.js';

package/src/objects/ClippingGroup.js

@@ -1,15 +1,64 @@
 import { Group } from './Group.js';
 
+/**
+ * In earlier three.js versions, clipping was defined globally
+ * on the renderer or on material level. This special version of
+ * `THREE.Group` allows to encode the clipping state into the scene
+ * graph. Meaning if you create an instance of this group, all
+ * descendant 3D objects will be affected by the respective clipping
+ * planes.
+ *
+ * Note: `ClippingGroup` can only be used with `WebGPURenderer`.
+ *
+ * @augments Group
+ */
 class ClippingGroup extends Group {
 
+	/**
+	 * Constructs a new clipping group.
+	 */
 	constructor() {
 
 		super();
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isClippingGroup = true;
+
+		/**
+		 * An array with clipping planes.
+		 *
+		 * @type {Array<Plane>}
+		 */
 		this.clippingPlanes = [];
+
+		/**
+		 * Whether clipping should be enabled or not.
+		 *
+		 * @type {Boolean}
+		 * @default true
+		 */
 		this.enabled = true;
+
+		/**
+		 * Whether the intersection of the clipping planes is used to clip objects, rather than their union.
+		 *
+		 * @type {Boolean}
+		 * @default false
+		 */
 		this.clipIntersection = false;
+
+		/**
+		 * Whether shadows should be clipped or not.
+		 *
+		 * @type {Boolean}
+		 * @default false
+		 */
 		this.clipShadows = false;
 
 	}

package/src/renderers/WebGLRenderer.js

@@ -195,6 +195,9 @@ class WebGLRenderer {
 		let _clippingEnabled = false;
 		let _localClippingEnabled = false;
 
+		// transmission render target scale
+		this.transmissionResolutionScale = 1.0;
+
 		// camera matrices cache
 
 		const _currentProjectionMatrix = new Matrix4();
@@ -1283,7 +1286,7 @@ class WebGLRenderer {
 
 			//
 
-			if ( _currentRenderTarget !== null ) {
+			if ( _currentRenderTarget !== null && _currentActiveMipmapLevel === 0 ) {
 
 				// resolve multisample renderbuffers to a single-sample texture if necessary
 
@@ -1511,7 +1514,7 @@ class WebGLRenderer {
 			const transmissionRenderTarget = currentRenderState.state.transmissionRenderTarget[ camera.id ];
 
 			const activeViewport = camera.viewport || _currentViewport;
-			transmissionRenderTarget.setSize( activeViewport.z, activeViewport.w );
+			transmissionRenderTarget.setSize( activeViewport.z * _this.transmissionResolutionScale, activeViewport.w * _this.transmissionResolutionScale );
 
 			//
 
@@ -2329,6 +2332,7 @@ class WebGLRenderer {
 
 		};
 
+		const _scratchFrameBuffer = _gl.createFramebuffer();
 		this.setRenderTarget = function ( renderTarget, activeCubeFace = 0, activeMipmapLevel = 0 ) {
 
 			_currentRenderTarget = renderTarget;
@@ -2437,6 +2441,14 @@ class WebGLRenderer {
 
 			}
 
+			// Use a scratch frame buffer if rendering to a mip level to avoid depth buffers
+			// being bound that are different sizes.
+			if ( activeMipmapLevel !== 0 ) {
+
+				framebuffer = _scratchFrameBuffer;
+
+			}
+
 			const framebufferBound = state.bindFramebuffer( _gl.FRAMEBUFFER, framebuffer );
 
 			if ( framebufferBound && useDefaultFramebuffer ) {
@@ -2457,8 +2469,15 @@ class WebGLRenderer {
 			} else if ( isRenderTarget3D ) {
 
 				const textureProperties = properties.get( renderTarget.texture );
-				const layer = activeCubeFace || 0;
-				_gl.framebufferTextureLayer( _gl.FRAMEBUFFER, _gl.COLOR_ATTACHMENT0, textureProperties.__webglTexture, activeMipmapLevel || 0, layer );
+				const layer = activeCubeFace;
+				_gl.framebufferTextureLayer( _gl.FRAMEBUFFER, _gl.COLOR_ATTACHMENT0, textureProperties.__webglTexture, activeMipmapLevel, layer );
+
+			} else if ( renderTarget !== null && activeMipmapLevel !== 0 ) {
+
+				// Only bind the frame buffer if we are using a scratch frame buffer to render to a mipmap.
+				// If we rebind the texture when using a multi sample buffer then an error about inconsistent samples will be thrown.
+				const textureProperties = properties.get( renderTarget.texture );
+				_gl.framebufferTexture2D( _gl.FRAMEBUFFER, _gl.COLOR_ATTACHMENT0, _gl.TEXTURE_2D, textureProperties.__webglTexture, activeMipmapLevel );
 
 			}
 

package/src/renderers/common/Animation.js

@@ -1,16 +1,63 @@
+
+/**
+ * This module manages the internal animation loop of the renderer.
+ *
+ * @private
+ */
 class Animation {
 
+	/**
+	 * Constructs a new animation loop management component.
+	 *
+	 * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+	 * @param {Info} info - Renderer component for managing metrics and monitoring data.
+	 */
 	constructor( nodes, info ) {
 
+		/**
+		 * Renderer component for managing nodes related logic.
+		 *
+		 * @type {Nodes}
+		 */
 		this.nodes = nodes;
+
+		/**
+		 * Renderer component for managing metrics and monitoring data.
+		 *
+		 * @type {Info}
+		 */
 		this.info = info;
 
+		/**
+		 * A reference to the context from `requestAnimationFrame()` can
+		 * be called (usually `window`).
+		 *
+		 * @type {Window|XRSession}
+		 */
 		this._context = self;
+
+		/**
+		 * The user-defined animation loop.
+		 *
+		 * @type {Function?}
+		 * @default null
+		 */
 		this._animationLoop = null;
+
+		/**
+		 * The requestId whic is returned from the `requestAnimationFrame()` call.
+		 * Can be used to cancel the stop the animation loop.
+		 *
+		 * @type {Number?}
+		 * @default null
+		 */
 		this._requestId = null;
 
 	}
 
+	/**
+	 * Starts the internal animation loop.
+	 */
 	start() {
 
 		const update = ( time, frame ) => {
@@ -31,6 +78,9 @@ class Animation {
 
 	}
 
+	/**
+	 * Stops the internal animation loop.
+	 */
 	stop() {
 
 		this._context.cancelAnimationFrame( this._requestId );
@@ -39,18 +89,31 @@ class Animation {
 
 	}
 
+	/**
+	 * Defines the user-level animation loop.
+	 *
+	 * @param {Function} callback - The animation loop.
+	 */
 	setAnimationLoop( callback ) {
 
 		this._animationLoop = callback;
 
 	}
 
+	/**
+	 * Defines the context in which `requestAnimationFrame()` is executed.
+	 *
+	 * @param {Window|XRSession} context - The context to set.
+	 */
 	setContext( context ) {
 
 		this._context = context;
 
 	}
 
+	/**
+	 * Frees all internal resources and stops the animation loop.
+	 */
 	dispose() {
 
 		this.stop();

package/src/renderers/common/Attributes.js

@@ -3,16 +3,38 @@ import { AttributeType } from './Constants.js';
 
 import { DynamicDrawUsage } from '../../constants.js';
 
+/**
+ * This renderer module manages geometry attributes.
+ *
+ * @private
+ * @augments DataMap
+ */
 class Attributes extends DataMap {
 
+	/**
+	 * Constructs a new attribute management component.
+	 *
+	 * @param {Backend} backend - The renderer's backend.
+	 */
 	constructor( backend ) {
 
 		super();
 
+		/**
+		 * The renderer's backend.
+		 *
+		 * @type {Backend}
+		 */
 		this.backend = backend;
 
 	}
 
+	/**
+	 * Deletes the data for the given attribute.
+	 *
+	 * @param {BufferAttribute} attribute - The attribute.
+	 * @return {Object} The deleted attribute data.
+	 */
 	delete( attribute ) {
 
 		const attributeData = super.delete( attribute );
@@ -27,6 +49,13 @@ class Attributes extends DataMap {
 
 	}
 
+	/**
+	 * Updates the given attribute. This method creates attribute buffers
+	 * for new attributes and updates data for existing ones.
+	 *
+	 * @param {BufferAttribute} attribute - The attribute to update.
+	 * @param {Number} type - The attribute type.
+	 */
 	update( attribute, type ) {
 
 		const data = this.get( attribute );
@@ -69,6 +98,13 @@ class Attributes extends DataMap {
 
 	}
 
+	/**
+	 * Utility method for handling interleaved buffer attributes correctly.
+	 * To process them, their `InterleavedBuffer` is returned.
+	 *
+	 * @param {BufferAttribute} attribute - The attribute.
+	 * @return {BufferAttribute|InterleavedBuffer}
+	 */
 	_getBufferAttribute( attribute ) {
 
 		if ( attribute.isInterleavedBufferAttribute ) attribute = attribute.data;