super-three 0.181.0 → 0.185.0

package/examples/jsm/helpers/LightProbeGridHelper.js

@@ -0,0 +1,221 @@
+import {
+	InstancedBufferAttribute,
+	InstancedMesh,
+	Matrix4,
+	ShaderMaterial,
+	SphereGeometry,
+	Vector3
+} from 'three';
+
+/**
+ * Visualizes an {@link LightProbeGrid} by rendering a sphere at each
+ * probe position, shaded with the probe's L2 spherical harmonics.
+ *
+ * Uses a single `InstancedMesh` draw call for all probes.
+ *
+ * ```js
+ * const helper = new LightProbeGridHelper( probes );
+ * scene.add( helper );
+ * ```
+ *
+ * @augments InstancedMesh
+ * @three_import import { LightProbeGridHelper } from 'three/addons/helpers/LightProbeGridHelper.js';
+ */
+class LightProbeGridHelper extends InstancedMesh {
+
+	/**
+	 * Constructs a new irradiance probe grid helper.
+	 *
+	 * @param {LightProbeGrid} probes - The probe grid to visualize.
+	 * @param {number} [sphereSize=0.12] - The radius of each probe sphere.
+	 */
+	constructor( probes, sphereSize = 0.12 ) {
+
+		const geometry = new SphereGeometry( sphereSize, 16, 16 );
+
+		const material = new ShaderMaterial( {
+
+			uniforms: {
+
+				probesSH: { value: null },
+				probesResolution: { value: new Vector3() },
+
+			},
+
+			vertexShader: /* glsl */`
+
+				attribute vec3 instanceUVW;
+
+				varying vec3 vWorldNormal;
+				varying vec3 vUVW;
+
+				void main() {
+
+					vUVW = instanceUVW;
+					vWorldNormal = normalize( mat3( modelMatrix ) * normal );
+					gl_Position = projectionMatrix * modelViewMatrix * instanceMatrix * vec4( position, 1.0 );
+
+				}
+
+			`,
+
+			fragmentShader: /* glsl */`
+
+				precision highp sampler3D;
+
+				uniform sampler3D probesSH;
+				uniform vec3 probesResolution;
+
+				varying vec3 vWorldNormal;
+				varying vec3 vUVW;
+
+				void main() {
+
+					// Atlas UV mapping — must match lightprobes_pars_fragment.glsl.js
+					float nz          = probesResolution.z;
+					float paddedSlices = nz + 2.0;
+					float atlasDepth  = 7.0 * paddedSlices;
+					float uvZBase     = vUVW.z * nz + 1.0;
+
+					vec4 s0 = texture( probesSH, vec3( vUVW.xy, ( uvZBase                       ) / atlasDepth ) );
+					vec4 s1 = texture( probesSH, vec3( vUVW.xy, ( uvZBase +       paddedSlices   ) / atlasDepth ) );
+					vec4 s2 = texture( probesSH, vec3( vUVW.xy, ( uvZBase + 2.0 * paddedSlices   ) / atlasDepth ) );
+					vec4 s3 = texture( probesSH, vec3( vUVW.xy, ( uvZBase + 3.0 * paddedSlices   ) / atlasDepth ) );
+					vec4 s4 = texture( probesSH, vec3( vUVW.xy, ( uvZBase + 4.0 * paddedSlices   ) / atlasDepth ) );
+					vec4 s5 = texture( probesSH, vec3( vUVW.xy, ( uvZBase + 5.0 * paddedSlices   ) / atlasDepth ) );
+					vec4 s6 = texture( probesSH, vec3( vUVW.xy, ( uvZBase + 6.0 * paddedSlices   ) / atlasDepth ) );
+
+					// Unpack 9 vec3 SH L2 coefficients
+
+					vec3 c0 = s0.xyz;
+					vec3 c1 = vec3( s0.w, s1.xy );
+					vec3 c2 = vec3( s1.zw, s2.x );
+					vec3 c3 = s2.yzw;
+					vec3 c4 = s3.xyz;
+					vec3 c5 = vec3( s3.w, s4.xy );
+					vec3 c6 = vec3( s4.zw, s5.x );
+					vec3 c7 = s5.yzw;
+					vec3 c8 = s6.xyz;
+
+					vec3 n = normalize( vWorldNormal );
+
+					float x = n.x, y = n.y, z = n.z;
+
+					// band 0
+					vec3 result = c0 * 0.886227;
+
+					// band 1,
+					result += c1 * 2.0 * 0.511664 * y;
+					result += c2 * 2.0 * 0.511664 * z;
+					result += c3 * 2.0 * 0.511664 * x;
+
+					// band 2,
+					result += c4 * 2.0 * 0.429043 * x * y;
+					result += c5 * 2.0 * 0.429043 * y * z;
+					result += c6 * ( 0.743125 * z * z - 0.247708 );
+					result += c7 * 2.0 * 0.429043 * x * z;
+					result += c8 * 0.429043 * ( x * x - y * y );
+
+					gl_FragColor = vec4( max( result, vec3( 0.0 ) ), 1.0 );
+
+					#include <tonemapping_fragment>
+					#include <colorspace_fragment>
+
+				}
+
+			`
+
+		} );
+
+		const res = probes.resolution;
+		const count = res.x * res.y * res.z;
+
+		super( geometry, material, count );
+
+		/**
+		 * The probe grid to visualize.
+		 *
+		 * @type {LightProbeGrid}
+		 */
+		this.probes = probes;
+
+		this.type = 'LightProbeGridHelper';
+
+		this.update();
+
+	}
+
+	/**
+	 * Rebuilds instance matrices and UVW attributes from the current probe grid.
+	 * Call this after changing `probes` or after re-baking.
+	 */
+	update() {
+
+		const probes = this.probes;
+		const res = probes.resolution;
+		const count = res.x * res.y * res.z;
+
+		// Resize instance matrix buffer if needed
+
+		if ( this.instanceMatrix.count !== count ) {
+
+			this.instanceMatrix = new InstancedBufferAttribute( new Float32Array( count * 16 ), 16 );
+
+		}
+
+		this.count = count;
+
+		const uvwArray = new Float32Array( count * 3 );
+		const matrix = new Matrix4();
+		const probePos = new Vector3();
+
+		let i = 0;
+
+		for ( let iz = 0; iz < res.z; iz ++ ) {
+
+			for ( let iy = 0; iy < res.y; iy ++ ) {
+
+				for ( let ix = 0; ix < res.x; ix ++ ) {
+
+					// Remap to texel centers (must match lightprobes_pars_fragment.glsl.js)
+					uvwArray[ i * 3 ] = ( ix + 0.5 ) / res.x;
+					uvwArray[ i * 3 + 1 ] = ( iy + 0.5 ) / res.y;
+					uvwArray[ i * 3 + 2 ] = ( iz + 0.5 ) / res.z;
+
+					probes.getProbePosition( ix, iy, iz, probePos );
+					matrix.makeTranslation( probePos.x, probePos.y, probePos.z );
+					this.setMatrixAt( i, matrix );
+
+					i ++;
+
+				}
+
+			}
+
+		}
+
+		this.instanceMatrix.needsUpdate = true;
+
+		this.geometry.setAttribute( 'instanceUVW', new InstancedBufferAttribute( uvwArray, 3 ) );
+
+		// Update texture uniforms
+
+		this.material.uniforms.probesSH.value = probes.texture;
+		this.material.uniforms.probesResolution.value.copy( probes.resolution );
+
+	}
+
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
+	dispose() {
+
+		this.geometry.dispose();
+		this.material.dispose();
+
+	}
+
+}
+
+export { LightProbeGridHelper };

package/examples/jsm/helpers/LightProbeHelper.js

@@ -58,11 +58,12 @@ class LightProbeHelper extends Mesh {
 
 				#define RECIPROCAL_PI 0.318309886
 
-				vec3 inverseTransformDirection( in vec3 normal, in mat4 matrix ) {
 
-					// matrix is assumed to be orthogonal
+				vec3 transformNormalByInverseViewMatrix( in vec3 normal, in mat4 viewMatrix ) {
 
-					return normalize( ( vec4( normal, 0.0 ) * matrix ).xyz );
+					// upper-left 3x3 of view matrix is assumed to be orthogonal
+
+					return normalize( ( vec4( normal, 0.0 ) * viewMatrix ).xyz );
 
 				}
 
@@ -101,7 +102,7 @@ class LightProbeHelper extends Mesh {
 
 					vec3 normal = normalize( vNormal );
 
-					vec3 worldNormal = inverseTransformDirection( normal, viewMatrix );
+					vec3 worldNormal = transformNormalByInverseViewMatrix( normal, viewMatrix );
 
 					vec3 irradiance = shGetIrradianceAt( worldNormal, sh );
 

package/examples/jsm/helpers/LightProbeHelperGPU.js

@@ -2,7 +2,7 @@ import {
 	Mesh,
 	NodeMaterial,
 	SphereGeometry
-} from 'three';
+} from 'three/webgpu';
 import { float, Fn, getShIrradianceAt, normalWorld, uniformArray, uniform, vec4 } from 'three/tsl';
 
 /**

package/examples/jsm/helpers/TextureHelperGPU.js

@@ -6,7 +6,7 @@ import {
 	PlaneGeometry,
 	DoubleSide,
 	Vector3,
-} from 'three';
+} from 'three/webgpu';
 import { texture as textureNode, cubeTexture, texture3D, float, vec4, attribute } from 'three/tsl';
 import { mergeGeometries } from '../utils/BufferGeometryUtils.js';
 

package/examples/jsm/helpers/ViewHelper.js

@@ -49,6 +49,14 @@ class ViewHelper extends Object3D {
 		 */
 		this.isViewHelper = true;
 
+		/**
+		 * The camera whose transformation is visualized. It can be reassigned at
+		 * any time to rebind the helper to a different camera.
+		 *
+		 * @type {Camera}
+		 */
+		this.camera = camera;
+
 		/**
 		 * Whether the helper is currently animating or not.
 		 *
@@ -65,6 +73,20 @@ class ViewHelper extends Object3D {
 		 */
 		this.center = new Vector3();
 
+		/**
+		 * Controls the position of the helper in the viewport.
+		 * Use `top`/`bottom` for vertical positioning and `left`/`right` for horizontal.
+		 * If `left` is `null`, `right` is used. If `top` is `null`, `bottom` is used.
+		 *
+		 * @type {{top: number|null, right: number, bottom: number, left: number|null}}
+		 */
+		this.location = {
+			top: null,
+			right: 0,
+			bottom: 0,
+			left: null
+		};
+
 		const color1 = new Color( '#ff4466' );
 		const color2 = new Color( '#88ff44' );
 		const color3 = new Color( '#4488ff' );
@@ -72,6 +94,8 @@ class ViewHelper extends Object3D {
 
 		const options = {};
 
+		const scope = this;
+
 		const interactiveObjects = [];
 		const raycaster = new Raycaster();
 		const mouse = new Vector2();
@@ -142,23 +166,46 @@ class ViewHelper extends Object3D {
 		const turnRate = 2 * Math.PI; // turn rate in angles per second
 
 		/**
-		 * Renders the helper in a separate view in the bottom-right corner
-		 * of the viewport.
+		 * Renders the helper in a separate view in the viewport.
+		 * Position is controlled by the `location` property.
 		 *
 		 * @param {WebGLRenderer|WebGPURenderer} renderer - The renderer.
 		 */
 		this.render = function ( renderer ) {
 
-			this.quaternion.copy( camera.quaternion ).invert();
+			this.quaternion.copy( this.camera.quaternion ).invert();
 			this.updateMatrixWorld();
 
 			point.set( 0, 0, 1 );
-			point.applyQuaternion( camera.quaternion );
+			point.applyQuaternion( this.camera.quaternion );
 
 			//
 
-			const x = domElement.offsetWidth - dim;
-			const y = renderer.isWebGPURenderer ? domElement.offsetHeight - dim : 0;
+			const location = this.location;
+
+			let x, y;
+
+			if ( location.left !== null ) {
+
+				x = location.left;
+
+			} else {
+
+				x = domElement.offsetWidth - dim - location.right;
+
+			}
+
+			if ( location.top !== null ) {
+
+				// Position from top
+				y = renderer.isWebGPURenderer ? location.top : domElement.offsetHeight - dim - location.top;
+
+			} else {
+
+				// Position from bottom
+				y = renderer.isWebGPURenderer ? domElement.offsetHeight - dim - location.bottom : location.bottom;
+
+			}
 
 			renderer.clearDepth();
 
@@ -191,10 +238,32 @@ class ViewHelper extends Object3D {
 			if ( this.animating === true ) return false;
 
 			const rect = domElement.getBoundingClientRect();
-			const offsetX = rect.left + ( domElement.offsetWidth - dim );
-			const offsetY = rect.top + ( domElement.offsetHeight - dim );
-			mouse.x = ( ( event.clientX - offsetX ) / ( rect.right - offsetX ) ) * 2 - 1;
-			mouse.y = - ( ( event.clientY - offsetY ) / ( rect.bottom - offsetY ) ) * 2 + 1;
+			const location = this.location;
+
+			let offsetX, offsetY;
+
+			if ( location.left !== null ) {
+
+				offsetX = rect.left + location.left;
+
+			} else {
+
+				offsetX = rect.left + domElement.offsetWidth - dim - location.right;
+
+			}
+
+			if ( location.top !== null ) {
+
+				offsetY = rect.top + location.top;
+
+			} else {
+
+				offsetY = rect.top + domElement.offsetHeight - dim - location.bottom;
+
+			}
+
+			mouse.x = ( ( event.clientX - offsetX ) / dim ) * 2 - 1;
+			mouse.y = - ( ( event.clientY - offsetY ) / dim ) * 2 + 1;
 
 			raycaster.setFromCamera( mouse, orthoCamera );
 
@@ -266,11 +335,11 @@ class ViewHelper extends Object3D {
 			// animate position by doing a slerp and then scaling the position on the unit sphere
 
 			q1.rotateTowards( q2, step );
-			camera.position.set( 0, 0, 1 ).applyQuaternion( q1 ).multiplyScalar( radius ).add( this.center );
+			this.camera.position.set( 0, 0, 1 ).applyQuaternion( q1 ).multiplyScalar( radius ).add( this.center );
 
 			// animate orientation
 
-			camera.quaternion.rotateTowards( targetQuaternion, step );
+			this.camera.quaternion.rotateTowards( targetQuaternion, step );
 
 			if ( q1.angleTo( q2 ) === 0 ) {
 
@@ -349,12 +418,12 @@ class ViewHelper extends Object3D {
 
 			//
 
-			radius = camera.position.distanceTo( focusPoint );
+			radius = scope.camera.position.distanceTo( focusPoint );
 			targetPosition.multiplyScalar( radius ).add( focusPoint );
 
 			dummy.position.copy( focusPoint );
 
-			dummy.lookAt( camera.position );
+			dummy.lookAt( scope.camera.position );
 			q1.copy( dummy.quaternion );
 
 			dummy.lookAt( targetPosition );

package/examples/jsm/inspector/Extension.js

@@ -0,0 +1,13 @@
+import { Tab } from 'three/addons/inspector/ui/Tab.js';
+
+export class Extension extends Tab {
+
+	constructor( name, options = {} ) {
+
+		super( name, options );
+
+		this.isExtension = true;
+
+	}
+
+}