rayzee 6.4.0 → 7.0.0

package/src/Processor/SceneProcessor.js

@@ -297,6 +297,7 @@ export class SceneProcessor {
 			// Store other extracted data
 			this.materials = extractedData.materials;
 			this.materialCount = this.materials.length; // Store material count for feature scanning
+			this.materialTriangleCounts = extractedData.materialTriangleCounts; // Per-material tri count for sort-bin remap
 			this.meshes = extractedData.meshes;
 			this.meshTriangleRanges = extractedData.meshTriangleRanges; // Per-mesh { start, count } for TLAS/BLAS
 			this.maps = extractedData.maps;

package/src/Processor/ShaderBuilder.js

@@ -1,110 +1,29 @@
 /**
- * ShaderBuilder.js
- * Owns TSL shader graph construction and compute node management
- * for the path tracing pipeline.
+ * ShaderBuilder.js — shared scene texture-node factory for the path tracer.
  *
- * "Copy approach": Single compute node writes to 3 write-only StorageTextures.
- * Previous-frame reads use texture() sampling from a MRT RenderTarget
- * (populated by copyTextureToTexture after each dispatch).
- *
- * Texture nodes are created once and updated in-place via .value mutation
- * to preserve compiled shader graph references.
+ * Creates the texture/storage nodes the wavefront kernels read (environment, material map
+ * arrays, previous-frame MRT, adaptive-sampling, gobo/IES) and configures the module-level
+ * shadow/alpha/gobo/IES shader state. Nodes are created once and updated in-place via
+ * .value mutation to preserve compiled shader-graph references.
  */
 
-import { Fn, texture, vec2, float, int, uniform, If,
-	localId, workgroupId } from 'three/tsl';
-import { TextureNode } from 'three/webgpu';
+import { texture } from 'three/tsl';
 import { LinearFilter, DataArrayTexture } from 'three';
-import { pathTracerMain } from '../TSL/PathTracer.js';
 import { setShadowAlbedoMaps, setAlphaShadowsUniform } from '../TSL/LightsDirect.js';
 import { setGoboMapsTexture, setIESProfilesTexture } from '../TSL/LightsCore.js';
-import { BuildTimer } from './BuildTimer.js';
-
-const WG_SIZE = 8;
 
 export class ShaderBuilder {
 
 	constructor() {
 
-		// Single compute node (no dual ping-pong — copy approach)
-		this.computeNode = null;
-
 		// Previous-frame texture nodes (sample from MRT RenderTarget)
 		this.prevColorTexNode = null;
 		this.prevNormalDepthTexNode = null;
 		this.prevAlbedoTexNode = null;
 
-		// Adaptive sampling texture (updated per-frame from context)
-		this.adaptiveSamplingTexNode = null;
-
-		// Tile offset uniforms — pixel origin of the active tile region
-		// Dispatch covers only tile-sized workgroups; offset maps them to image space
-		this.tileOffsetX = uniform( 0, 'int' );
-		this.tileOffsetY = uniform( 0, 'int' );
-
-		// Render dimensions for edge-workgroup bounds checking
-		this.renderWidth = uniform( 1920, 'int' );
-		this.renderHeight = uniform( 1080, 'int' );
-
-		// Dispatch dimensions
-		this._dispatchX = 0;
-		this._dispatchY = 0;
-
-		// Reused per-frame dispatchSize array — avoids GC pressure from
-		// allocating [x,y,z] on every setFullScreenDispatch/setTileDispatch call.
-		// WebGPUBackend only reads indices 0..2 of this array during compute dispatch.
-		this._dispatchSize = [ 0, 0, 1 ];
-
 		// Scene texture nodes cache (for in-place updates on model change)
 		this._sceneTextureNodes = null;
 
-		// Whether the GPU compute pipeline has been compiled (via a real dispatch).
-		// Reset on setupCompute() rebuilds and on dispose().
-		this._compiled = false;
-
-	}
-
-	/**
-	 * Creates the full compute shader graph from scratch.
-	 *
-	 * @param {Object} config
-	 * @param {Object} config.stage - PathTracer instance
-	 * @param {Object} config.storageTextures - StorageTexturePool
-	 */
-	setupCompute( config ) {
-
-		const { stage, storageTextures } = config;
-
-		const timer = new BuildTimer( 'setupCompute' );
-
-		timer.start( 'Create texture nodes' );
-		const textureNodes = this._createTextureNodes( stage, storageTextures );
-		timer.end( 'Create texture nodes' );
-
-		timer.start( 'Build compute node (TSL)' );
-
-		const width = storageTextures.renderWidth;
-		const height = storageTextures.renderHeight;
-		this._dispatchX = Math.ceil( width / WG_SIZE );
-		this._dispatchY = Math.ceil( height / WG_SIZE );
-
-		this.renderWidth.value = width;
-		this.renderHeight.value = height;
-
-		const writeTex = storageTextures.getWriteTextures();
-
-		this.computeNode = this._buildComputeNode(
-			stage, textureNodes,
-			writeTex.color, writeTex.normalDepth, writeTex.albedo
-		);
-
-		// New compute node → needs a fresh GPU pipeline compile
-		this._compiled = false;
-
-		timer.end( 'Build compute node (TSL)' );
-
-		timer.print();
-
 	}
 
 	updateSceneTextures( stage ) {
@@ -165,98 +84,10 @@ export class ShaderBuilder {
 
 	}
 
-	setSize( width, height ) {
-
-		this._dispatchX = Math.ceil( width / WG_SIZE );
-		this._dispatchY = Math.ceil( height / WG_SIZE );
-
-		if ( this.computeNode ) {
-
-			this._dispatchSize[ 0 ] = this._dispatchX;
-			this._dispatchSize[ 1 ] = this._dispatchY;
-			this.computeNode.dispatchSize = this._dispatchSize;
-
-		}
-
-		this.renderWidth.value = width;
-		this.renderHeight.value = height;
-
-		// Reset tile offset (full-screen)
-		this.tileOffsetX.value = 0;
-		this.tileOffsetY.value = 0;
-
-	}
-
-	/**
-	 * Set dispatch to cover only the active tile region.
-	 * Adjusts dispatch count and tile offset so threads map directly to tile pixels.
-	 * @param {number} offsetX - Tile origin X in pixels
-	 * @param {number} offsetY - Tile origin Y in pixels
-	 * @param {number} tileWidth - Tile width in pixels
-	 * @param {number} tileHeight - Tile height in pixels
-	 */
-	setTileDispatch( offsetX, offsetY, tileWidth, tileHeight ) {
-
-		this.tileOffsetX.value = offsetX;
-		this.tileOffsetY.value = offsetY;
-
-		const dispatchX = Math.ceil( tileWidth / WG_SIZE );
-		const dispatchY = Math.ceil( tileHeight / WG_SIZE );
-
-		if ( this.computeNode ) {
-
-			this._dispatchSize[ 0 ] = dispatchX;
-			this._dispatchSize[ 1 ] = dispatchY;
-			this.computeNode.dispatchSize = this._dispatchSize;
-
-		}
-
-	}
-
-	/**
-	 * Reset dispatch to full-screen (no tiling).
-	 */
-	setFullScreenDispatch() {
-
-		this.tileOffsetX.value = 0;
-		this.tileOffsetY.value = 0;
-
-		if ( this.computeNode ) {
-
-			this._dispatchSize[ 0 ] = this._dispatchX;
-			this._dispatchSize[ 1 ] = this._dispatchY;
-			this.computeNode.dispatchSize = this._dispatchSize;
-
-		}
-
-	}
-
-	/**
-	 * Front-load GPU compute pipeline creation via a single dispatch.
-	 *
-	 * Three.js WebGPU has no `createComputePipelineAsync` path — compute
-	 * pipelines always compile synchronously on first `renderer.compute(node)`.
-	 * Calling this at build time (while a "Compiling shaders…" status is
-	 * already visible) moves the stall off the first animate frame.
-	 *
-	 * The dispatch writes to ping-pong storage textures whose contents are
-	 * discarded by the subsequent `reset()` (frame counter back to 0 →
-	 * `hasPreviousAccumulated = 0` → prev textures are not read).
-	 *
-	 * @param {object} renderer - WebGPURenderer
-	 */
-	forceCompile( renderer ) {
-
-		if ( this._compiled || ! this.computeNode || ! renderer ) return;
-
-		this._compiled = true;
-		renderer.compute( this.computeNode );
-
-	}
-
-	// ===== PRIVATE =====
-
-	_createTextureNodes( stage, storageTextures ) {
+	// Creates the shared scene texture nodes (env, material maps, prev-frame, adaptive, gobo, IES)
+	// + configures the module-level shadow/alpha/gobo/IES shader state read by the wavefront kernels.
+	// Call from setupMaterial before the kernels are built.
+	createSceneTextureNodes( stage, storageTextures ) {
 
 		const triStorage = stage.triangleStorageNode;
 		const bvhStorage = stage.bvhStorageNode;
@@ -270,14 +101,6 @@ export class ShaderBuilder {
 
 		const envTex = texture( stage.environment.environmentTexture );
 
-		// Adaptive sampling texture
-		const adaptiveSamplingTex = new TextureNode();
-		this.adaptiveSamplingTexNode = adaptiveSamplingTex;
-
-		// Environment importance sampling CDF — packed storage buffer
-		// Layout: [marginal (envResolution.y floats) | conditional (envResolution.x * envResolution.y floats)]
-		const envCDFStorage = stage.environment.envCDFStorageNode;
-
 		// Previous-frame texture nodes — initialized from readTarget textures
 		const readTextures = storageTextures.getReadTextures();
 		this.prevColorTexNode = texture( readTextures.color );
@@ -319,7 +142,7 @@ export class ShaderBuilder {
 
 		const result = {
 			triStorage, bvhStorage, matStorage, lightBufferStorage,
-			envTex, adaptiveSamplingTex, envCDFStorage,
+			envTex,
 			albedoMapsTex, normalMapsTex, bumpMapsTex,
 			metalnessMapsTex, roughnessMapsTex, emissiveMapsTex, displacementMapsTex,
 			goboMapsTex, iesProfilesTex,
@@ -330,140 +153,12 @@ export class ShaderBuilder {
 
 	}
 
-	/**
-	 * Build a single compute node.
-	 * Previous-frame reads use texture() nodes bound to MRT RenderTarget textures.
-	 */
-	_buildComputeNode( stage, textureNodes,
-		writeColorTex, writeNDTex, writeAlbedoTex ) {
-
-		const {
-			triStorage, bvhStorage, matStorage, lightBufferStorage,
-			envTex, adaptiveSamplingTex, envCDFStorage,
-			albedoMapsTex, normalMapsTex, bumpMapsTex,
-			metalnessMapsTex, roughnessMapsTex, emissiveMapsTex, displacementMapsTex,
-		} = textureNodes;
-
-		const tileOffsetX = this.tileOffsetX;
-		const tileOffsetY = this.tileOffsetY;
-		const renderWidth = this.renderWidth;
-		const renderHeight = this.renderHeight;
-
-		const prevColorTexNode = this.prevColorTexNode;
-		const prevNormalDepthTexNode = this.prevNormalDepthTexNode;
-		const prevAlbedoTexNode = this.prevAlbedoTexNode;
-
-		const computeFn = Fn( () => {
-
-			// Map thread to image-space pixel via tile offset
-			const gx = tileOffsetX.add( int( workgroupId.x ).mul( WG_SIZE ) ).add( int( localId.x ) );
-			const gy = tileOffsetY.add( int( workgroupId.y ).mul( WG_SIZE ) ).add( int( localId.y ) );
-
-			// Bounds check only needed for edge workgroups that overshoot render dimensions
-			If( gx.lessThan( renderWidth ).and( gy.lessThan( renderHeight ) ), () => {
-
-				const pixelCoord = vec2( float( gx ).add( 0.5 ), float( gy ).add( 0.5 ) );
-
-				pathTracerMain( {
-					pixelCoord,
-					writeColorTex, writeNDTex, writeAlbedoTex,
-					// Previous-frame textures from MRT RenderTarget (sampled via texture())
-					prevAccumTexture: prevColorTexNode,
-					prevNormalDepthTexture: prevNormalDepthTexNode,
-					prevAlbedoTexture: prevAlbedoTexNode,
-					resolution: stage.resolution,
-					frame: stage.frame,
-					samplesPerPixel: stage.samplesPerPixel,
-					visMode: stage.visMode,
-					cameraWorldMatrix: stage.cameraWorldMatrix,
-					cameraProjectionMatrixInverse: stage.cameraProjectionMatrixInverse,
-					cameraViewMatrix: stage.cameraViewMatrix,
-					cameraProjectionMatrix: stage.cameraProjectionMatrix,
-					bvhBuffer: bvhStorage,
-					triangleBuffer: triStorage,
-					materialBuffer: matStorage,
-					albedoMaps: albedoMapsTex,
-					normalMaps: normalMapsTex,
-					bumpMaps: bumpMapsTex,
-					metalnessMaps: metalnessMapsTex,
-					roughnessMaps: roughnessMapsTex,
-					emissiveMaps: emissiveMapsTex,
-					displacementMaps: displacementMapsTex,
-					directionalLightsBuffer: stage.directionalLightsBufferNode,
-					numDirectionalLights: stage.numDirectionalLights,
-					areaLightsBuffer: stage.areaLightsBufferNode,
-					numAreaLights: stage.numAreaLights,
-					pointLightsBuffer: stage.pointLightsBufferNode,
-					numPointLights: stage.numPointLights,
-					spotLightsBuffer: stage.spotLightsBufferNode,
-					numSpotLights: stage.numSpotLights,
-					envTexture: envTex,
-					environmentIntensity: stage.environmentIntensity,
-					envMatrix: stage.environmentMatrix,
-					envCDFBuffer: envCDFStorage,
-					envTotalSum: stage.envTotalSum,
-					envCompensationDelta: stage.envCompensationDelta,
-					envResolution: stage.envResolution,
-					enableEnvironmentLight: stage.enableEnvironment,
-					useEnvMapIS: stage.useEnvMapIS,
-					groundProjectionEnabled: stage.groundProjectionEnabled,
-					groundProjectionRadius: stage.groundProjectionRadius,
-					groundProjectionHeight: stage.groundProjectionHeight,
-					maxBounceCount: stage.maxBounces,
-					transmissiveBounces: stage.transmissiveBounces,
-					showBackground: stage.showBackground,
-					transparentBackground: stage.transparentBackground,
-					backgroundIntensity: stage.backgroundIntensity,
-					fireflyThreshold: stage.fireflyThreshold,
-					globalIlluminationIntensity: stage.globalIlluminationIntensity,
-					enableEmissiveTriangleSampling: stage.enableEmissiveTriangleSampling,
-					emissiveTriangleBuffer: lightBufferStorage,
-					emissiveTriangleCount: stage.emissiveTriangleCount,
-					emissiveTotalPower: stage.emissiveTotalPower,
-					emissiveBoost: stage.emissiveBoost,
-					emissiveVec4Offset: stage.emissiveVec4Offset,
-					lightBVHBuffer: lightBufferStorage,
-					lightBVHNodeCount: stage.lightBVHNodeCount,
-					debugVisScale: stage.debugVisScale,
-					enableAccumulation: stage.enableAccumulation,
-					hasPreviousAccumulated: stage.hasPreviousAccumulated,
-					accumulationAlpha: stage.accumulationAlpha,
-					cameraIsMoving: stage.cameraIsMoving,
-					useAdaptiveSampling: stage.useAdaptiveSampling,
-					adaptiveSamplingTexture: adaptiveSamplingTex,
-					adaptiveSamplingMin: stage.adaptiveSamplingMin,
-					adaptiveSamplingMax: stage.adaptiveSamplingMax,
-					enableDOF: stage.enableDOF,
-					focalLength: stage.focalLength,
-					aperture: stage.aperture,
-					focusDistance: stage.focusDistance,
-					sceneScale: stage.sceneScale,
-					apertureScale: stage.apertureScale,
-					anamorphicRatio: stage.anamorphicRatio,
-				} );
-
-			} );
-
-		} );
-
-		return computeFn().compute(
-			[ this._dispatchX, this._dispatchY, 1 ],
-			[ WG_SIZE, WG_SIZE, 1 ]
-		);
-
-	}
-
 	dispose() {
 
-		this.computeNode?.dispose();
-
-		this.computeNode = null;
 		this.prevColorTexNode = null;
 		this.prevNormalDepthTexNode = null;
 		this.prevAlbedoTexNode = null;
-		this.adaptiveSamplingTexNode = null;
 		this._sceneTextureNodes = null;
-		this._compiled = false;
 
 	}
 

package/src/Processor/StorageTexturePool.js

@@ -13,11 +13,12 @@
  */
 
 import { StorageTexture, RenderTarget } from 'three/webgpu';
-import { RGBAFormat, FloatType, LinearFilter, NearestFilter } from 'three';
+import { RGBAFormat, FloatType, LinearFilter, NearestFilter, Box2, Vector2 } from 'three';
+import { MAX_STORAGE_TEXTURE_SIZE } from '../EngineDefaults.js';
 
-function createWriteStorageTex( width, height ) {
+function createWriteStorageTex() {
 
-	const tex = new StorageTexture( width, height );
+	const tex = new StorageTexture( MAX_STORAGE_TEXTURE_SIZE, MAX_STORAGE_TEXTURE_SIZE );
 	tex.type = FloatType;
 	tex.format = RGBAFormat;
 	tex.minFilter = LinearFilter;
@@ -44,6 +45,9 @@ export class StorageTexturePool {
 		this.renderWidth = 0;
 		this.renderHeight = 0;
 
+		// Reused srcRegion for copies out of the over-allocated StorageTextures.
+		this._srcRegion = new Box2( new Vector2( 0, 0 ), new Vector2( 0, 0 ) );
+
 		if ( width > 0 && height > 0 ) {
 
 			this.create( width, height );
@@ -59,10 +63,10 @@ export class StorageTexturePool {
 		this.renderWidth = width;
 		this.renderHeight = height;
 
-		// Write-only StorageTextures
-		this.writeColor = createWriteStorageTex( width, height );
-		this.writeNormalDepth = createWriteStorageTex( width, height );
-		this.writeAlbedo = createWriteStorageTex( width, height );
+		// Write-only StorageTextures allocated at max — never resized (see resize crash fix).
+		this.writeColor = createWriteStorageTex();
+		this.writeNormalDepth = createWriteStorageTex();
+		this.writeAlbedo = createWriteStorageTex();
 
 		// Readable MRT RenderTarget (3 color attachments, no depth/stencil)
 		this.readTarget = new RenderTarget( width, height, {
@@ -85,13 +89,22 @@ export class StorageTexturePool {
 
 	ensureSize( width, height ) {
 
-		if ( this.renderWidth !== width || this.renderHeight !== height || ! this.writeColor ) {
+		if ( ! this.writeColor ) {
 
 			this.create( width, height );
 			return true;
 
 		}
 
+		if ( this.renderWidth !== width || this.renderHeight !== height ) {
+
+			// Resize only the readTarget — never dispose/recreate the write StorageTextures
+			// (that destroys the texture the compute bind group holds → submit crash).
+			this.setSize( width, height );
+			return true;
+
+		}
+
 		return false;
 
 	}
@@ -131,9 +144,13 @@ export class StorageTexturePool {
 	 */
 	copyToReadTargets( renderer ) {
 
-		renderer.copyTextureToTexture( this.writeColor, this.readTarget.textures[ 0 ] );
-		renderer.copyTextureToTexture( this.writeNormalDepth, this.readTarget.textures[ 1 ] );
-		renderer.copyTextureToTexture( this.writeAlbedo, this.readTarget.textures[ 2 ] );
+		// Source write StorageTextures are over-allocated at the max size; the Box2 region
+		// restricts the copy to the active render size so source and destination extents match.
+		this._srcRegion.max.set( this.renderWidth, this.renderHeight );
+
+		renderer.copyTextureToTexture( this.writeColor, this.readTarget.textures[ 0 ], this._srcRegion );
+		renderer.copyTextureToTexture( this.writeNormalDepth, this.readTarget.textures[ 1 ], this._srcRegion );
+		renderer.copyTextureToTexture( this.writeAlbedo, this.readTarget.textures[ 2 ], this._srcRegion );
 
 	}
 
@@ -163,10 +180,7 @@ export class StorageTexturePool {
 		this.renderWidth = width;
 		this.renderHeight = height;
 
-		this.writeColor?.setSize( width, height );
-		this.writeNormalDepth?.setSize( width, height );
-		this.writeAlbedo?.setSize( width, height );
-
+		// Write StorageTextures stay at max allocation — never resized (see resize crash fix).
 		if ( this.readTarget ) {
 
 			this.readTarget.setSize( width, height );

package/src/Processor/TextureCreator.js

@@ -965,6 +965,12 @@ export class TextureCreator {
 				bumpMapMatrices[ 4 ], 		bumpMapMatrices[ 5 ],	 	bumpMapMatrices[ 6 ], 		1,
 				displacementMapMatrices[ 0 ], displacementMapMatrices[ 1 ], displacementMapMatrices[ 2 ], displacementMapMatrices[ 3 ],
 				displacementMapMatrices[ 4 ], displacementMapMatrices[ 5 ], displacementMapMatrices[ 6 ], 1,
+				// Slot 27: subsurface (subsurfaceColor.rgb, subsurface weight)
+				mat.subsurfaceColor?.r ?? 1,	mat.subsurfaceColor?.g ?? 1,	mat.subsurfaceColor?.b ?? 1,	mat.subsurface ?? 0,
+				// Slot 28: subsurface (subsurfaceRadius.rgb, subsurfaceRadiusScale)
+				mat.subsurfaceRadius?.[ 0 ] ?? 1, mat.subsurfaceRadius?.[ 1 ] ?? 0.2, mat.subsurfaceRadius?.[ 2 ] ?? 0.1, mat.subsurfaceRadiusScale ?? 1,
+				// Slot 29: subsurface (anisotropy g, reserved)
+				mat.subsurfaceAnisotropy ?? 0,	0,	0,	0,
 			];
 
 			data.set( materialData, stride );

package/src/Processor/VRAMTracker.js

@@ -0,0 +1,169 @@
+/**
+ * VRAMTracker.js — current/peak GPU memory accounting.
+ *
+ * Measures ACTUAL live bytes (attribute.array.byteLength, texture dims × format/type)
+ * rather than re-deriving allocation formulas, so it never drifts when strides,
+ * capacity rounding, or layouts change. Providers are thunks that read current state,
+ * so they survive reallocation (resize, scene/material/env reload). A per-pass WeakSet
+ * dedupes by resource identity, so overlapping registrations never double-count.
+ */
+
+import {
+	RGBAFormat, RGBFormat, RGFormat, RedFormat,
+	FloatType, HalfFloatType, UnsignedByteType, ByteType,
+	UnsignedShortType, ShortType, UnsignedIntType, IntType,
+} from 'three';
+
+const CHANNELS = { [ RGBAFormat ]: 4, [ RGBFormat ]: 3, [ RGFormat ]: 2, [ RedFormat ]: 1 };
+const TYPE_BYTES = {
+	[ FloatType ]: 4, [ HalfFloatType ]: 2,
+	[ UnsignedByteType ]: 1, [ ByteType ]: 1,
+	[ UnsignedShortType ]: 2, [ ShortType ]: 2,
+	[ UnsignedIntType ]: 4, [ IntType ]: 4,
+};
+
+function texelBytes( tex ) {
+
+	return ( CHANNELS[ tex.format ] ?? 4 ) * ( TYPE_BYTES[ tex.type ] ?? 4 );
+
+}
+
+/** Exact byte size of a storage/buffer attribute's backing typed array. */
+export function bufferBytes( attr ) {
+
+	return attr?.array?.byteLength || 0;
+
+}
+
+/** Estimated GPU byte size of a Texture/StorageTexture/DataArrayTexture/RenderTarget. */
+export function textureBytes( tex ) {
+
+	if ( ! tex ) return 0;
+
+	if ( tex.isRenderTarget ) {
+
+		const list = tex.textures?.length ? tex.textures : [ tex.texture ];
+		const w = tex.width || 0, h = tex.height || 0, d = tex.depth || 1;
+		let sum = 0;
+		for ( const t of list ) if ( t ) sum += w * h * d * texelBytes( t );
+		return sum;
+
+	}
+
+	const img = tex.image || {};
+	const w = img.width ?? tex.width ?? 0;
+	const h = img.height ?? tex.height ?? 0;
+	const d = img.depth ?? 1;
+	return w * h * d * texelBytes( tex );
+
+}
+
+export class VRAMTracker {
+
+	constructor() {
+
+		this._providers = [];
+		this.current = 0;
+		this.peak = 0;
+		this.byCategory = {};
+
+	}
+
+	/**
+	 * @param {string} category - grouping label in the report
+	 * @param {Function} fn - returns a resource or array of resources: buffer
+	 *   attributes (`.array`), textures/render targets (`.isTexture`/`.isRenderTarget`),
+	 *   or synthetic `{ bytes }` for sizes with no inspectable object. Return falsy to skip.
+	 */
+	register( category, fn ) {
+
+		this._providers.push( { category, fn } );
+
+	}
+
+	measure() {
+
+		const seen = new WeakSet();
+		const byCategory = {};
+		let total = 0;
+
+		for ( const { category, fn } of this._providers ) {
+
+			let resources;
+			try {
+
+				resources = fn();
+
+			} catch {
+
+				resources = null;
+
+			}
+
+			if ( ! resources ) continue;
+
+			let bytes = 0;
+			for ( const r of ( Array.isArray( resources ) ? resources : [ resources ] ) ) {
+
+				bytes += this._resourceBytes( r, seen );
+
+			}
+
+			byCategory[ category ] = ( byCategory[ category ] || 0 ) + bytes;
+			total += bytes;
+
+		}
+
+		this.byCategory = byCategory;
+		this.current = total;
+		if ( total > this.peak ) this.peak = total;
+
+		return { current: total, peak: this.peak, byCategory };
+
+	}
+
+	_resourceBytes( r, seen ) {
+
+		if ( ! r ) return 0;
+
+		// synthetic { bytes } (e.g. attributeArray-backed histograms)
+		if ( typeof r.bytes === 'number' && ! r.isTexture && ! r.isRenderTarget ) return r.bytes;
+
+		// buffer attribute — dedupe by backing array (rw/ro nodes share one buffer)
+		if ( r.array && r.array.byteLength != null ) {
+
+			if ( seen.has( r.array ) ) return 0;
+			seen.add( r.array );
+			return r.array.byteLength;
+
+		}
+
+		// texture / render target — dedupe by object identity
+		if ( r.isRenderTarget || r.isTexture ) {
+
+			if ( seen.has( r ) ) return 0;
+			seen.add( r );
+			return textureBytes( r );
+
+		}
+
+		return 0;
+
+	}
+
+	/** Drop the high-water mark to the current value (call when a new render begins). */
+	resetPeak() {
+
+		this.peak = this.current;
+
+	}
+
+	getReport() {
+
+		const mb = ( b ) => ( b / 1048576 ).toFixed( 1 );
+		const parts = Object.entries( this.byCategory ).map( ( [ k, v ] ) => `${k}=${mb( v )}` );
+		return `VRAM current=${mb( this.current )}MB peak=${mb( this.peak )}MB [${parts.join( ' ' )}]`;
+
+	}
+
+}