rayzee 6.5.0 → 7.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rayzee",
-  "version": "6.5.0",
+  "version": "7.1.0",
   "type": "module",
   "description": "Real-time WebGPU path tracing engine built on Three.js",
   "main": "dist/rayzee.umd.js",

package/src/EngineDefaults.js

@@ -58,6 +58,10 @@ export const ENGINE_DEFAULTS = {
 	afScreenPoint: { x: 0.5, y: 0.5 },
 	afSmoothingFactor: 0.15,
 
+	// Multi-sample pool: S=samplesPerPixel rays/pixel/frame, FinalWrite averages them; interactive-only (renderMode 0, ≤ cap), else S=1.
+	// Pixel cap (768²) bounds pool memory; covers the 512² default, excludes ≥768².
+	wavefrontMultiSampleMaxPixels: 589824,
+
 	enablePathTracer: true,
 	enableAccumulation: true,
 	pauseRendering: false,
@@ -70,14 +74,9 @@ export const ENGINE_DEFAULTS = {
 	enableEmissiveTriangleSampling: false,
 	emissiveBoost: 1.0,
 
-	adaptiveSampling: false,
-	adaptiveSamplingMin: 1,
-	adaptiveSamplingMax: 8,
-	adaptiveSamplingVarianceThreshold: 0.1,
 	temporalVarianceWeight: 0.6,
 	enableEarlyTermination: true,
 	earlyTerminationThreshold: 0.002,
-	showAdaptiveSamplingHelper: false,
 	performanceModeAdaptive: 'medium',
 
 	fireflyThreshold: 3.0,
@@ -85,8 +84,7 @@ export const ENGINE_DEFAULTS = {
 	renderTimeLimit: 30,
 	renderMode: 0,
 	enableAlphaShadows: false,
-	tiles: 3,
-	tilesHelper: false,
+	tilesHelper: true, // show OIDN denoise / AI upscale tile progress overlay
 	showLightHelper: false,
 
 	directionalLightIntensity: 0,
@@ -129,6 +127,9 @@ export const ENGINE_DEFAULTS = {
 	asvgfPhiDepth: 1.0,
 	asvgfVarianceBoost: 1.0,
 	asvgfMaxAccumFrames: 32,
+	asvgfGradientStrength: 0.0,
+	asvgfGradientSigmaScale: 2.0,
+	asvgfGradientNoiseFloor: 0.0,
 	asvgfDebugMode: 0,
 	asvgfQualityPreset: 'medium',
 	showAsvgfHeatmap: false,
@@ -152,6 +153,12 @@ export const ENGINE_DEFAULTS = {
 // only round-trip exactly when both sides agree.
 export const ALBEDO_EPS = 0.01;
 
+// Per-resolution compute StorageTextures are pre-allocated at this size and never
+// resized (works around three.js r184 StorageTexture-resize bugs — see TSL/patches
+// history). Render resolution must not exceed this on either axis; the engine warns
+// and ignores larger requests.
+export const MAX_STORAGE_TEXTURE_SIZE = 2048;
+
 export const ASVGF_QUALITY_PRESETS = {
 	// phiColor / phiDepth are RELATIVE tolerances (fractions). Bigger = more
 	// permissive. gradientStrength = 0 keeps the adaptive-α boost off; the
@@ -191,6 +198,17 @@ export const ASVGF_QUALITY_PRESETS = {
 	}
 };
 
+// Adaptive variants — same SVGF quality as the base preset plus the temporal-
+// gradient anti-lag enabled (gradientStrength > 0). The gradient measures real
+// change in units of noise σ (gradientSigmaScale), so a static scene reads ~0
+// and convergence is unaffected; only moving lights/anim/disocclusion drop
+// history. Mutating the exported object is fine (const binding, mutable object);
+// spreading lets each inherit its base. See ASVGF._buildGradientCompute.
+const ADAPTIVE_GRADIENT = { gradientSigmaScale: 2.5, gradientNoiseFloor: 0.05 };
+ASVGF_QUALITY_PRESETS.low_adaptive = { ...ASVGF_QUALITY_PRESETS.low, gradientStrength: 0.8, ...ADAPTIVE_GRADIENT };
+ASVGF_QUALITY_PRESETS.medium_adaptive = { ...ASVGF_QUALITY_PRESETS.medium, gradientStrength: 1.0, ...ADAPTIVE_GRADIENT };
+ASVGF_QUALITY_PRESETS.high_adaptive = { ...ASVGF_QUALITY_PRESETS.high, gradientStrength: 1.0, ...ADAPTIVE_GRADIENT };
+
 export const CAMERA_RANGES = {
 	fov: {
 		min: 10,
@@ -467,7 +485,7 @@ export const DEFAULT_TEXTURE_MATRIX = [ 0, 0, 1, 1, 0, 0, 0, 1 ];
 // 'production'  — high-sample, deep bounces, OIDN enabled, controls disabled.
 export const PRODUCTION_RENDER_CONFIG = {
 	maxSamples: 30, bounces: 20, transmissiveBounces: 8, maxSubsurfaceSteps: 64, samplesPerPixel: 1,
-	renderMode: 1, enableAlphaShadows: true, tiles: 3, tilesHelper: true,
+	renderMode: 1, enableAlphaShadows: true,
 	enableOIDN: true, oidnQuality: 'balance',
 	interactionModeEnabled: false,
 };
@@ -477,7 +495,6 @@ export const INTERACTIVE_RENDER_CONFIG = {
 	samplesPerPixel: ENGINE_DEFAULTS.samplesPerPixel, renderMode: ENGINE_DEFAULTS.renderMode, enableAlphaShadows: ENGINE_DEFAULTS.enableAlphaShadows,
 	transmissiveBounces: ENGINE_DEFAULTS.transmissiveBounces,
 	maxSubsurfaceSteps: ENGINE_DEFAULTS.maxSubsurfaceSteps,
-	tiles: ENGINE_DEFAULTS.tiles, tilesHelper: ENGINE_DEFAULTS.tilesHelper,
 	enableOIDN: false, oidnQuality: 'fast',
 	interactionModeEnabled: true,
 };

package/src/PathTracerApp.js

@@ -11,14 +11,13 @@ import { MotionVector } from './Stages/MotionVector.js';
 import { ASVGF } from './Stages/ASVGF.js';
 import { Variance } from './Stages/Variance.js';
 import { BilateralFilter } from './Stages/BilateralFilter.js';
-import { AdaptiveSampling } from './Stages/AdaptiveSampling.js';
 import { EdgeFilter } from './Stages/EdgeFilter.js';
 import { AutoExposure } from './Stages/AutoExposure.js';
 import { SSRC } from './Stages/SSRC.js';
 import { Compositor } from './Stages/Compositor.js';
 import { RenderPipeline } from './Pipeline/RenderPipeline.js';
 import { CompletionTracker } from './Pipeline/CompletionTracker.js';
-import { ENGINE_DEFAULTS as DEFAULT_STATE, PRODUCTION_RENDER_CONFIG, INTERACTIVE_RENDER_CONFIG } from './EngineDefaults.js';
+import { ENGINE_DEFAULTS as DEFAULT_STATE, PRODUCTION_RENDER_CONFIG, INTERACTIVE_RENDER_CONFIG, MAX_STORAGE_TEXTURE_SIZE } from './EngineDefaults.js';
 import { updateStats, updateLoading, resetLoading, setStatusCallback, getDisplaySamples, disposeObjectFromMemory } from './Processor/utils.js';
 import { BuildTimer } from './Processor/BuildTimer.js';
 import { InteractionManager } from './managers/InteractionManager.js';
@@ -310,7 +309,14 @@ export class PathTracerApp extends EventDispatcher {
 
 			}
 
-			updateStats( { timeElapsed: this.completion.timeElapsed, samples: getDisplaySamples( this.stages.pathTracer ) } );
+			this._ensureVRAMWiring();
+			const mem = this.stages.pathTracer?.vramTracker?.measure();
+			updateStats( {
+				timeElapsed: this.completion.timeElapsed,
+				samples: getDisplaySamples( this.stages.pathTracer ),
+				memoryUsed: mem?.current ?? 0,
+				memoryPeak: mem?.peak ?? 0,
+			} );
 
 			// Check time limit
 			if ( this.completion.isTimeLimitReached( this.settings.get( 'renderLimitMode' ), this.settings.get( 'renderTimeLimit' ) ) ) {
@@ -740,12 +746,9 @@ export class PathTracerApp extends EventDispatcher {
 		this.stages.pathTracer.setupMaterial();
 		timer.end( 'Material setup (TSL compile)' );
 
-		// Front-load GPU pipeline creation so the first animate frame is snappy:
-		//  - compute: Three.js has no async compute compile — one dispatch at
-		//    build time moves the stall to this loading moment.
-		//  - raster fallback: compileAsync yields to main thread (r184+).
+		// Front-load raster pipeline creation (compileAsync yields to main thread, r184+) so the first
+		// animate frame is snappy. Wavefront compute kernels compile lazily on their first dispatch.
 		timer.start( 'Pipeline precompile' );
-		this.stages.pathTracer.shaderBuilder.forceCompile( this.renderer );
 		try {
 
 			await this.renderer.compileAsync( this.meshScene, this.cameraManager.camera );
@@ -845,11 +848,31 @@ export class PathTracerApp extends EventDispatcher {
 	// Resize
 	// ═══════════════════════════════════════════════════════════════
 
+	/**
+	 * Guard against render resolutions the compute pipeline can't support.
+	 * Per-resolution StorageTextures are pre-allocated at MAX_STORAGE_TEXTURE_SIZE
+	 * and never resized, so a larger request would overflow them. Warn and skip.
+	 * @returns {boolean} true if the size is renderable
+	 */
+	_isRenderSizeSupported( width, height ) {
+
+		if ( width > MAX_STORAGE_TEXTURE_SIZE || height > MAX_STORAGE_TEXTURE_SIZE ) {
+
+			console.warn( `[Rayzee] Render resolution ${width}×${height} exceeds the ${MAX_STORAGE_TEXTURE_SIZE}px limit (compute storage textures are pre-allocated at ${MAX_STORAGE_TEXTURE_SIZE}px). Ignoring resize — use a resolution ≤ ${MAX_STORAGE_TEXTURE_SIZE}.` );
+			return false;
+
+		}
+
+		return true;
+
+	}
+
 	onResize() {
 
 		const width = this.canvas.clientWidth;
 		const height = this.canvas.clientHeight;
 		if ( width === 0 || height === 0 ) return;
+		if ( ! this._isRenderSizeSupported( width, height ) ) return;
 
 		this.renderer.setPixelRatio( 1.0 );
 		this.renderer.setSize( width, height, false );
@@ -878,6 +901,8 @@ export class PathTracerApp extends EventDispatcher {
 
 	_applyRenderResize( renderWidth, renderHeight ) {
 
+		if ( ! this._isRenderSizeSupported( renderWidth, renderHeight ) ) return;
+
 		this.pipeline?.setSize( renderWidth, renderHeight );
 		this.denoisingManager?.setRenderSize( renderWidth, renderHeight );
 		this.needsReset = true;
@@ -889,6 +914,7 @@ export class PathTracerApp extends EventDispatcher {
 	setCanvasSize( width, height ) {
 
 		if ( width === 0 || height === 0 ) return;
+		if ( ! this._isRenderSizeSupported( width, height ) ) return;
 
 		this.renderer.setPixelRatio( 1.0 );
 		this.renderer.setSize( width, height, false );
@@ -927,15 +953,6 @@ export class PathTracerApp extends EventDispatcher {
 
 		this.stages.pathTracer?.setUniform( 'renderMode', parseInt( config.renderMode ) );
 		this.stages.pathTracer?.setUniform( 'enableAlphaShadows', config.enableAlphaShadows ?? false );
-		this.stages.pathTracer?.tileManager?.setTileCount( config.tiles );
-
-		const tileHelper = this.overlayManager?.getHelper( 'tiles' );
-		if ( tileHelper ) {
-
-			tileHelper.enabled = config.tilesHelper;
-			if ( ! config.tilesHelper ) tileHelper.hide();
-
-		}
 
 		this.stages.pathTracer?.updateCompletionThreshold?.();
 
@@ -958,6 +975,20 @@ export class PathTracerApp extends EventDispatcher {
 
 		this.needsReset = false;
 		this.pauseRendering = false;
+
+		// Entering a final render starts a fresh peak window (Blender per-render semantics).
+		if ( isProduction ) {
+
+			const tracker = this.stages.pathTracer?.vramTracker;
+			if ( tracker ) {
+
+				tracker.measure();
+				tracker.resetPeak();
+
+			}
+
+		}
+
 		this.reset();
 
 	}
@@ -1067,6 +1098,69 @@ export class PathTracerApp extends EventDispatcher {
 
 	}
 
+	/** The path tracer's VRAM tracker, or null before stages are built. */
+	get vram() {
+
+		return this.stages.pathTracer?.vramTracker ?? null;
+
+	}
+
+	/**
+	 * On-demand current/peak GPU memory snapshot.
+	 * @returns {{ current: number, peak: number, byCategory: Object }} bytes
+	 */
+	getMemoryInfo() {
+
+		return this.stages.pathTracer?.vramTracker?.measure() ?? { current: 0, peak: 0, byCategory: {} };
+
+	}
+
+	// Idempotent: registers the cross-stage texture provider and re-measures on
+	// allocation events (scene/env load, resize) so peak is caught even while idle.
+	_ensureVRAMWiring() {
+
+		if ( this._vramWired ) return;
+		const tracker = this.stages.pathTracer?.vramTracker;
+		if ( ! tracker ) return; // stages not ready yet
+
+		tracker.register( 'stages', () => this._collectStageTextures() );
+
+		const remeasure = () => tracker.measure();
+		this._addTrackedListener( this, 'SceneRebuild', remeasure );
+		this._addTrackedListener( this, 'EnvironmentLoaded', remeasure );
+		this._addTrackedListener( this, 'resolution_changed', remeasure );
+
+		this._vramWired = true;
+
+	}
+
+	// Direct StorageTexture/RenderTarget properties of every non-pathTracer stage
+	// (denoiser/G-buffer/filter targets). The pathTracer's own buffers/textures are
+	// registered explicitly; measure() dedupes by identity so overlaps don't double-count.
+	_collectStageTextures() {
+
+		const out = [];
+		const stages = this.stages || {};
+		const pt = stages.pathTracer;
+
+		for ( const key in stages ) {
+
+			const stage = stages[ key ];
+			if ( ! stage || stage === pt || typeof stage !== 'object' ) continue;
+
+			for ( const prop in stage ) {
+
+				const v = stage[ prop ];
+				if ( v && ( v.isTexture || v.isRenderTarget ) ) out.push( v );
+
+			}
+
+		}
+
+		return out;
+
+	}
+
 	// ═══════════════════════════════════════════════════════════════
 	// Materials (absorbed from MaterialsAPI)
 	// ═══════════════════════════════════════════════════════════════
@@ -1207,6 +1301,7 @@ export class PathTracerApp extends EventDispatcher {
 				maxBufferSize: adapterLimits.maxBufferSize,
 				maxStorageBufferBindingSize: adapterLimits.maxStorageBufferBindingSize,
 				maxColorAttachmentBytesPerSample: 128,
+				maxStorageBuffersPerShaderStage: Math.min( adapterLimits.maxStorageBuffersPerShaderStage, 10 ),
 			}
 		} );
 
@@ -1265,7 +1360,6 @@ export class PathTracerApp extends EventDispatcher {
 		this.pipeline.addStage( this.stages.asvgf );
 		this.pipeline.addStage( this.stages.variance );
 		this.pipeline.addStage( this.stages.bilateralFilter );
-		this.pipeline.addStage( this.stages.adaptiveSampling );
 		this.pipeline.addStage( this.stages.edgeFilter );
 		this.pipeline.addStage( this.stages.autoExposure );
 		this.pipeline.addStage( this.stages.compositor );
@@ -1469,9 +1563,6 @@ export class PathTracerApp extends EventDispatcher {
 
 	_createStages() {
 
-		const adaptiveSamplingMax = this.settings.get( 'adaptiveSamplingMax' );
-		const useAdaptiveSampling = this.settings.get( 'useAdaptiveSampling' );
-
 		this.stages.pathTracer = new PathTracer( this.renderer, this.scene, this.cameraManager.camera );
 		this.stages.normalDepth = new NormalDepth( this.renderer, {
 			pathTracer: this.stages.pathTracer
@@ -1483,10 +1574,6 @@ export class PathTracerApp extends EventDispatcher {
 		this.stages.asvgf = new ASVGF( this.renderer, { enabled: false } );
 		this.stages.variance = new Variance( this.renderer, { enabled: false } );
 		this.stages.bilateralFilter = new BilateralFilter( this.renderer, { enabled: false } );
-		this.stages.adaptiveSampling = new AdaptiveSampling( this.renderer, {
-			adaptiveSamplingMax,
-			enabled: useAdaptiveSampling,
-		} );
 		this.stages.edgeFilter = new EdgeFilter( this.renderer, { enabled: false } );
 		this.stages.autoExposure = new AutoExposure( this.renderer, { enabled: DEFAULT_STATE.autoExposure ?? false } );
 
@@ -1505,10 +1592,11 @@ export class PathTracerApp extends EventDispatcher {
 			camera: this.cameraManager.camera,
 			stages: {
 				pathTracer: this.stages.pathTracer,
+				normalDepth: this.stages.normalDepth,
+				motionVector: this.stages.motionVector,
 				asvgf: this.stages.asvgf,
 				variance: this.stages.variance,
 				bilateralFilter: this.stages.bilateralFilter,
-				adaptiveSampling: this.stages.adaptiveSampling,
 				edgeFilter: this.stages.edgeFilter,
 				ssrc: this.stages.ssrc,
 				autoExposure: this.stages.autoExposure,
@@ -1523,6 +1611,10 @@ export class PathTracerApp extends EventDispatcher {
 		this.denoisingManager.setupDenoiser();
 		this.denoisingManager.setupUpscaler();
 
+		// Seed G-buffer gating: NormalDepth/MotionVector start enabled (stage default)
+		// but are only needed by real-time denoisers — idle them until one is active.
+		this.denoisingManager._syncGBufferStages();
+
 		// Set initial render resolution
 		const initW = this.canvas.clientWidth || 1;
 		const initH = this.canvas.clientHeight || 1;

package/src/Pipeline/PipelineContext.js

@@ -42,7 +42,7 @@ export class PipelineContext {
 			accumulatedFrames: 0,
 
 			// Render modes
-			renderMode: 0, // 0 = progressive, 1 = tiled
+			renderMode: 0, // 0 = interactive, 1 = production (full-frame in both)
 			interactionMode: false,
 			isComplete: false,
 
@@ -65,7 +65,6 @@ export class PipelineContext {
 
 			// Feature flags
 			enableASVGF: false,
-			enableAdaptiveSampling: false,
 			enableEdgeFiltering: false,
 			// Can be extended by stages as needed
 		};

package/src/Pipeline/RenderPipeline.js

@@ -22,7 +22,7 @@ import { EventDispatcher } from './EventDispatcher.js';
  * // Add stages in execution order
  * pipeline.addStage(new PathTracer(...));
  * pipeline.addStage(new ASVGF(...));
- * pipeline.addStage(new AdaptiveSampling(...));
+ * pipeline.addStage(new EdgeFilter(...));
  *
  * // Render all stages
  * pipeline.render(writeBuffer);

package/src/Pipeline/RenderStage.js

@@ -28,7 +28,7 @@ export const StageExecutionMode = {
 
 	/**
 	 * CONDITIONAL - Stage decides execution via shouldExecute() method
-	 * Use for: Stages with complex execution logic (AdaptiveSampling)
+	 * Use for: Stages with complex execution logic
 	 */
 	CONDITIONAL: 'conditional'
 };

package/src/Processor/CameraOptimizer.js

@@ -25,7 +25,6 @@ export class CameraOptimizer {
 		this.interactionQualitySettings = {
 			maxBounceCount: 1,
 			numRaysPerPixel: 1,
-			useAdaptiveSampling: false,
 			useEnvMapIS: false,
 			// pixelRatio: 0.25,
 			enableAccumulation: false,
@@ -306,7 +305,6 @@ export class CameraOptimizer {
 			'ultra-low': {
 				maxBounceCount: 1,
 				numRaysPerPixel: 1,
-				useAdaptiveSampling: false,
 				useEnvMapIS: false,
 				pixelRatio: 0.125,
 				enableAccumulation: false
@@ -314,7 +312,6 @@ export class CameraOptimizer {
 			'low': {
 				maxBounceCount: 1,
 				numRaysPerPixel: 1,
-				useAdaptiveSampling: false,
 				useEnvMapIS: false,
 				pixelRatio: 0.25,
 				enableAccumulation: false
@@ -322,7 +319,6 @@ export class CameraOptimizer {
 			'medium': {
 				maxBounceCount: 2,
 				numRaysPerPixel: 1,
-				useAdaptiveSampling: false,
 				useEnvMapIS: true,
 				pixelRatio: 0.5,
 				enableAccumulation: false
@@ -330,7 +326,6 @@ export class CameraOptimizer {
 			'high': {
 				maxBounceCount: 3,
 				numRaysPerPixel: 1,
-				useAdaptiveSampling: true,
 				useEnvMapIS: true,
 				pixelRatio: 0.75,
 				enableAccumulation: true

package/src/Processor/GeometryExtractor.js

@@ -536,6 +536,10 @@ export class GeometryExtractor {
 	// triangle extraction that stores directly in texture format
 	extractTrianglesInBatch( positions, normals, uvs, indices, triangleCount, materialIndex, meshIndex ) {
 
+		// Track per-material triangle count for sort-bin remap (item 41)
+		while ( this.materialTriangleCounts.length <= materialIndex ) this.materialTriangleCounts.push( 0 );
+		this.materialTriangleCounts[ materialIndex ] += triangleCount;
+
 		// Pre-allocate objects for positions, normals, and UVs
 		const posA = this._getVec3( 0 );
 		const posB = this._getVec3( 1 );
@@ -779,6 +783,7 @@ export class GeometryExtractor {
 
 		// Reset other arrays
 		this.materials = [];
+		this.materialTriangleCounts = []; // Per-material triangle count (for sort-bin remap, item 41)
 		this.meshes = [];
 		this.meshTriangleRanges = []; // Per-mesh { start, count } for TLAS/BLAS
 		this.maps = [];
@@ -816,6 +821,7 @@ export class GeometryExtractor {
 			triangleData: this.getTriangleData(), // Texture-ready Float32Array format
 			triangleCount: this.getTriangleCount(),
 			materials: this.materials,
+			materialTriangleCounts: this.materialTriangleCounts,
 			meshes: this.meshes,
 			meshTriangleRanges: this.meshTriangleRanges, // Per-mesh { start, count } for TLAS/BLAS
 			maps: this.maps,