rayzee 8.0.0 → 8.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",
@@ -35,7 +35,7 @@
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
-    "three": ">=0.185.0"
+    "three": ">=0.186.0"
   },
   "optionalDependencies": {
     "oidn-web": ">=0.4.0",

package/src/PathTracerApp.js

@@ -2881,16 +2881,41 @@ export class PathTracerApp extends EventDispatcher {
 
 		const adapterLimits = adapter.limits;
 
+		// A limit that is NOT requested is granted at WebGPU's portable default, never at the
+		// adapter's maximum — on Apple Metal-3 that is 16 sampled textures of 48, 4 storage
+		// textures of 8, 256 workgroup invocations of 1024 and 256 array layers of 2048.
+		// Requesting exactly what the adapter reports can never fail, so a weaker GPU simply
+		// gets less and every consumer has to stay adaptive.
+		const requiredLimits = { maxColorAttachmentBytesPerSample: 128 };
+
+		for ( const key of [
+			'maxBufferSize',
+			'maxStorageBufferBindingSize',
+			'maxSampledTexturesPerShaderStage',
+			'maxStorageTexturesPerShaderStage',
+			'maxTextureArrayLayers',
+			'maxTextureDimension2D',
+			'maxComputeInvocationsPerWorkgroup',
+			'maxComputeWorkgroupStorageSize',
+			'maxComputeWorkgroupSizeX',
+			'maxComputeWorkgroupSizeY',
+			'maxComputeWorkgroupSizeZ',
+		] ) {
+
+			const value = adapterLimits[ key ];
+			if ( value !== undefined ) requiredLimits[ key ] = value;
+
+		}
+
+		// Shade binds exactly 10 and the kernels are written to that budget; asking for more
+		// buys nothing, and 10 is already this adapter's ceiling.
+		requiredLimits.maxStorageBuffersPerShaderStage = Math.min( adapterLimits.maxStorageBuffersPerShaderStage, 10 );
+
 		this.renderer = new WebGPURenderer( {
 			canvas: this.canvas,
 			alpha: true,
 			powerPreference: 'high-performance',
-			requiredLimits: {
-				maxBufferSize: adapterLimits.maxBufferSize,
-				maxStorageBufferBindingSize: adapterLimits.maxStorageBufferBindingSize,
-				maxColorAttachmentBytesPerSample: 128,
-				maxStorageBuffersPerShaderStage: Math.min( adapterLimits.maxStorageBuffersPerShaderStage, 10 ),
-			}
+			requiredLimits,
 		} );
 
 		await this.renderer.init();

package/src/Processor/GeometryExtractor.js

@@ -965,7 +965,9 @@ export class GeometryExtractor {
 	getTextureMatrix( texture ) {
 
 		if ( ! texture ) return new Matrix3().elements;
-		texture.updateMatrix();
+		// GLTFLoader writes `matrix` itself for a rotated KHR_texture_transform (glTF is
+		// T·R·S, three is T·S·R) and clears the flag; updateMatrix() ignores the flag.
+		if ( texture.matrixAutoUpdate ) texture.updateMatrix();
 		return texture.matrix.elements;
 
 	}

package/src/Processor/utils.js

@@ -1,10 +1,6 @@
 import { SphereGeometry, Mesh, MeshPhysicalMaterial, Group, Object3D, Color, Vector3, ShaderMaterial, Vector2, Matrix4, GLSL3 } from 'three';
-import { QuadMesh } from 'three/webgpu';
 import { EngineEvents } from '../EngineEvents.js';
 
-/** Every QuadMesh in the realm shares this one geometry (module-level in three). */
-const _sharedQuadGeometry = /*@__PURE__*/ new QuadMesh( null ).geometry;
-
 let _statusCallback = null;
 
 /**
@@ -103,17 +99,18 @@ export function distroyBuffers( { material, geometry, children } ) {
 /**
  * Disposes a renderer without leaking it.
  *
- * Three.js 0.184–0.185: `Renderer.dispose()` does not remove the 'resize' listener
+ * Three.js 0.184–0.186: `Renderer.dispose()` does not remove the 'resize' listener
  * it installs on `_canvasTarget`. The bound handler closes over the renderer,
  * pinning the entire WebGPU graph (Backend, Nodes, Bindings, Pipelines, GPUDevice,
  * every TSL node) alive indefinitely — confirmed via heap-snapshot retainer
- * analysis. See three/src/renderers/common/Renderer.js:292 (attach) and :2503
- * (dispose — missing removal).
+ * analysis. See `Renderer.js` (attach in the constructor, still absent from
+ * `dispose()` in r186). Re-check on every upgrade; drop this when upstream fixes it.
  *
  * Renderers constructed with an external `device` do not destroy it here; three
  * only destroys a device it created itself.
  *
  * @param {import('three/webgpu').WebGPURenderer} renderer
+ * @returns {?Promise<void>} Settles once the backend is torn down.
  */
 export function disposeRenderer( renderer ) {
 
@@ -125,20 +122,11 @@ export function disposeRenderer( renderer ) {
 
 	}
 
-	renderer.dispose();
+	// r186+ `dispose()` is async and settles once the backend is torn down; anything that
+	// measures memory straight afterwards has to await the returned promise.
+	const disposed = renderer.dispose();
 	renderer._canvasTarget = null;
-
-	// Three.js 0.185: `RenderObjects.dispose()` drops its chain maps without disposing the
-	// render objects, so each one leaves behind the 'dispose' listener it registered on its
-	// geometry. Full-screen passes render a QuadMesh, and every QuadMesh in the realm shares
-	// one module-level geometry — so that listener list grows by one entry per renderer and
-	// keeps RenderObject → RenderObjects → Bindings → Backend → GPUDevice reachable for the
-	// page's lifetime. The chain maps are WeakMaps, so this list is the only handle on them.
-	//
-	// Clearing it also drops entries belonging to live renderers, which is safe: the
-	// singleton geometry is never disposed, so none of these listeners can ever fire.
-	const quadDisposeListeners = _sharedQuadGeometry._listeners?.dispose;
-	if ( quadDisposeListeners ) quadDisposeListeners.length = 0;
+	return disposed;
 
 }
 

package/src/TSL/SortGlobalKernels.js

@@ -21,11 +21,10 @@ import {
 	Fn, uint,
 	If, Loop,
 	instanceIndex, localId,
-	workgroupBarrier,
+	workgroupBarrier, workgroupArray,
 	atomicAdd, atomicLoad, atomicStore,
 } from 'three/tsl';
 
-import { workgroupAtomicArray } from './patches.js';
 import { readHitMaterialIndex } from '../Processor/PackedRayBuffer.js';
 import { COUNTER } from '../Processor/QueueManager.js';
 
@@ -54,7 +53,7 @@ export function buildGlobalHistKernel( { hitBufferRO, activeIndicesReadRO, sortG
 
 		const tid = instanceIndex;
 		const lid = localId.x;
-		const local = workgroupAtomicArray( 'uint', bins );
+		const local = workgroupArray( 'uint', bins ).toAtomic();
 
 		If( lid.lessThan( uint( bins ) ), () => {
 
@@ -127,7 +126,7 @@ export function buildGlobalScatterKernel( { hitBufferRO, activeIndicesReadRO, so
 
 		const tid = instanceIndex;
 		const lid = localId.x;
-		const local = workgroupAtomicArray( 'uint', bins );
+		const local = workgroupArray( 'uint', bins ).toAtomic();
 
 		If( lid.lessThan( uint( bins ) ), () => {
 

package/src/TSL/patches.js

@@ -7,12 +7,15 @@
  * loop) and `initTimestampQuery` (enlarges the stats-gl timestamp query pool so
  * the wavefront tracer's high per-frame compute-pass count doesn't overflow it).
  *
+ * Also overrides `ContextNode.prototype.setup` to undo an r186 codegen regression
+ * (§4) — that one is temporary and goes away at r187.
+ *
  * Exports: `struct()` — drop-in replacement for TSL's `struct()` returning
  * a proxy factory that supports GLSL-style dot-notation field access — and
  * `gpuOnlyStorageAttribute()`, a storage attribute with no CPU backing array.
  */
 
-import { StorageInstancedBufferAttribute, WebGPUBackend } from 'three/webgpu';
+import { ContextNode, StorageInstancedBufferAttribute, WebGPUBackend } from 'three/webgpu';
 import { struct as _struct } from 'three/tsl';
 
 // ---------------------------------------------------------------------------
@@ -62,10 +65,6 @@ WebGPUBackend.prototype.createNodeBuilder = function ( object, renderer ) {
 		configurable: true,
 	} );
 
-	// Install the workgroup-atomic-array codegen patch (section 4) lazily off the
-	// first builder, so we don't need to import WGSLNodeBuilder directly.
-	_installScopedArrayAtomicPatch( builder );
-
 	return builder;
 
 };
@@ -351,87 +350,28 @@ export function struct( members, name = null ) {
 }
 
 // ---------------------------------------------------------------------------
-// 4. Workgroup-scoped atomic arrays — var<workgroup> array<atomic<T>, N>
+// 4. r186 ContextNode.setup regression — DELETE WHEN THE three DEP REACHES r187
 // ---------------------------------------------------------------------------
-// TSL's `workgroupArray(type, count)` emits `var<workgroup> name: array<T, N>`
-// (`WGSLNodeBuilder.getScopedArrays`, r185 ~line 1773) with a NON-atomic element
-// type, so `atomicAdd(arr.element(i), v)` fails WGSL validation. AtomicFunctionNode
-// is itself address-space-agnostic — it emits `atomicAdd(&name[i], v)`, valid for
-// BOTH storage and workgroup pointers — so the ONLY missing piece is the
-// declaration. This patch adds `workgroupAtomicArray()` (a `workgroupArray` tagged
-// atomic) and overrides `getScopedArrays` to wrap the element type in `atomic<…>`
-// for tagged arrays, enabling true on-chip workgroup-shared atomics (e.g. fast
-// per-workgroup histograms) instead of the slow global-storage-atomic fallback.
-// Access tagged arrays ONLY via atomic ops (atomicAdd/atomicLoad/atomicStore).
-
-import { workgroupArray } from 'three/tsl';
-
-const _WorkgroupInfoNode = workgroupArray( 'uint', 1 ).constructor;
-
-// Tag the node so the patched getScopedArrays emits an atomic element type. The
-// array's WGSL name is only known after generate() runs, so we mark the builder's
-// scopedArrays entry there (idempotent across analyze/generate passes).
-const _origWorkgroupGenerate = _WorkgroupInfoNode.prototype.generate;
-
-_WorkgroupInfoNode.prototype.generate = function ( builder ) {
+// r186 (#34251) made `ContextNode.setup()` return the node it had just built.
+// Returning it stores the child's output node in the context node's own
+// properties, so `Node.build()` then re-builds it generically OUTSIDE the
+// context. `Loop()` wraps its body in a context (`fnCall.context({ nodeLoop })`),
+// so every loop-heavy kernel is evaluated against the wrong one — measured on our
+// corpus as 63x energy on furnace-clearcoat, 5.8x on furnace-sheen and NaN in the
+// SSS random walk, all while the WGSL compiled without a single error.
+//
+// Upstream reverted it in #34531 (merged 2026-09-11, on dev, ships in r187); this
+// body is that revert verbatim, and is also what r185 shipped, so it stays correct
+// if the dep is rolled back. Verified: with it, all 27 quality scenes pass and the
+// numbers are identical to r185. Drop this section and the `ContextNode` import
+// once the dep is r187+.
 
-	const name = _origWorkgroupGenerate.call( this, builder );
-	if ( this.isAtomicArray === true ) {
+ContextNode.prototype.setup = function ( builder ) {
 
-		const entry = builder.scopedArrays && builder.scopedArrays.get( name );
-		if ( entry ) entry.isAtomic = true;
+	const previousContext = builder.addContext( this.value );
 
-	}
+	this.node.build( builder );
 
-	return name;
+	builder.setContext( previousContext );
 
 };
-
-/**
- * Like `workgroupArray(type, count)` but declares the workgroup buffer with an
- * atomic element type: `var<workgroup> name: array<atomic<type>, count>`.
- * Elements MUST be accessed only via atomic ops (atomicAdd/atomicLoad/atomicStore).
- *
- * @param {string} type - Element type (e.g. 'uint').
- * @param {number} count - Number of elements.
- * @returns {WorkgroupInfoNode} The tagged workgroup array node.
- */
-export function workgroupAtomicArray( type, count ) {
-
-	const node = workgroupArray( type, count );
-	node.isAtomicArray = true;
-	return node;
-
-}
-
-let _scopedArraysPatched = false;
-
-// Override getScopedArrays on the builder's prototype (compute-stage WGSL
-// assembly) to emit `atomic<T>` element types for tagged workgroup arrays.
-// Installed once, lazily, off the first node builder created.
-function _installScopedArrayAtomicPatch( builder ) {
-
-	if ( _scopedArraysPatched ) return;
-	const proto = Object.getPrototypeOf( builder );
-	if ( ! proto || typeof proto.getScopedArrays !== 'function' ) return;
-
-	proto.getScopedArrays = function ( shaderStage ) {
-
-		if ( shaderStage !== 'compute' ) return;
-
-		const snippets = [];
-		for ( const { name, scope, bufferType, bufferCount, isAtomic } of this.scopedArrays.values() ) {
-
-			const type = this.getType( bufferType );
-			const elementType = ( isAtomic === true ) ? `atomic< ${ type } >` : type;
-			snippets.push( `var<${ scope }> ${ name }: array< ${ elementType }, ${ bufferCount } >;` );
-
-		}
-
-		return snippets.join( '\n' );
-
-	};
-
-	_scopedArraysPatched = true;
-
-}