three-gpu-pathtracer 0.0.26 → 0.0.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-gpu-pathtracer",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "description": "Path tracing renderer and utilities for three.js built on top of three-mesh-bvh.",
   "module": "src/index.js",
   "main": "build/index.umd.cjs",
@@ -43,9 +43,9 @@
   "devDependencies": {
     "@lookingglass/webxr": "^0.6.0",
     "@monogrid/gainmap-js": "^3.0.5",
-    "@pmndrs/upscaler": "^0.2.0",
+    "@pmndrs/upscaler": "^0.3.0",
     "@types/node": "^24.3.1",
-    "@types/three": "^0.185.1",
+    "@types/three": "^0.186.0",
     "@typescript-eslint/eslint-plugin": "^8.40.0",
     "@vitejs/plugin-basic-ssl": "^2.3.0",
     "@webgpu/types": "^0.1.72",
@@ -56,22 +56,22 @@
     "jsdoc": "^4.0.5",
     "mediabunny": "^1.50.9",
     "node-fetch": "^3.2.9",
-    "oidn-web": "^0.4.0",
+    "oidn-webgpu": "^0.6.0",
     "pixelmatch": "^5.3.0",
     "pngjs": "^6.0.0",
     "process": "^0.11.10",
     "puppeteer": "^24.42.0",
     "rollup": "^2.70.0",
     "simple-git": "^3.10.0",
-    "three": "^0.185.1",
-    "three-mesh-bvh": "^0.9.15",
+    "three": "^0.187.0",
+    "three-mesh-bvh": "^0.9.17",
     "typescript": "^5.9.2",
     "vite": "^8.2.2",
     "yargs": "^17.5.1"
   },
   "peerDependencies": {
-    "three": ">=0.185.0",
-    "three-mesh-bvh": ">=0.9.15",
+    "three": ">=0.187.0",
+    "three-mesh-bvh": ">=0.9.17",
     "xatlas-web": "^0.1.0"
   },
   "scripts": {

package/src/core/PathTracingSceneGenerator.js

@@ -177,7 +177,7 @@ export class PathTracingSceneGenerator {
 		// generate the geometry
 		const result = staticGeometryGenerator.generate( geometry );
 		const materials = result.materials;
-		let needsMaterialIndexUpdate = result.changeType !== NO_CHANGE || this._materialUuids === null || this._materialUuids.length !== length;
+		let needsMaterialIndexUpdate = result.changeType !== NO_CHANGE || this._materialUuids === null || this._materialUuids.length !== materials.length;
 		if ( ! needsMaterialIndexUpdate ) {
 
 			for ( let i = 0, length = materials.length; i < length; i ++ ) {

package/src/core/utils/sceneUpdateUtils.js

@@ -78,7 +78,8 @@ export function getLights( scene ) {
 			c.isRectAreaLight ||
 			c.isSpotLight ||
 			c.isPointLight ||
-			c.isDirectionalLight
+			c.isDirectionalLight ||
+			c.isSunLight
 		) {
 
 			lights.push( c );

package/src/uniforms/EquirectHdrInfoUniform.js

@@ -1,4 +1,4 @@
-import { DataTexture, RedFormat, LinearFilter, DataUtils, HalfFloatType, Source, RepeatWrapping, RGBAFormat, FloatType, ClampToEdgeWrapping } from 'three';
+import { DataTexture, RedFormat, LinearFilter, DataUtils, HalfFloatType, TextureSource, RepeatWrapping, RGBAFormat, FloatType, ClampToEdgeWrapping } from 'three';
 import { toHalfFloatArray } from '../utils/TextureUtils.js';
 
 function binarySearchFindClosestIndexOf( array, targetValue, offset = 0, count = array.length ) {
@@ -42,7 +42,7 @@ function colorToLuminance( r, g, b ) {
 function preprocessEnvMap( envMap, targetType = HalfFloatType ) {
 
 	const map = envMap.clone();
-	map.source = new Source( { ...map.image } );
+	map.source = new TextureSource( { ...map.image } );
 	const { width, height, data } = map.image;
 
 	// TODO: is there a simple way to avoid cloning and adjusting the env map data here?
@@ -311,6 +311,8 @@ export class EquirectHdrInfoUniform {
 
 		this.totalSum = totalSumValue;
 		this.map = map;
+		this.cdfMarginal = cdfMarginal;
+		this.cdfConditional = cdfConditional;
 
 	}
 

package/src/uniforms/LightsInfoUniformStruct.js

@@ -2,6 +2,7 @@ import { DataTexture, RGBAFormat, ClampToEdgeWrapping, FloatType, Vector3, Quate
 import { bufferToHash } from '../utils/bufferToHash.js';
 
 const LIGHT_PIXELS = 6;
+const VISIBLE_TO_CAMERA_OFFSET = 11;
 const RECT_AREA_LIGHT = 0;
 const CIRC_AREA_LIGHT = 1;
 const SPOT_LIGHT = 2;
@@ -82,7 +83,7 @@ export class LightsInfoUniformStruct {
 
 				type = SPOT_LIGHT;
 
-			} else if ( l.isDirectionalLight ) {
+			} else if ( l.isDirectionalLight || l.isSunLight ) {
 
 				type = DIR_LIGHT;
 
@@ -207,8 +208,22 @@ export class LightsInfoUniformStruct {
 				floatArray[ baseIndex + ( index ++ ) ] = target.y;
 				floatArray[ baseIndex + ( index ++ ) ] = target.z;
 
+			} else if ( l.isSunLight ) {
+
+				// the sun has no target and shines from its position toward the origin
+				target.setFromMatrixPosition( l.matrixWorld ).normalize();
+
+				// sample 3
+				// u vector
+				floatArray[ baseIndex + ( index ++ ) ] = target.x;
+				floatArray[ baseIndex + ( index ++ ) ] = target.y;
+				floatArray[ baseIndex + ( index ++ ) ] = target.z;
+
 			}
 
+			// whether camera rays see the light
+			floatArray[ baseIndex + VISIBLE_TO_CAMERA_OFFSET ] = l.visibleToCameraRays ? 1 : 0;
+
 		}
 
 		this.count = lights.length;

package/src/webgpu/API.md

@@ -17,7 +17,7 @@ Uncorrelated pseudo random samples. Converges slowest but never shows structured
 RANDOM_SOBOL: Object
 ```
 
-Sobol low discrepancy samples, scrambled per pixel. Converges faster than `RANDOM_PCG`.
+Sobol low discrepancy samples, scrambled per pixel. Converges faster than `RANDOM_PCG`. The default.
 
 ### RANDOM_BLUE_DITHER
 
@@ -26,7 +26,7 @@ RANDOM_BLUE_DITHER: Object
 ```
 
 The same Sobol sequence for every pixel, offset by a blue noise dither so early frames read as
-smooth grain rather than clumped noise. The default.
+smooth grain rather than clumped noise.
 
 ## Transmissive Background Modes
 
@@ -143,7 +143,7 @@ Runs Open Image Denoise over a path traced image. Pass one to
 nor the network files become a dependency.
 
 ```js
-import { initUNetFromURL } from 'oidn-web';
+import { initUNetFromURL } from 'oidn-webgpu';
 pathTracer.setDenoiser( new OIDNDenoiser( { initUNetFromURL, auxWeightsUrl } ) );
 ```
 
@@ -151,6 +151,17 @@ Weights come from the oidn-weights repository, where the "_small" and "_large" v
 quality against download size and per tile cost.
 
 
+### events
+
+```js
+// Fired when a pass started by `update` fails, such as the weights failing to download, with the
+// failure as the event's `error`. No other pass starts until a reset.
+{ type: 'error' }
+
+// Fired as each tile of a pass finishes, with the fraction of the pass done as `progress`.
+{ type: 'progress' }
+```
+
 ### .texture
 
 ```js
@@ -210,20 +221,17 @@ init( renderer: WebGPURenderer ): void
 ```
 
 
-### .setScene
-
-```js
-setScene( scene: Scene, camera: Camera ): void
-```
-
-
 ### .update
 
 ```js
-update( target: Texture ): Texture | null
+update(
+	target: Texture,
+	aux = null: StorageArrayTexture | null
+): Texture | null
 ```
 
-Renders the auxiliary buffers and starts a pass. Safe to call every frame.
+Unpacks the auxiliary buffers the path tracer accumulated and starts a pass. Safe to call
+every frame.
 
 
 ### .denoise
@@ -261,6 +269,19 @@ the environment afterward require the matching `update*` function. Any change th
 the accumulated image restarts it.
 
 
+### events
+
+```js
+// Fired once every pixel has reached `maxSamples` and an attached denoiser has finished. Fires
+// again after a reset, or after `maxSamples` is raised, once the render has caught up.
+{ type: 'complete' }
+
+// Fired as the render advances. `stage` is "building", "compiling", "rendering" or "denoising", and
+// `progress` is the fraction of it done, or null when unknown. "rendering" also gives the sample
+// counts as `samples`, reported a few times a second.
+{ type: 'progress' }
+```
+
 ### .maxBounces
 
 ```js
@@ -277,20 +298,40 @@ resolve more indirect light at the cost of speed.
 frameBudget: number = 250000
 ```
 
-Number of path slots dispatched per [WebGPUPathTracer#renderSample](WebGPUPathTracer#renderSample) call,
+Number of path steps dispatched per [WebGPUPathTracer#renderSample](WebGPUPathTracer#renderSample) call,
 independent of resolution. Raising it trades frame rate for convergence speed.
 
 
+### .frameTime
+
+```js
+readonly frameTime: number
+```
+
+GPU time in milliseconds of a recent [WebGPUPathTracer#renderSample](WebGPUPathTracer#renderSample) call. Only measured
+when the renderer is created with `trackTimestamp: true`.
+
+
 ### .maxTransparentBounces
 
 ```js
-maxTransparentBounces: number = 5
+maxTransparentBounces: number = 15
 ```
 
 Maximum number of alpha tested surfaces a ray can pass through. Counted separately from
 [WebGPUPathTracer#maxBounces](WebGPUPathTracer#maxBounces) so foliage and cutouts cannot exhaust the bounce budget.
 
 
+### .maxSubsurfaceBounces
+
+```js
+maxSubsurfaceBounces: number = 256
+```
+
+Maximum number of scatter events a path can take inside a subsurface scattering volume. Counted
+separately from [WebGPUPathTracer#maxBounces](WebGPUPathTracer#maxBounces). Paths that reach it end, darkening dense volumes.
+
+
 ### .maxSamples
 
 ```js
@@ -303,6 +344,16 @@ render has stopped, so it has no effect while this is `0`.
 > [!NOTE]
 > `0` renders indefinitely.
 
+### .complete
+
+```js
+complete: boolean
+```
+
+Whether every pixel has reached [WebGPUPathTracer#maxSamples](WebGPUPathTracer#maxSamples) and an attached denoiser
+has finished, as of the last measurement. Always false while rendering indefinitely.
+
+
 ### .transmissiveBackground
 
 ```js
@@ -395,6 +446,17 @@ readonly lowResMode: boolean
 Whether the tracer is currently rendering the low resolution preview.
 
 
+### .compiling
+
+```js
+readonly compiling: boolean
+```
+
+Whether the kernels are compiling, such as after the scene or material changes. Nothing new
+renders until they finish and the canvas keeps the last frame, so an app may draw its own
+preview in the meantime.
+
+
 ### .textureAtlas
 
 ```js
@@ -410,13 +472,13 @@ The atlas every scene texture is packed into for the kernels to sample.
 minSamples: number = 1
 ```
 
-Samples every pixel must reach before the full resolution render is faded in.
+Average samples per pixel the full resolution render must reach before it is faded in.
 
 
 ### .renderDelay
 
 ```js
-renderDelay: number = 500
+renderDelay: number = 16
 ```
 
 Milliseconds to show the low resolution preview for after a reset.
@@ -425,7 +487,7 @@ Milliseconds to show the low resolution preview for after a reset.
 ### .fadeDuration
 
 ```js
-fadeDuration: number = 500
+fadeDuration: number = 250
 ```
 
 Milliseconds taken to cross fade from the preview to the full render.
@@ -446,7 +508,39 @@ Whether to render a low resolution preview while the camera is moving.
 lowResScale: number = 0.1
 ```
 
-Resolution of the low resolution preview, as a fraction of the render size.
+Resolution of the low resolution preview, as a fraction of the render size. Adjusted when
+[WebGPUPathTracer#adaptiveDynamicRes](WebGPUPathTracer#adaptiveDynamicRes) is set. The preview never has more pixels than a
+frame of [WebGPUPathTracer#frameBudget](WebGPUPathTracer#frameBudget) can render.
+
+
+### .adaptiveDynamicRes
+
+```js
+adaptiveDynamicRes: boolean = true
+```
+
+Whether [WebGPUPathTracer#lowResScale](WebGPUPathTracer#lowResScale) is adjusted to the pixels a frame of
+[WebGPUPathTracer#frameBudget](WebGPUPathTracer#frameBudget) can render.
+
+
+### .adaptiveFrameBudget
+
+```js
+adaptiveFrameBudget: boolean = true
+```
+
+Whether [WebGPUPathTracer#frameBudget](WebGPUPathTracer#frameBudget) is adjusted to keep each
+[WebGPUPathTracer#renderSample](WebGPUPathTracer#renderSample) call near [WebGPUPathTracer#targetFrameTime](WebGPUPathTracer#targetFrameTime) of
+GPU time. Requires a renderer created with `trackTimestamp: true`.
+
+
+### .targetFrameTime
+
+```js
+targetFrameTime: number = 16
+```
+
+GPU time in milliseconds per frame targeted by [WebGPUPathTracer#adaptiveFrameBudget](WebGPUPathTracer#adaptiveFrameBudget).
 
 
 ### .renderScale
@@ -469,6 +563,27 @@ Whether to track the canvas size automatically. Set to `false` to drive the rend
 size with [WebGPUPathTracer#setSize](WebGPUPathTracer#setSize).
 
 
+### .renderToCanvas
+
+```js
+renderToCanvas: boolean = true
+```
+
+Whether [WebGPUPathTracer#renderSample](WebGPUPathTracer#renderSample) draws the result to the current render
+target, the canvas by default. Set to `false` to only accumulate, as when baking to a
+texture read through [WebGPUPathTracer#target](WebGPUPathTracer#target).
+
+
+### .asyncCompile
+
+```js
+asyncCompile: boolean = false
+```
+
+Whether to compile the kernels asynchronously so a compile doesn't stall the page. Nothing
+new renders while [WebGPUPathTracer#compiling](WebGPUPathTracer#compiling) is true.
+
+
 ### .generateMissingAttributes
 
 ```js
@@ -539,7 +654,8 @@ setDenoiser( denoiser: OIDNDenoiser | null ): void
 ```
 
 Attaches a denoiser, run once the render settles and displayed in place of the raw image.
-Settings live on the instance. Pass null to remove it.
+Settings live on the instance. Pass null to remove it. The render restarts when the auxiliary
+buffers it needs are added or dropped.
 
 
 ### .setUpscaler
@@ -564,6 +680,28 @@ against. Call this once, then use the `update*` functions for later changes.
 > [!NOTE]
 > Geometry BVHs are built synchronously, so this blocks for large scenes.
 
+### .setBVHWorker
+
+```js
+setBVHWorker( WorkerConstructor: function ): void
+```
+
+Sets the worker class [WebGPUPathTracer#setSceneAsync](WebGPUPathTracer#setSceneAsync) builds the mesh geometry BVHs
+with, such as `GenerateMeshBVHWorker` from three-mesh-bvh. Several are created and disposed
+per call so geometries build in parallel.
+
+
+### .setSceneAsync
+
+```js
+async setSceneAsync( scene: Scene, camera: Camera ): Promise<void>
+```
+
+Like [WebGPUPathTracer#setScene](WebGPUPathTracer#setScene) but builds the mesh geometry BVHs in the workers set
+with [WebGPUPathTracer#setBVHWorker](WebGPUPathTracer#setBVHWorker) so the page is not blocked. Skinned meshes are
+still built synchronously.
+
+
 ### .setRandom
 
 ```js
@@ -708,6 +846,16 @@ Draws a heatmap of the per pixel sample counts, for spotting pixels that converg
 > Measures on every call and draws with the previous result, since the readback lands a
 >   frame later.
 
+### .renderAuxBuffer
+
+```js
+renderAuxBuffer( buffer = 'albedo': 'albedo' | 'normal' ): void
+```
+
+Draws the albedo or normal auxiliary buffer accumulated for the denoiser, for checking what
+it is given. Nothing is drawn until a denoiser that uses them is attached.
+
+
 ### .dispose
 
 ```js

package/src/webgpu/AtlasTexture.js

@@ -6,10 +6,11 @@ import {
 	NoBlending,
 	Color,
 	Vector4,
+	Matrix3,
 } from 'three/webgpu';
 
-const MAX_TEXTURE_SIZE = 4096;
 const _prevClearColor = new Color();
+const _prevMatrix = new Matrix3();
 
 function getTextureHash( texture ) {
 
@@ -241,9 +242,9 @@ export class AtlasTexture {
 
 		}
 
-		// calculate the maximum dimension of the atlas
+		// calculate the maximum dimension of the atlas, up to what the device allows
 		let maxDim = textures.reduce( ( v, t ) => Math.max( v, t.width, t.height ), 1 );
-		maxDim = Math.min( MAX_TEXTURE_SIZE, maxDim );
+		maxDim = Math.min( renderer.backend.device.limits.maxTextureDimension2D, maxDim );
 
 		const width = maxDim;
 		const height = maxDim;
@@ -438,21 +439,40 @@ export class AtlasTexture {
 		for ( let i = 0, l = textures.length; i < l; i ++ ) {
 
 			const { x, y, w, h, page } = placements[ i ];
-
-			// Clone the source so we get an independent texture handle
-			const texture = textures[ i ].clone();
-			texture.matrixAutoUpdate = false;
-			texture.matrix.identity();
-
-			quadMesh.material.map = texture;
+			const texture = textures[ i ];
 
 			// three.js uses the render target viewport / scissor
 			renderTarget.viewport.set( x, y, w, h );
 			renderTarget.scissor.set( x, y, w, h );
 			renderer.setRenderTarget( renderTarget, page );
-			quadMesh.render( renderer );
 
-			texture.dispose();
+			if ( texture.isRenderTargetTexture ) {
+
+				// a render target's content only lives on the GPU, so draw it directly
+				const prevAutoUpdate = texture.matrixAutoUpdate;
+				_prevMatrix.copy( texture.matrix );
+				texture.matrix.identity();
+				texture.matrixAutoUpdate = false;
+
+				quadMesh.material.map = texture;
+				quadMesh.render( renderer );
+
+				texture.matrixAutoUpdate = prevAutoUpdate;
+				texture.matrix.copy( _prevMatrix );
+
+			} else {
+
+				// Clone the source so we get an independent texture handle
+				const clone = texture.clone();
+				clone.matrixAutoUpdate = false;
+				clone.matrix.identity();
+
+				quadMesh.material.map = clone;
+				quadMesh.render( renderer );
+
+				clone.dispose();
+
+			}
 
 		}