super-three 0.175.0 → 0.177.0

package/examples/jsm/tsl/shadows/TileShadowNodeHelper.js

@@ -0,0 +1,212 @@
+import { Group, NodeMaterial, Mesh, PlaneGeometry, DoubleSide, CameraHelper } from 'three/webgpu';
+import { Fn, vec4, vec3, texture, uv, positionLocal, vec2, float, screenSize } from 'three/tsl';
+
+/**
+ * Helper class to manage and display debug visuals for TileShadowNode.
+ *
+ * @augments Group
+ * @three_import import { TileShadowNodeHelper } from 'three/addons/tsl/shadows/TileShadowNodeHelper.js';
+ */
+class TileShadowNodeHelper extends Group {
+
+	/**
+	 * @param {TileShadowNode} tileShadowNode The TileShadowNode instance to debug.
+	 */
+	constructor( tileShadowNode ) {
+
+		super();
+
+		if ( ! tileShadowNode ) {
+
+			throw new Error( 'TileShadowNode instance is required for TileShadowNodeHelper.' );
+
+		}
+
+		this.tileShadowNode = tileShadowNode;
+		this.config = tileShadowNode.config;
+		this.tiles = tileShadowNode.tiles;
+		this._debugMeshes = [];
+		this._shadowCamHelpers = [];
+
+		this.initialized = false;
+
+	}
+
+	/**
+	 * Initializes the debug displays (planes and camera helpers).
+	 * Should be called after TileShadowNode has initialized its lights and shadow nodes.
+	 */
+	init() {
+
+		if ( this.tileShadowNode._shadowNodes.length !== this.tiles.length ) {
+
+			console.error( 'Cannot initialize TileShadowNodeHelper: Shadow nodes not ready or mismatch count.' );
+			return;
+
+		}
+
+		const tilesX = this.config.tilesX;
+		const tilesY = this.config.tilesY;
+
+		// Clear previous helpers if any (e.g., during a re-init)
+		this.dispose();
+
+		// Create a display for each shadow map tile
+		for ( let i = 0; i < this.tiles.length; i ++ ) {
+
+			// Create display plane
+			const display = new Mesh( new PlaneGeometry( 1, 1 ), new NodeMaterial() );
+			display.renderOrder = 9999999; // Ensure they appear on top
+			display.material.transparent = true;
+			display.frustumCulled = false;
+			display.side = DoubleSide;
+			display.material.depthTest = false; // Disable depth testing
+			display.material.depthWrite = false; // Disable depth writing
+
+			const col = i % tilesX;
+			const row = Math.floor( i / tilesX );
+
+			// Vertex shader logic for positioning the debug quad
+			display.material.vertexNode = Fn( () => {
+
+				const aspectRatio = screenSize.x.div( screenSize.y );
+				const maxTiles = Math.max( tilesX, tilesY );
+				const displaySize = float( 0.8 / maxTiles ); // Size adapts to number of tiles
+				const margin = float( 0.01 );
+				const cornerOffset = float( 0.05 );
+
+				// Position tiles left-to-right, top-to-bottom
+				const xBase = float( - 1.0 ).add( cornerOffset ).add(
+					displaySize.div( 2 ).div( aspectRatio )
+				).add( float( col ).mul( displaySize.div( aspectRatio ).add( margin ) ) );
+
+				const yBase = float( 1.0 ).sub( cornerOffset ).sub(
+					displaySize.div( 2 )
+				).sub( float( row ).mul( displaySize.add( margin ) ) );
+
+				const scaledPos = vec2(
+					positionLocal.x.mul( displaySize.div( aspectRatio ) ),
+					positionLocal.y.mul( displaySize )
+				);
+
+				const finalPos = vec2(
+					scaledPos.x.add( xBase ),
+					scaledPos.y.add( yBase )
+				);
+
+				return vec4( finalPos.x, finalPos.y, 0.0, 1.0 );
+
+			} )();
+
+			display.material.outputNode = Fn( () => {
+
+				// Ensure shadowMap and depthTexture are available
+				if ( ! this.tileShadowNode.shadowMap || ! this.tileShadowNode.shadowMap.depthTexture ) {
+
+					return vec4( 1, 0, 1, 1 ); // Magenta error color
+
+				}
+
+				const sampledDepth = texture( this.tileShadowNode.shadowMap.depthTexture )
+					.sample( uv().flipY() )
+					.depth( float( i ) ) // Sample correct layer
+					.compare( 0.9 ); // Example comparison value
+
+				// Simple tint based on index for visual distinction
+				const r = float( 0.5 + ( i % 3 ) * 0.16 );
+				const g = float( 0.5 + ( i % 2 ) * 0.25 );
+				const b = float( 0.7 + ( i % 4 ) * 0.075 );
+
+				return vec4(
+					vec3( r, g, b )
+						.mul( sampledDepth )
+						.saturate()
+						.rgb,
+					1.0
+				);
+
+			} )();
+
+			this.add( display );
+			this._debugMeshes.push( display );
+
+			if ( this.tileShadowNode._shadowNodes[ i ] && this.tileShadowNode._shadowNodes[ i ].shadow ) {
+
+				const camHelper = new CameraHelper( this.tileShadowNode._shadowNodes[ i ].shadow.camera );
+				camHelper.fog = false;
+				this.add( camHelper );
+				this._shadowCamHelpers.push( camHelper );
+
+			} else {
+
+				console.warn( `TileShadowNodeHelper: Could not create CameraHelper for tile index ${i}. Shadow node or camera missing.` );
+				this._shadowCamHelpers.push( null );
+
+			}
+
+		}
+
+		this.initialized = true;
+
+	}
+
+	/**
+	 * Updates the debug visuals (specifically camera helpers).
+	 * Should be called within TileShadowNode's update method.
+	 */
+	update() {
+
+		if ( this.initialized === false ) {
+
+			this.init();
+
+		}
+
+		for ( const helper of this._shadowCamHelpers ) {
+
+			if ( helper ) {
+
+				helper.update(); // Update CameraHelper matrices
+				helper.updateMatrixWorld( true ); // Ensure world matrix is current
+
+			}
+
+		}
+
+	}
+
+	/**
+	 * Removes all debug objects (planes and helpers) from the scene.
+	 */
+	dispose() {
+
+		if ( this.scene ) {
+
+			for ( const mesh of this._debugMeshes ) {
+
+				mesh.geometry.dispose();
+				mesh.material.dispose();
+				this.scene.remove( mesh );
+
+			}
+
+			for ( const helper of this._shadowCamHelpers ) {
+
+				if ( helper ) {
+
+					this.scene.remove( helper );
+
+				}
+
+			}
+
+		}
+
+		this._debugMeshes = [];
+		this._shadowCamHelpers = [];
+
+	}
+
+}
+
+export { TileShadowNodeHelper };

package/examples/jsm/tsl/utils/Raymarching.js

@@ -1,6 +1,9 @@
 import { varying, vec4, modelWorldMatrixInverse, cameraPosition, positionGeometry, float, Fn, Loop, max, min, vec2, vec3 } from 'three/tsl';
 
-/** @module Raymarching */
+/**
+ * @module Raymarching
+ * @three_import import { RaymarchingBox } from 'three/addons/tsl/utils/Raymarching.js';
+ */
 
 const hitBox = /*@__PURE__*/ Fn( ( { orig, dir } ) => {
 
@@ -50,13 +53,13 @@ export const RaymarchingBox = ( steps, callback ) => {
 	bounds.assign( vec2( max( bounds.x, 0.0 ), bounds.y ) );
 
 	const inc = vec3( rayDir.abs().reciprocal() ).toVar();
-	const delta = float( min( inc.x, min( inc.y, inc.z ) ) ).toVar( 'rayDelta' ); // used 'rayDelta' name in loop
+	const delta = float( min( inc.x, min( inc.y, inc.z ) ) ).toVar();
 
 	delta.divAssign( float( steps ) );
 
 	const positionRay = vec3( vOrigin.add( bounds.x.mul( rayDir ) ) ).toVar();
 
-	Loop( { type: 'float', start: bounds.x, end: bounds.y, update: '+= rayDelta' }, () => {
+	Loop( { type: 'float', start: bounds.x, end: bounds.y, update: delta }, () => {
 
 		callback( { positionRay } );
 

package/examples/jsm/utils/BufferGeometryUtils.js

@@ -11,7 +11,10 @@ import {
 	Vector3,
 } from 'three';
 
-/** @module BufferGeometryUtils */
+/**
+ * @module BufferGeometryUtils
+ * @three_import import * as BufferGeometryUtils from 'three/addons/utils/BufferGeometryUtils.js';
+ */
 
 /**
  * Computes vertex tangents using the MikkTSpace algorithm. MikkTSpace generates the same tangents consistently,

package/examples/jsm/utils/CameraUtils.js

@@ -4,7 +4,10 @@ import {
 	Vector3
 } from 'three';
 
-/** @module CameraUtils */
+/**
+ * @module CameraUtils
+ * @three_import import * as CameraUtils from 'three/addons/utils/CameraUtils.js';
+ */
 
 const _va = /*@__PURE__*/ new Vector3(), // from pe to pa
 	_vb = /*@__PURE__*/ new Vector3(), // from pe to pb

package/examples/jsm/utils/GeometryCompressionUtils.js

@@ -5,7 +5,10 @@ import {
 	Vector3
 } from 'three';
 
-/** @module GeometryCompressionUtils */
+/**
+ * @module GeometryCompressionUtils
+ * @three_import import * as GeometryCompressionUtils from 'three/addons/utils/GeometryCompressionUtils.js';
+ */
 
 // Octahedron and Quantization encodings based on work by: https://github.com/tsherif/mesh-quantization-example
 

package/examples/jsm/utils/GeometryUtils.js

@@ -1,6 +1,9 @@
 import { Vector3 } from 'three';
 
-/** @module GeometryUtils */
+/**
+ * @module GeometryUtils
+ * @three_import import * as GeometryUtils from 'three/addons/utils/GeometryUtils.js';
+ */
 
 /**
  * Generates 2D-Coordinates along a Hilbert curve.

package/examples/jsm/utils/LDrawUtils.js

@@ -11,6 +11,8 @@ import { mergeGeometries } from './BufferGeometryUtils.js';
 
 /**
  * Utility class for LDraw models.
+ *
+ * @three_import import { LDrawUtils } from 'three/addons/utils/LDrawUtils.js';
  */
 class LDrawUtils {
 

package/examples/jsm/utils/SceneOptimizer.js

@@ -4,6 +4,8 @@ import * as THREE from 'three';
  * This class can be used to optimized scenes by converting
  * individual meshes into {@link BatchedMesh}. This component
  * is an experimental attempt to implement auto-batching in three.js.
+ *
+ * @three_import import { SceneOptimizer } from 'three/addons/utils/SceneOptimizer.js';
  */
 class SceneOptimizer {
 

package/examples/jsm/utils/SceneUtils.js

@@ -10,7 +10,10 @@ import {
 
 import { mergeGroups, deepCloneAttribute } from './BufferGeometryUtils.js';
 
-/** @module SceneUtils */
+/**
+ * @module SceneUtils
+ * @three_import import * as SceneUtils from 'three/addons/utils/SceneUtils.js';
+ */
 
 const _color = /*@__PURE__*/new Color();
 const _matrix = /*@__PURE__*/new Matrix4();

package/examples/jsm/utils/ShadowMapViewer.js

@@ -27,6 +27,8 @@ import { UnpackDepthRGBAShader } from '../shaders/UnpackDepthRGBAShader.js';
  * lightShadowMapViewer.size.height = SHADOW_MAP_HEIGHT / 4;
  * lightShadowMapViewer.update();
  * ```
+ *
+ * @three_import import { ShadowMapViewer } from 'three/addons/utils/ShadowMapViewer.js';
  */
 class ShadowMapViewer {
 

package/examples/jsm/utils/ShadowMapViewerGPU.js

@@ -27,6 +27,8 @@ import { texture } from 'three/tsl';
  * lightShadowMapViewer.size.height = SHADOW_MAP_HEIGHT / 4;
  * lightShadowMapViewer.update();
  * ```
+ *
+ * @three_import import { ShadowMapViewer } from 'three/addons/utils/ShadowMapViewerGPU.js';
  */
 class ShadowMapViewer {
 

package/examples/jsm/utils/SkeletonUtils.js

@@ -9,7 +9,10 @@ import {
 	VectorKeyframeTrack
 } from 'three';
 
-/** @module SkeletonUtils */
+/**
+ * @module SkeletonUtils
+ * @three_import import * as SkeletonUtils from 'three/addons/utils/SkeletonUtils.js';
+ */
 
 function getBoneName( bone, options ) {
 

package/examples/jsm/utils/SortUtils.js

@@ -1,5 +1,8 @@
 
-/** @module SortUtils */
+/**
+ * @module SortUtils
+ * @three_import import * as SortUtils from 'three/addons/utils/SortUtils.js';
+ */
 
 const POWER = 3;
 const BIT_MAX = 32;

package/examples/jsm/utils/UVsDebug.js

@@ -2,7 +2,10 @@ import {
 	Vector2
 } from 'three';
 
-/** @module UVsDebug */
+/**
+ * @module UVsDebug
+ * @three_import import { UVsDebug } from 'three/addons/utils/UVsDebug.js';
+ */
 
 /**
  * Function for "unwrapping" and debugging three.js geometries UV mapping.

package/examples/jsm/utils/WebGLTextureUtils.js

@@ -10,7 +10,10 @@ import {
 	SRGBColorSpace
 } from 'three';
 
-/** @module WebGLTextureUtils */
+/**
+ * @module WebGLTextureUtils
+ * @three_import import * as WebGLTextureUtils from 'three/addons/utils/WebGLTextureUtils.js';
+ */
 
 let _renderer;
 let fullscreenQuadGeometry;

package/examples/jsm/utils/WebGPUTextureUtils.js

@@ -6,7 +6,10 @@ import {
 } from 'three';
 import { texture, uv } from 'three/tsl';
 
-/** @module WebGPUTextureUtils */
+/**
+ * @module WebGPUTextureUtils
+ * @three_import import * as WebGPUTextureUtils from 'three/addons/utils/WebGPUTextureUtils.js';
+ */
 
 let _renderer;
 const _quadMesh = /*@__PURE__*/ new QuadMesh();

package/examples/jsm/utils/WorkerPool.js

@@ -1,5 +1,7 @@
 /**
  * A simple pool for managing Web Workers.
+ *
+ * @three_import import { WorkerPool } from 'three/addons/utils/WorkerPool.js';
  */
 export class WorkerPool {
 

package/examples/jsm/webxr/ARButton.js

@@ -8,6 +8,7 @@
  * ```
  *
  * @hideconstructor
+ * @three_import import { ARButton } from 'three/addons/webxr/ARButton.js';
  */
 class ARButton {
 

package/examples/jsm/webxr/OculusHandModel.js

@@ -8,6 +8,7 @@ const POINTING_JOINT = 'index-finger-tip';
  * Represents an Oculus hand model.
  *
  * @augments Object3D
+ * @three_import import { OculusHandModel } from 'three/addons/webxr/OculusHandModel.js';
  */
 class OculusHandModel extends Object3D {
 

package/examples/jsm/webxr/OculusHandPointerModel.js

@@ -23,6 +23,7 @@ const CURSOR_MAX_DISTANCE = 1.5;
  * Represents an Oculus hand pointer model.
  *
  * @augments Object3D
+ * @three_import import { OculusHandPointerModel } from 'three/addons/webxr/OculusHandPointerModel.js';
  */
 class OculusHandPointerModel extends Object3D {
 

package/examples/jsm/webxr/Text2D.js

@@ -1,6 +1,9 @@
 import { DoubleSide, Mesh, MeshBasicMaterial, PlaneGeometry, Texture } from 'three';
 
-/** @module Text2D */
+/**
+ * @module Text2D
+ * @three_import import * as Text2D from 'three/addons/webxr/Text2D.js';
+ */
 
 /**
  * A helper function for creating a simple plane mesh

package/examples/jsm/webxr/VRButton.js

@@ -8,6 +8,7 @@
  * ```
  *
  * @hideconstructor
+ * @three_import import { VRButton } from 'three/addons/webxr/VRButton.js';
  */
 class VRButton {
 

package/examples/jsm/webxr/XRButton.js

@@ -12,6 +12,7 @@
  * support this type of session, it uses an immersive VR session.
  *
  * @hideconstructor
+ * @three_import import { XRButton } from 'three/addons/webxr/XRButton.js';
  */
 class XRButton {
 

package/examples/jsm/webxr/XRControllerModelFactory.js

@@ -255,6 +255,8 @@ function addAssetSceneToControllerModel( controllerModel, scene ) {
  * controllerGrip.add( controllerModelFactory.createControllerModel( controllerGrip ) );
  * scene.add( controllerGrip );
  * ```
+ *
+ * @three_import import { XRControllerModelFactory } from 'three/addons/webxr/XRControllerModelFactory.js';
  */
 class XRControllerModelFactory {
 

package/examples/jsm/webxr/XREstimatedLight.js

@@ -138,6 +138,7 @@ class SessionLightProbe {
  * a XR session. It relies on the WebXR Lighting Estimation API.
  *
  * @augments Group
+ * @three_import import { XREstimatedLight } from 'three/addons/webxr/XREstimatedLight.js';
  */
 export class XREstimatedLight extends Group {
 

package/examples/jsm/webxr/XRHandMeshModel.js

@@ -6,6 +6,8 @@ const DEFAULT_HAND_PROFILE_PATH = 'https://cdn.jsdelivr.net/npm/@webxr-input-pro
  * Represents one of the hand model types {@link XRHandModelFactory} might produce
  * depending on the selected profile. `XRHandMeshModel` represents a hand with a
  * custom asset.
+ *
+ * @three_import import { XRHandMeshModel } from 'three/addons/webxr/XRHandMeshModel.js';
  */
 class XRHandMeshModel {
 

package/examples/jsm/webxr/XRHandModelFactory.js

@@ -90,6 +90,8 @@ class XRHandModel extends Object3D {
  * hand.add( handModelFactory.createHandModel( hand ) );
  * scene.add( hand );
  * ```
+ *
+ * @three_import import { XRHandModelFactory } from 'three/addons/webxr/XRHandModelFactory.js';
  */
 class XRHandModelFactory {
 

package/examples/jsm/webxr/XRHandPrimitiveModel.js

@@ -15,6 +15,8 @@ const _vector = new Vector3();
  * Represents one of the hand model types {@link XRHandModelFactory} might produce
  * depending on the selected profile. `XRHandPrimitiveModel` represents a hand
  * with sphere or box primitives according to the selected `primitive` option.
+ *
+ * @three_import import { XRHandPrimitiveModel } from 'three/addons/webxr/XRHandPrimitiveModel.js';
  */
 class XRHandPrimitiveModel {
 

package/examples/jsm/webxr/XRPlanes.js

@@ -17,6 +17,7 @@ import {
  * ```
  *
  * @augments Object3D
+ * @three_import import { XRPlanes } from 'three/addons/webxr/XRPlanes.js';
  */
 class XRPlanes extends Object3D {
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-three",
-  "version": "0.175.0",
+  "version": "0.177.0",
   "description": "JavaScript 3D library",
   "type": "module",
   "main": "./build/three.cjs",
@@ -48,8 +48,10 @@
     "build": "rollup -c utils/build/rollup.config.js",
     "build-module": "rollup -c utils/build/rollup.config.js --configOnlyModule",
     "build-docs": "jsdoc -c utils/docs/jsdoc.config.json",
-    "dev": "concurrently --names \"ROLLUP,HTTP\" -c \"bgBlue.bold,bgGreen.bold\" \"rollup -c utils/build/rollup.config.js -w -m inline\" \"servez -p 8080\"",
-    "dev-ssl": "concurrently --names \"ROLLUP,HTTPS\" -c \"bgBlue.bold,bgGreen.bold\" \"rollup -c utils/build/rollup.config.js -w -m inline\" \"servez -p 8080 --ssl\"",
+    "dev": "node utils/build/dev.js && servez -p 8080",
+    "dev-ssl": "node utils/build/dev.js && servez -p 8080 --ssl",
+    "preview": "concurrently --names \"ROLLUP,HTTP\" -c \"bgBlue.bold,bgGreen.bold\" \"rollup -c utils/build/rollup.config.js -w -m inline\" \"servez -p 8080\"",
+    "preview-ssl": "concurrently --names \"ROLLUP,HTTPS\" -c \"bgBlue.bold,bgGreen.bold\" \"rollup -c utils/build/rollup.config.js -w -m inline\" \"servez -p 8080 --ssl\"",
     "lint-core": "eslint src",
     "lint-addons": "eslint examples/jsm --ext .js --ignore-pattern libs --ignore-pattern ifc",
     "lint-examples": "eslint examples --ext .html",
@@ -112,7 +114,7 @@
     "qunit": "^2.19.4",
     "rollup": "^4.6.0",
     "rollup-plugin-filesize": "^10.0.0",
-    "rollup-plugin-visualizer": "^5.9.0",
+    "rollup-plugin-visualizer": "^6.0.0",
     "servez": "^2.2.4"
   },
   "overrides": {

package/src/Three.Core.js

@@ -88,7 +88,6 @@ export { AnimationClip } from './animation/AnimationClip.js';
 export { AnimationAction } from './animation/AnimationAction.js';
 export { RenderTarget } from './core/RenderTarget.js';
 export { RenderTarget3D } from './core/RenderTarget3D.js';
-export { RenderTargetArray } from './core/RenderTargetArray.js';
 export { Uniform } from './core/Uniform.js';
 export { UniformsGroup } from './core/UniformsGroup.js';
 export { InstancedBufferGeometry } from './core/InstancedBufferGeometry.js';
@@ -115,6 +114,7 @@ export { Spherical } from './math/Spherical.js';
 export { Cylindrical } from './math/Cylindrical.js';
 export { Plane } from './math/Plane.js';
 export { Frustum } from './math/Frustum.js';
+export { FrustumArray } from './math/FrustumArray.js';
 export { Sphere } from './math/Sphere.js';
 export { Ray } from './math/Ray.js';
 export { Matrix4 } from './math/Matrix4.js';