rayzee 7.11.0 → 7.12.0

package/package.json

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

package/src/EngineDefaults.js

@@ -83,6 +83,19 @@ export const ENGINE_DEFAULTS = {
 	bounces: 3,
 	transmissiveBounces: 5,
 	maxSubsurfaceSteps: 8, // interactive default: low cap (bounded random-walk SSS)
+
+	// Adaptive sampling (Blender-style): stop the frame once enough pixels drop below the noise threshold.
+	useAdaptiveSampling: true,
+	noiseThreshold: 0.02, // per-pixel noise below which a pixel is converged
+	darkNoiseFloor: 0.003, // extra absolute-noise floor so dark pixels can converge too
+	adaptiveMinSamples: 8, // min samples before adaptive sampling can trigger
+	adaptiveStopFraction: 0.95, // retire the frame once this fraction of pixels has converged
+	// Per-pixel freeze: skip tracing pixels that individually converged (noise threshold only — no dark floor,
+	// which would bake dim regions too dark). Naturally engages only on static/idle views. See docs/specs/tier2-adaptive-sampling-plan.md.
+	usePixelFreeze: false,
+	pixelFreezeThreshold: 0.02, // per-pixel noise below which a pixel becomes a freeze candidate
+	pixelFreezeStability: 8, // consecutive candidate frames before a pixel freezes
+
 	samplingTechnique: 3,
 	enableEmissiveTriangleSampling: false,
 	emissiveBoost: 1.0,
@@ -556,10 +569,18 @@ export const DEFAULT_TEXTURE_MATRIX = [ 0, 0, 1, 1, 0, 0, 0, 1 ];
 // 'interactive' — low-sample, bounded bounces, no offline denoising, controls enabled.
 // 'production'  — high-sample, deep bounces, OIDN enabled, controls disabled.
 export const PRODUCTION_RENDER_CONFIG = {
-	maxSamples: 30, bounces: 20, transmissiveBounces: 8, maxSubsurfaceSteps: 64,
+	// maxSamples is a CEILING: adaptive sampling retires the frame once adaptiveStopFraction of pixels converge,
+	// so easy scenes finish well under it while hard GI scenes use the full budget.
+	maxSamples: 150, bounces: 20, transmissiveBounces: 8, maxSubsurfaceSteps: 64,
 	renderMode: 1, enableAlphaShadows: true,
 	enableOIDN: true, oidnQuality: 'balance',
 	interactionModeEnabled: false,
+	// Looser thresholds + stop at 90%, leaning on OIDN to clean the residual tail.
+	useAdaptiveSampling: true,
+	noiseThreshold: 0.1,
+	darkNoiseFloor: 0.01,
+	adaptiveStopFraction: 0.9,
+	usePixelFreeze: true,
 };
 
 export const INTERACTIVE_RENDER_CONFIG = {
@@ -569,6 +590,8 @@ export const INTERACTIVE_RENDER_CONFIG = {
 	maxSubsurfaceSteps: ENGINE_DEFAULTS.maxSubsurfaceSteps,
 	enableOIDN: false, oidnQuality: 'fast',
 	interactionModeEnabled: true,
+	useAdaptiveSampling: true, // idle refine stops early when converged; frozen during motion
+	usePixelFreeze: true, // speeds up idle refinement on heavy/high-res views; inert while moving (freeze resets)
 };
 
 // Memory management constants

package/src/PathTracerApp.js

@@ -323,6 +323,7 @@ export class PathTracerApp extends EventDispatcher {
 			const tracker = this.stages.pathTracer?.vramTracker;
 			const frame = this.stages.pathTracer?.frameCount ?? 0;
 			if ( tracker && ( frame <= 1 || frame % 30 === 0 ) ) tracker.measure();
+
 			updateStats( {
 				timeElapsed: this.completion.timeElapsed,
 				samples: getDisplaySamples( this.stages.pathTracer ),
@@ -1236,6 +1237,19 @@ export class PathTracerApp extends EventDispatcher {
 		this.stages.pathTracer?.setUniform( 'renderMode', parseInt( config.renderMode ) );
 		this.stages.pathTracer?.setUniform( 'enableAlphaShadows', config.enableAlphaShadows ?? false );
 
+		// Tier-1 convergence early-stop (live uniforms, no kernel rebuild). Threshold/min-samples fall back to
+		// engine defaults when a config doesn't override them.
+		this.stages.pathTracer?.setUniform( 'useAdaptiveSampling', config.useAdaptiveSampling ?? false );
+		this.stages.pathTracer?.setUniform( 'noiseThreshold', config.noiseThreshold ?? DEFAULT_STATE.noiseThreshold );
+		this.stages.pathTracer?.setUniform( 'darkNoiseFloor', config.darkNoiseFloor ?? DEFAULT_STATE.darkNoiseFloor );
+		this.stages.pathTracer?.setUniform( 'adaptiveStopFraction', config.adaptiveStopFraction ?? DEFAULT_STATE.adaptiveStopFraction );
+		this.stages.pathTracer?.setUniform( 'adaptiveMinSamples', config.adaptiveMinSamples ?? DEFAULT_STATE.adaptiveMinSamples );
+
+		// Tier-2 per-pixel freeze (per-mode; falls back off when a config doesn't set it).
+		this.stages.pathTracer?.setUniform( 'usePixelFreeze', config.usePixelFreeze ?? false );
+		this.stages.pathTracer?.setUniform( 'pixelFreezeThreshold', config.pixelFreezeThreshold ?? DEFAULT_STATE.pixelFreezeThreshold );
+		this.stages.pathTracer?.setUniform( 'pixelFreezeStability', config.pixelFreezeStability ?? DEFAULT_STATE.pixelFreezeStability );
+
 		this.stages.pathTracer?.updateCompletionThreshold?.();
 
 		const denoiser = this.denoisingManager?.denoiser;

package/src/Pipeline/CompletionTracker.js

@@ -48,7 +48,10 @@ export class CompletionTracker {
 
 		if ( this.isTimeLimitReached( renderLimitMode, renderTimeLimit ) ) return true;
 
-		return pathTracer.frameCount >= pathTracer.completionThreshold;
+		// Tier-1 convergence early-stop must agree with PathTracer.render()'s own check, else the app-level
+		// reconcile would flip isComplete back off and keep dispatching after the frame converged.
+		return pathTracer.frameCount >= pathTracer.completionThreshold
+			|| ( pathTracer._isConvergedComplete?.() ?? false );
 
 	}
 

package/src/Processor/KernelManager.js

@@ -16,7 +16,6 @@ const WORKGROUP_SIZES = {
 	connect: [ 256, 1, 1 ], // 1D shadow-ray-parallel
 	accumulate: [ 256, 1, 1 ], // 1D shadow-ray-parallel
 	compact: [ 256, 1, 1 ], // 1D ray-parallel
-	resetCounters: [ 1, 1, 1 ], // Single thread
 	finalWrite: [ 16, 16, 1 ], // 2D screen-space
 };
 

package/src/Processor/QueueManager.js

@@ -11,7 +11,14 @@ export const COUNTER = {
 	ACTIVE_RAY_COUNT: 0,
 	// rays entering current bounce; snapshotted before ACTIVE_RAY_COUNT reset so over-sized dispatch is safe.
 	ENTERING_COUNT: 1,
-	COUNT: 2,
+	// per-frame count of pixels whose Tier-1 relative-error dropped below threshold; zeroed at frame start by
+	// initActiveIndices, incremented in FinalWrite, read back async to drive the whole-frame convergence early-stop.
+	CONVERGED_COUNT: 2,
+	// Tier-2 per-pixel freeze: FROZEN_COUNT = pixels skipped this frame; ACTIVE_PIXEL_COUNT = bounce-0 active
+	// count (maxRays − frozen), read back to size next frame's grid.
+	FROZEN_COUNT: 3,
+	ACTIVE_PIXEL_COUNT: 4,
+	COUNT: 5,
 };
 
 /** Ray flag bits packed into rayBounceFlags (uint) */

package/src/Processor/ShaderBuilder.js

@@ -19,6 +19,7 @@ export class ShaderBuilder {
 		// Previous-frame texture nodes (sample from MRT RenderTarget)
 		this.prevColorTexNode = null;
 		this.prevAlbedoTexNode = null;
+		this.prevNormalDepthTexNode = null;
 
 		// Scene texture nodes cache (for in-place updates on model change)
 		this._sceneTextureNodes = null;
@@ -98,6 +99,7 @@ export class ShaderBuilder {
 		const readTextures = storageTextures.getReadTextures();
 		this.prevColorTexNode = texture( readTextures.color );
 		this.prevAlbedoTexNode = texture( readTextures.albedo );
+		this.prevNormalDepthTexNode = texture( readTextures.normalDepth );
 
 		const createArrayPlaceholder = () => {
 
@@ -137,6 +139,7 @@ export class ShaderBuilder {
 
 		this.prevColorTexNode = null;
 		this.prevAlbedoTexNode = null;
+		this.prevNormalDepthTexNode = null;
 		this._sceneTextureNodes = null;
 
 	}

package/src/RenderSettings.js

@@ -40,6 +40,15 @@ const SETTING_ROUTES = {
 	samplingTechnique: { uniform: 'samplingTechnique', reset: true },
 	fireflyThreshold: { uniform: 'fireflyThreshold', reset: true },
 	enableAlphaShadows: { uniform: 'enableAlphaShadows', reset: true },
+	// Adaptive sampling — whole-frame early-stop (useAdaptiveSampling) + per-pixel freeze (usePixelFreeze)
+	useAdaptiveSampling: { uniform: 'useAdaptiveSampling', reset: true },
+	noiseThreshold: { uniform: 'noiseThreshold', reset: true },
+	darkNoiseFloor: { uniform: 'darkNoiseFloor', reset: true },
+	adaptiveMinSamples: { uniform: 'adaptiveMinSamples', reset: true },
+	adaptiveStopFraction: { uniform: 'adaptiveStopFraction', reset: true },
+	usePixelFreeze: { uniform: 'usePixelFreeze', reset: true },
+	pixelFreezeThreshold: { uniform: 'pixelFreezeThreshold', reset: true },
+	pixelFreezeStability: { uniform: 'pixelFreezeStability', reset: true },
 	enableEmissiveTriangleSampling: { uniform: 'enableEmissiveTriangleSampling', reset: true },
 	emissiveBoost: { uniform: 'emissiveBoost', reset: true },
 	visMode: { uniform: 'visMode', reset: true },