rayzee 8.3.0 → 8.4.1

package/dist/rolldown-runtime-CAFD8bLK.js

@@ -0,0 +1,11 @@
+//#region \0rolldown/runtime.js
+var e = Object.defineProperty, t = (t, n) => {
+	let r = {};
+	for (var i in t) e(r, i, {
+		get: t[i],
+		enumerable: !0
+	});
+	return n || e(r, Symbol.toStringTag, { value: "Module" }), r;
+};
+//#endregion
+export { t };

package/package.json

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

package/src/AssetConfig.js

@@ -32,6 +32,13 @@ const config = {
 	// AI upscaler ONNX model base URL. Quality presets resolve relative paths against this.
 	upscalerModelBaseUrl: 'https://huggingface.co/notaneimu/onnx-image-models/resolve/main/',
 
+	// DLSS runtime bundle. A plain script the host serves, not a module: it installs
+	// `globalThis.DLSSRuntime`, so it cannot be imported and the host must publish it somewhere.
+	dlssRuntimeUrl: '/dlss/dlss-runtime.js',
+
+	// Base for the DLSS weight manifests the runtime fetches (`generated/...` beneath this).
+	dlssAssetBaseUrl: 'https://pub-6e048ff014374f11bef33d76b6c2b5ef.r2.dev/v1',
+
 	// Prefix used when the engine writes to client-side stores (IndexedDB, etc).
 	// Set to a unique value to avoid collisions when multiple apps embed the engine on the same origin.
 	cacheNamespace: 'rayzee',

package/src/EngineDefaults.js

@@ -10,13 +10,11 @@
  */
 export const RENDER_PROFILES = Object.freeze( {
 	viewer: Object.freeze( {
-		areaLightIntensityScale: 0.1, // scales glTF placeholder area-light power (viewer tuning)
 		environmentRotation: 270.0, // degrees
 		toneMapping: 4, // ACESFilmicToneMapping
 		saturation: 1.2, // compensates for ACES desaturation — see Compositor
 	} ),
 	physical: Object.freeze( {
-		areaLightIntensityScale: 1.0,
 		environmentRotation: 0.0,
 		// AgX, matching Blender/Cycles' default view transform. ACES crushes shadows on this
 		// engine's own corpus (shade 1.48 vs AgX 3.01 from identical radiance).
@@ -27,7 +25,7 @@ export const RENDER_PROFILES = Object.freeze( {
 
 /**
  * @param {string} [name] - a RENDER_PROFILES key
- * @returns {{areaLightIntensityScale: number, environmentRotation: number}}
+ * @returns {{environmentRotation: number, toneMapping: number, saturation: number}}
  * @throws {Error} on an unknown name — a typo must not silently select viewer tuning
  */
 export function getRenderProfile( name = 'viewer' ) {
@@ -1062,7 +1060,8 @@ export const DEFAULT_TEXTURE_MATRIX = [ 0, 0, 1, 1, 0, 0, 0, 1 ];
 export const PRODUCTION_RENDER_CONFIG = {
 	// 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,
+	// Below 24 a ray that spends its transmissive budget is shaded opaque — black pixels, not dim glass.
+	maxSamples: 30, bounces: 20, transmissiveBounces: 24, maxSubsurfaceSteps: 64,
 	renderMode: 1, enableAlphaShadows: true,
 	// 'high' is the only tier that reaches OIDN's _large weights (calb_cnrm); ~2x denoise cost.
 	enableOIDN: true, oidnQuality: 'high',
@@ -1077,9 +1076,14 @@ export const PRODUCTION_RENDER_CONFIG = {
 export const INTERACTIVE_RENDER_CONFIG = {
 	maxSamples: ENGINE_DEFAULTS.maxSamples, bounces: ENGINE_DEFAULTS.bounces,
 	renderMode: ENGINE_DEFAULTS.renderMode, enableAlphaShadows: ENGINE_DEFAULTS.enableAlphaShadows,
-	transmissiveBounces: ENGINE_DEFAULTS.transmissiveBounces,
+	// 12, not 5: a spent budget leaves black glass and costs MORE — the ray then bounces diffusely.
+	transmissiveBounces: 12,
 	maxSubsurfaceSteps: ENGINE_DEFAULTS.maxSubsurfaceSteps,
-	enableOIDN: false, oidnQuality: 'fast',
+	// On, like production. The final pass costs one cheap denoise when the preview settles, and both
+	// neural passes need a denoised frame to be worth running — on Monte-Carlo noise the upscaler
+	// measured worse than a plain resize. ⚠️ `ENGINE_DEFAULTS.enableOIDN` stays false: the bench
+	// renders against it and every quality golden would move.
+	enableOIDN: true, oidnQuality: 'fast',
 	interactionModeEnabled: true,
 	useAdaptiveSampling: true, // idle refine stops early when converged; frozen during motion
 	noiseThreshold: 0.1, // loose: preview wants a fast settle, not a clean one

package/src/EngineIssues.js

@@ -19,6 +19,7 @@ export const ISSUE_CODES = Object.freeze( {
 	STAGE_RENDER_FAILED: 'stage.render_failed',
 	RENDER_RESERVE_CAPPED: 'render.reserve_capped',
 	SCENE_MEMORY_BUDGET: 'scene.memory_budget',
+	LIGHT_PLACEHOLDER_INVALID: 'light.placeholder_invalid',
 	EMISSIVE_INSTANCES_COLLAPSED: 'emissive.instances_collapsed',
 	REFIT_SHARED_GEOMETRY: 'refit.shared_geometry',
 } );

package/src/LightUnits.js

@@ -0,0 +1,122 @@
+/**
+ * The engine's light-unit rule, stated once.
+ *
+ * Every light in the scene graph is a **valid three.js light**: it carries the quantity three.js
+ * expects for its type, measured in radiometric (watt-based) units rather than photometric ones.
+ *
+ *   point / spot  → radiant intensity   W/sr
+ *   directional   → irradiance          W/m²
+ *   rect area     → radiance            W/(sr·m²), `width`/`height` in world metres, unit scale
+ *
+ * three.js' shading maths is unit-agnostic — it divides by distance² and integrates a form factor,
+ * never caring whether the number it was handed is candela or W/sr. Feeding it radiometric values
+ * therefore makes the raster fallback, the light helpers and any host reading `sceneModel` correct
+ * without one of them knowing anything about the path tracer.
+ *
+ * Blender-style **Power in Watts** — what the Lights panel edits — is a view of that, converted
+ * here and nowhere else. `LightSerializer` converts the other way when it fills the GPU buffer.
+ */
+
+/** Luminous efficacy that glTF, three.js and Blender's exporter all assume (lm/W). */
+export const LUMENS_PER_WATT = 683;
+
+/** Emitting area in m², including the ellipse/disk shape factor. Assumes unit world scale. */
+export function areaLightArea( light ) {
+
+	const shape = light.userData?.shape;
+	const shapeFactor = shape === 'ellipse' || shape === 'disk' ? Math.PI / 4 : 1;
+	const area = Math.abs( light.width * light.height ) * shapeFactor;
+	return Number.isFinite( area ) && area > 0 ? area : 0;
+
+}
+
+/**
+ * Blender-style Power for the Lights panel: radiant power in W for point, spot and area lights,
+ * and the Sun's strength in W/m² unchanged.
+ */
+export function lightPower( light ) {
+
+	if ( light.isRectAreaLight ) {
+
+		const normalize = light.userData?.normalize ?? true;
+		return light.intensity * Math.PI * ( normalize ? areaLightArea( light ) : 1 );
+
+	}
+
+	if ( light.isPointLight || light.isSpotLight ) return light.intensity * 4 * Math.PI;
+
+	return light.intensity;
+
+}
+
+/** Inverse of {@link lightPower} — what the panel writes back. */
+export function setLightPower( light, watts ) {
+
+	if ( light.isRectAreaLight ) {
+
+		const normalize = light.userData?.normalize ?? true;
+		const denominator = Math.PI * ( normalize ? areaLightArea( light ) : 1 );
+		light.intensity = denominator > 0 ? watts / denominator : 0;
+		return;
+
+	}
+
+	if ( light.isPointLight || light.isSpotLight ) {
+
+		light.intensity = watts / ( 4 * Math.PI );
+		return;
+
+	}
+
+	light.intensity = watts;
+
+}
+
+/**
+ * Runs `mutate` with the light's Power held constant.
+ *
+ * Resizing a normalized area light is meant to keep its total power and change its radiance —
+ * Blender's Normalize toggle. Since the stored quantity is radiance, that only happens if the
+ * edit puts the Power back afterwards. With Normalize off, Power does not depend on the area,
+ * so this is a no-op and the same call is still correct.
+ */
+export function preserveLightPower( light, mutate ) {
+
+	const watts = lightPower( light );
+	mutate();
+	setLightPower( light, watts );
+
+}
+
+/**
+ * Puts an area light's rectangle in world metres with unit scale, leaving its world size and
+ * placement untouched.
+ *
+ * ⚠️ three.js' rasteriser reads `width`/`height` as WORLD dimensions and drops any scale inherited
+ * from parent nodes — `RectAreaLightNode` builds the light's basis with `extractRotation`, which
+ * normalises the scale away. A light authored as 70 units under a 0.01 node scale therefore rasters
+ * as a **70 metre** panel while the path tracer, which uses the world matrix, renders the 0.7 m one
+ * it should. Measured on 24001884.glb: 58.7x too bright in the raster view. Baking the scale in and
+ * cancelling it on the light itself makes every reader agree.
+ *
+ * Idempotent: a light already at unit scale is left alone, so re-processing a tree is safe.
+ */
+export function bakeAreaLightScale( light ) {
+
+	light.updateWorldMatrix( true, false );
+
+	// Column lengths of the world matrix, read directly so this module needs no three.js import.
+	const e = light.matrixWorld.elements;
+	const sx = Math.hypot( e[ 0 ], e[ 1 ], e[ 2 ] );
+	const sy = Math.hypot( e[ 4 ], e[ 5 ], e[ 6 ] );
+	const sz = Math.hypot( e[ 8 ], e[ 9 ], e[ 10 ] );
+
+	if ( ! Number.isFinite( sx ) || ! Number.isFinite( sy ) || sx === 0 || sy === 0 ) return;
+	if ( Math.abs( sx - 1 ) < 1e-9 && Math.abs( sy - 1 ) < 1e-9 ) return;
+
+	light.width = Math.abs( light.width * sx );
+	light.height = Math.abs( light.height * sy );
+	light.scale.set( light.scale.x / sx, light.scale.y / sy, sz === 0 ? light.scale.z : light.scale.z / sz );
+	light.updateMatrixWorld( true );
+
+}

package/src/PathTracerApp.js

@@ -764,8 +764,9 @@ export class PathTracerApp extends EventDispatcher {
 	 * by reference, and any ancestor transform is baked in. Later edits to `object3d` do not
 	 * reach the render — mutate {@link sceneModel}, then {@link refitBVH}/{@link refitBLASes}.
 	 *
-	 * Lights keep three.js units — `RectAreaLight.intensity` in nits, point/spot in candela — and are
-	 * converted to radiant power on the copy. `areaLightIntensityScale` does not apply here.
+	 * Lights are read as three.js lights in RADIOMETRIC units — W/sr for point and spot, W/m² for
+	 * directional, radiance for area — and are left as they are; only an area light's rectangle is
+	 * put into world metres on the copy. See `LightUnits.js`.
 	 *
 	 * @param {import('three').Object3D} object3d - The Object3D to render; left untouched.
 	 * @param {string} [name='object3d'] - Display name for the object
@@ -2463,11 +2464,13 @@ export class PathTracerApp extends EventDispatcher {
 
 		if ( ! this.renderer?.domElement ) return null;
 
+		// Whatever is on the overlay is what the viewport shows, so it is also what a save must
+		// write. Gating on `upscaler.enabled` instead missed the neural-rendering pass, which puts
+		// a picture there without the ONNX upscaler being on at all — saves silently wrote the
+		// un-enhanced render.
 		const dm = this.denoisingManager;
-		const upscaled = dm?.upscaler?.enabled && dm?.upscalerCanvas
-			&& dm.upscalerCanvas.style.display !== 'none';
-
-		if ( upscaled ) return dm.upscalerCanvas;
+		const overlay = dm?.upscalerCanvas;
+		if ( overlay && overlay.style.display !== 'none' ) return overlay;
 
 		// A presented WebGPU canvas only reads back what was drawn immediately before, so draw.
 		// This also puts the denoised picture on it: the Compositor prefers it over the raw render.
@@ -3104,6 +3107,7 @@ export class PathTracerApp extends EventDispatcher {
 		this.denoisingManager.setOverlayManager( this.overlayManager );
 		this.denoisingManager.setResetCallback( () => this.reset() );
 		this.denoisingManager.setPostProcessRefreshCallback( () => this.requestPostProcessRefresh() );
+		this.denoisingManager.setDisplayRefreshCallback( () => this.refreshFrame() );
 		this.denoisingManager.setSettings( this.settings );
 
 		// Expose environment manager (lives on pathTracer stage)

package/src/Processor/AssetLoader.js

@@ -19,6 +19,7 @@ import { getAssetConfig } from '../AssetConfig.js';
 import { loadPBRTScene, pickEntryPath } from './PBRT/index.js';
 import { extractSceneMetadata } from './SceneMetadata.js';
 import { ISSUE_CODES, ISSUE_SEVERITY } from '../EngineIssues.js';
+import { bakeAreaLightScale, LUMENS_PER_WATT } from '../LightUnits.js';
 import { getRenderProfile } from '../EngineDefaults.js';
 
 // Define supported file formats
@@ -67,16 +68,43 @@ function standInForSplit( source ) {
 
 }
 
-// three.js nits → the engine's radiant power, inverting areaLightRadiance.
-function areaLightPowerFactor( node, width, height, userData ) {
+const PLACEHOLDER_SHAPES = new Set( [ 'rectangle', 'square', 'disk', 'ellipse' ] );
 
-	if ( ! ( userData.normalize ?? true ) ) return Math.PI;
+/**
+ * Build the light a placeholder node stands for. glTF has no area light, so a three.js host's
+ * patched GLTFExporter writes the RectAreaLight into the node's `extras` and leaves the node
+ * itself carrying the transform. `intensity` is three.js radiance, which is what the engine
+ * stores, so the number is used as authored; only the rectangle needs normalising to world
+ * metres (see `bakeAreaLightScale`).
+ *
+ * `power`, `position`, `rotation` and `direction` are present in the record and deliberately
+ * unused. The node's matrix already carries the transform, `direction` is not even normalised,
+ * and `power` was written from the light's UNSCALED dimensions — on 24155522.glb's window light,
+ * whose ancestor scale is non-uniform (1.6 × 1.2 m in world, not 1.2 × 1.2), it is 25 % low.
+ *
+ * @returns {RectAreaLight|null} null when the record carries no usable size or intensity.
+ */
+function areaLightFromPlaceholder( node, record ) {
 
-	const shapeFactor = userData.shape === 'ellipse' || userData.shape === 'disk' ? Math.PI / 4 : 1;
-	const scale = node.getWorldScale( new Vector3() );
-	// abs: a mirrored ancestor decomposes negative; the serializer takes the area as |u × v|.
-	const factor = Math.PI * shapeFactor * Math.abs( width * scale.x * height * scale.y );
-	return Number.isFinite( factor ) ? factor : Math.PI;
+	const width = Number( record.width );
+	const height = Number( record.height );
+	const intensity = Number( record.intensity );
+	if ( ! ( width > 0 ) || ! ( height > 0 ) || ! Number.isFinite( intensity ) ) return null;
+
+	const shape = PLACEHOLDER_SHAPES.has( record.shape ) ? record.shape : 'rectangle';
+	const color = Array.isArray( record.color ) && record.color.length >= 3 ? record.color : [ 1, 1, 1 ];
+
+	const light = new RectAreaLight( new Color( ...color ), intensity, width, height );
+	light.name = record.name || 'RectAreaLight';
+	light.userData.normalize = record.normalize ?? true;
+	light.userData.spread = Number.isFinite( record.spread ) ? record.spread : Math.PI;
+	light.userData.shape = shape;
+
+	// Parented before baking: the bake needs the node's world scale, and on the append path
+	// nothing has refreshed the tree yet.
+	node.add( light );
+	bakeAreaLightScale( light );
+	return light;
 
 }
 
@@ -2081,50 +2109,40 @@ export class AssetLoader extends EventDispatcher {
 
 			const userData = object.userData;
 
-			// An adopted light carries three.js units; convert as point/spot are below.
-			if ( object.isRectAreaLight && ! userData.__radianceConverted ) {
+			// three.js states RectAreaLight.intensity as radiance, which is what the engine
+			// stores, so only the rectangle needs putting into world metres.
+			if ( object.isRectAreaLight ) bakeAreaLightScale( object );
 
-				object.intensity *= areaLightPowerFactor( object, object.width, object.height, userData );
-				userData.__radianceConverted = true;
+			// Punctual lights arrive photometric: glTF (and three.js) state point/spot in
+			// candela and directional in lux. The engine keeps the same QUANTITY in radiometric
+			// units — W/sr and W/m² — so only the luminous efficacy is divided back out, which
+			// is what Blender's own glTF importer does. Skipping it rendered every Blender lamp
+			// 683x too bright.
+			if ( ( object.isPointLight || object.isSpotLight ) && ! userData.__candelaConverted ) {
+
+				object.intensity /= LUMENS_PER_WATT;
+				userData.__candelaConverted = true;
 
 			}
 
-			// glTF punctual point/spot intensity is candela (W/sr); the engine's light
-			// model is Blender-style Power (W) that LightSerializer divides by 4π. Convert
-			// glTF candela → Power once at import (×4π) so it nets to the correct I/d².
-			// Directional (lux ≈ irradiance) is used directly and needs no conversion.
-			if ( ( object.isPointLight || object.isSpotLight ) && ! userData.__candelaConverted ) {
+			if ( object.isDirectionalLight && ! userData.__luxConverted ) {
 
-				object.intensity *= 4 * Math.PI;
-				userData.__candelaConverted = true;
+				object.intensity /= LUMENS_PER_WATT;
+				userData.__luxConverted = true;
 
 			}
 
-			// Process ceiling lights
-			if ( object.name.startsWith( 'RectAreaLightPlaceholder' ) &&
-				userData.name
-				// && userData.name.includes( "ceilingLight" )
-			) {
-
-				if ( userData.type === 'RectAreaLight' ) {
-
-					const normalize = userData.normalize ?? true;
-					const shape = userData.shape ?? 'rectangle';
-					const power = userData.intensity * areaLightPowerFactor( object, userData.width, userData.height, userData );
-					const light = new RectAreaLight(
-						new Color( ...userData.color ),
-						power * this._profile.areaLightIntensityScale,
-						userData.width,
-						userData.height
-					);
-					light.userData.normalize = normalize;
-					light.userData.spread = Number.isFinite( userData.spread ) ? userData.spread : Math.PI;
-					light.userData.shape = shape;
-					light.userData.__radianceConverted = true; // already power, and traverse() reaches it
-					light.name = userData.name;
-					object.add( light );
+			// An area light serialized into a placeholder node. Keyed on the record's own type
+			// rather than the node's name, so a renamed placeholder still lights the scene.
+			if ( userData.type === 'RectAreaLight' ) {
 
-				}
+				const light = areaLightFromPlaceholder( object, userData );
+				if ( ! light ) this._issues?.record(
+					ISSUE_CODES.LIGHT_PLACEHOLDER_INVALID,
+					`area-light placeholder "${object.name}" carries no usable size or intensity`,
+					{ node: object.name, record: userData },
+					ISSUE_SEVERITY.WARNING,
+				);
 
 			}
 

package/src/Processor/LightSerializer.js

@@ -1,10 +1,11 @@
 import { Vector3, Quaternion } from 'three';
 import { blackbodyToLinearRGB } from './blackbody.js';
+import { lightPower } from '../LightUnits.js';
 
-// Point & spot lights specify Power in Watts; the shader uses radiant intensity
-// (W/sr) as `intensity / dist²`, so convert with I = P / 4π (isotropic emitter),
-// matching Blender. Area lights are already radiant power; the Sun is irradiance.
-const INV_4PI = 1 / ( 4 * Math.PI );
+// Scene lights hold the three.js quantity in radiometric units (see LightUnits.js): point and
+// spot in W/sr, the Sun in W/m², area lights in radiance. The GPU buffer wants radiant intensity
+// for point/spot — already what they hold — and radiant POWER for area lights, which the shader
+// turns back into radiance with its own π·area. This is where that adaptation happens.
 
 // Effective emission colour + intensity after per-light Exposure (EV stops) and
 // optional blackbody Temperature tint (Blender-style). Both fold into the values
@@ -61,9 +62,10 @@ export class LightSerializer {
 
 	calculateLightImportance( light, type = 'directional' ) {
 
-		// Calculate luminance-weighted importance
+		// Ranked on Power, so the ordering does not shift when a light type's stored quantity
+		// differs from what the panel shows.
 		const luminance = 0.2126 * light.color.r + 0.7152 * light.color.g + 0.0722 * light.color.b;
-		let importance = light.intensity * luminance;
+		let importance = lightPower( light ) * luminance;
 
 		// Area lights get additional importance based on size
 		if ( type === 'area' ) {
@@ -172,6 +174,12 @@ export class LightSerializer {
 
 		const em = effectiveEmission( light );
 
+		// The shader recovers radiance as power/(π·area), so hand it the power that inverts to
+		// the radiance the light holds. Area is measured off u/v exactly as the shader does it.
+		const rectArea = 4 * u.clone().cross( v ).length();
+		const emittingArea = shape > 0.5 ? rectArea * Math.PI / 4 : rectArea;
+		const power = em.intensity * Math.PI * ( normalize > 0.5 ? emittingArea : 1 );
+
 		// Store in cache with importance (16 floats, vec4-aligned)
 		this.areaLightCache.push( {
 			data: [
@@ -179,7 +187,7 @@ export class LightSerializer {
 				u.x, u.y, u.z, // u half-vector (3)
 				v.x, v.y, v.z, // v half-vector (3)
 				em.r, em.g, em.b, // color (3) — incl. temperature tint
-				em.intensity, // radiant power in Watts (1) — incl. exposure
+				power, // radiant power in Watts (1) — incl. exposure
 				normalize, // power-normalize flag (1)
 				spread, // emission spread in radians (1)
 				shape, // 0 = rect, 1 = disk/ellipse (1)
@@ -209,7 +217,7 @@ export class LightSerializer {
 			data: [
 				position.x, position.y, position.z, // position (3)
 				em.r, em.g, em.b, // color (3) — incl. temperature tint
-				em.intensity * INV_4PI, // radiant intensity W/sr = power(W)/4π, incl. exposure (1)
+				em.intensity, // radiant intensity W/sr, incl. exposure (1)
 				light.distance || 0.0, // cutoff distance (0 = infinite) (1)
 				light.decay !== undefined ? light.decay : 2.0 // decay exponent (1)
 			],
@@ -252,7 +260,7 @@ export class LightSerializer {
 				position.x, position.y, position.z, // position (3)
 				direction.x, direction.y, direction.z, // direction (3)
 				em.r, em.g, em.b, // color (3) — incl. temperature tint
-				em.intensity * INV_4PI, // radiant intensity W/sr = power(W)/4π, incl. exposure (1)
+				em.intensity, // radiant intensity W/sr, incl. exposure (1)
 				light.angle || Math.PI / 4, // cone half-angle in radians (1)
 				light.penumbra || 0.0, // penumbra [0,1] (1)
 				light.distance || 0.0, // cutoff distance (0 = infinite) (1)