@plasius/gpu-renderer 0.2.48 → 0.2.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/gpu-renderer",
-  "version": "0.2.48",
+  "version": "0.2.49",
   "description": "Framework-agnostic WebGPU renderer runtime for Plasius projects.",
   "type": "module",
   "sideEffects": false,

package/src/index.d.ts

@@ -869,6 +869,7 @@ export interface WavefrontEnvironmentMapSnapshot {
 }
 
 export interface WavefrontPathTracingComputeConfig {
+  readonly progressive: boolean;
   readonly mode: typeof rendererWavefrontComputeMode;
   readonly width: number;
   readonly height: number;
@@ -1036,6 +1037,7 @@ export interface WavefrontPathTracingMemoryEstimate {
   readonly queuePairBytes: number;
   readonly hitBytes: number;
   readonly accumulationBytes: number;
+  readonly progressiveBytes: number;
   readonly pathVertexBytes: number;
   readonly sceneObjectBytes: number;
   readonly triangleBytes: number;
@@ -1097,6 +1099,8 @@ export interface WavefrontGpuParallelismDiagnostics {
 }
 
 export interface CreateWavefrontPathTracingComputeRendererOptions {
+  /** Accumulate linear radiance between frames until camera/scene/reset changes. Default false. */
+  readonly progressive?: boolean;
   readonly canvas?: HTMLCanvasElement | string;
   readonly navigator?: Navigator | { gpu?: GPU };
   readonly document?: Document;
@@ -1160,7 +1164,8 @@ export interface WavefrontPathTracingComputeRenderer {
   readonly device: GPUDevice;
   readonly format: GPUTextureFormat | string;
   readonly config: WavefrontPathTracingComputeConfig;
-  renderOnce(): WavefrontPathTracingComputeFrameStats;
+  renderOnce(options?: { samplesPerPixel?: number }): WavefrontPathTracingComputeFrameStats;
+  resetAccumulation(): void;
   renderFrame(options?: {
     readStats?: boolean;
     readOutputProbe?: boolean;
@@ -1182,6 +1187,8 @@ export interface WavefrontPathTracingComputeRenderer {
   updateSceneObjects(sceneObjects: readonly WavefrontSceneObjectInput[]): WavefrontPathTracingComputeConfig;
   updateCamera(camera: WavefrontCameraOptions): WavefrontPathTracingComputeConfig;
   getSnapshot(): Readonly<{
+    /** Submitted samples; await GPU completion before reporting completed progress. */
+    accumulatedSamplesPerPixel: number;
     frame: number;
     width: number;
     height: number;

package/src/wavefront-compute.js

@@ -1,3 +1,4 @@
+import { createWavefrontProgressiveResources } from './wavefront-progressive.js';
 import {
   createGpuParallelismCounters,
   createGpuParallelismDiagnostics,
@@ -299,7 +300,7 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
   const outputConfigSlotCount = config.deferredPathResolve ? 0 : tiles.length;
   const frameConfigSlotCount = Math.max(
     1,
-    tiles.length * config.samplesPerPixel + outputConfigSlotCount + (config.denoise ? 1 : 0)
+    tiles.length * config.samplesPerPixel + outputConfigSlotCount + (config.denoise || config.progressive ? 1 : 0)
   );
   const configBuffer = createBuffer(
     device,
@@ -369,7 +370,7 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     format: "rgba16float",
     usage:
       constants.texture.STORAGE_BINDING |
-      constants.texture.TEXTURE_BINDING,
+      constants.texture.TEXTURE_BINDING | constants.texture.COPY_DST,
   });
   const radianceView = radianceTexture.createView();
   const denoiseScratchTexture = device.createTexture({
@@ -563,10 +564,12 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     outputView,
     sampler,
   });
+  const progressive = await createWavefrontProgressiveResources({device, constants, config, configBuffer, radianceTexture, radianceView, outputView});
   let activeFrameTelemetry = null;
   let frameTelemetryResources = null;
   const frameEncoder = createWavefrontFrameEncoder({
     getConfig: () => config,
+    progressive,
     getBindGroups: () => bindGroups,
     pipelines,
     counterBuffer,
@@ -1022,6 +1025,7 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
   }
 
   function updateSceneObjects(sceneObjects) {
+    progressive?.reset();
     const nextPackedScene = packWavefrontSceneObjects(sceneObjects, config.sceneObjectCapacity);
     packedScene = nextPackedScene;
     const nextConfig = rebuildLiveConfig();
@@ -1034,6 +1038,7 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
   }
 
   function updateCamera(cameraOptions = {}) {
+    progressive?.reset();
     activeCameraOptions = cameraOptions;
     config = rebuildLiveConfig();
     return config;
@@ -1042,6 +1047,7 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
   function getSnapshot() {
     return Object.freeze({
       frame,
+      accumulatedSamplesPerPixel: progressive?.samples ?? 0,
       width: config.width,
       height: config.height,
       maxDepth: config.maxDepth,
@@ -1073,6 +1079,7 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
   }
 
   function destroy() {
+    progressive?.destroy();
     frameTelemetryResources?.destroy?.();
     activeQueue.destroy?.();
     nextQueue.destroy?.();
@@ -1138,6 +1145,7 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     readOutputProbe,
     updateSceneObjects,
     updateCamera,
+    resetAccumulation: () => progressive?.reset(),
     getSnapshot,
     destroy,
   });

package/src/wavefront-config.js

@@ -346,6 +346,7 @@ export function estimateWavefrontPathTracingMemory(options = {}) {
   const queueBytes = tilePixelCapacity * RAY_RECORD_BYTES;
   const hitBytes = tilePixelCapacity * HIT_RECORD_BYTES;
   const accumulationBytes = tilePixelCapacity * ACCUMULATION_RECORD_BYTES;
+  const progressiveBytes = options.progressive === true ? width * height * 16 + 16 : 0;
   const pathVertexBytes = tilePixelCapacity * (maxDepth + 1) * PATH_VERTEX_RECORD_BYTES;
   const sceneObjectBytes = sceneObjectCapacity * SCENE_OBJECT_RECORD_BYTES;
   const triangleBytes = allocatedRecordBytes(triangleCapacity, TRIANGLE_RECORD_BYTES);
@@ -372,7 +373,7 @@ export function estimateWavefrontPathTracingMemory(options = {}) {
   const outputConfigSlotCount = deferredPathResolve ? 0 : tileCount;
   const frameConfigSlotCount = Math.max(
     1,
-    tileCount * samplesPerPixel + outputConfigSlotCount + (denoise ? 1 : 0)
+    tileCount * samplesPerPixel + outputConfigSlotCount + (denoise || options.progressive === true ? 1 : 0)
   );
   const configBufferStride = alignByteSize(
     CONFIG_BUFFER_BYTES,
@@ -384,6 +385,7 @@ export function estimateWavefrontPathTracingMemory(options = {}) {
     1 + bvhSortStageCount + bvhBuildLevelCount
   ) * configBufferStride;
   const sceneStorageBufferBindingBytes = Math.max(
+    progressiveBytes,
     sceneObjectBytes,
     triangleBytes,
     bvhCombinedBytes,
@@ -397,6 +399,7 @@ export function estimateWavefrontPathTracingMemory(options = {}) {
     queueBytes * 2 +
     hitBytes +
     accumulationBytes +
+    progressiveBytes +
     pathVertexBytes +
     sceneObjectBytes +
     triangleBytes +
@@ -416,6 +419,7 @@ export function estimateWavefrontPathTracingMemory(options = {}) {
     queuePairBytes: queueBytes * 2,
     hitBytes,
     accumulationBytes,
+    progressiveBytes,
     pathVertexBytes,
     sceneObjectBytes,
     triangleBytes,
@@ -459,6 +463,7 @@ export function estimateWavefrontPathTracingMemoryForConfig(config, limits = {})
     bvhSortStageCount: config.bvhSortStages.length,
     bvhBuildLevelCount: config.bvhBuildLevels.length,
     denoise: config.denoise,
+    progressive: config.progressive,
     deferredPathResolve: config.deferredPathResolve,
     minUniformBufferOffsetAlignment:
       limits.minUniformBufferOffsetAlignment ??
@@ -587,10 +592,15 @@ export function createWavefrontPathTracingComputeConfig(options = {}) {
   );
   const deferredPathResolve = resolveDeferredPathResolve(options);
   const strictPhysicalLowSppLighting = resolveStrictPhysicalLowSppLighting(options);
-  const transportExperiments = resolveTransportExperiments(options, strictPhysicalLowSppLighting);
+  // Progressive batches require distinct frame seeds, even when static-frame
+  // sample routing was requested by a consumer.
+  const transportExperiments = resolveTransportExperiments(options.progressive === true
+    ? { ...options, "renderer.transport.stableSampleRouting.enabled": false }
+    : options, strictPhysicalLowSppLighting);
 
   return Object.freeze({
     mode: rendererWavefrontComputeMode,
+    progressive: options.progressive === true,
     width,
     height,
     maxDepth,
@@ -641,6 +651,7 @@ export function createWavefrontPathTracingComputeConfig(options = {}) {
       height,
       tileSize,
       samplesPerPixel,
+      progressive: options.progressive === true,
       tilePixelCapacity,
       maxDepth,
       sceneObjectCapacity,

package/src/wavefront-frame-dispatcher.js

@@ -46,17 +46,19 @@ export function dispatchWavefrontFrame({
       frameEncoder.encodeTileOutput(batch.reserve(1), tile, outputConfigOffset, parallelism);
     }
   }
-  if (config.denoise) {
+  if (config.denoise || config.progressive) {
+    const totalSamples = renderedSamplesPerPixel + frameEncoder.getAccumulatedSamples();
     const denoiseConfigOffset = writeFrameConfig(
       { x: 0, y: 0, width: config.width, height: config.height },
-      { sampleIndex: 0, sampleWeight: 1 / renderedSamplesPerPixel }
+      { sampleIndex: 0, sampleWeight: 1 / totalSamples }
     );
-    const denoisePassCount = renderedSamplesPerPixel < 4 ? 2 : 1;
+    if (config.progressive) frameEncoder.encodeProgressive(batch.reserve(1), denoiseConfigOffset, parallelism, renderedSamplesPerPixel);
+    const denoisePassCount = totalSamples < 4 ? 2 : 1;
     frameEncoder.encodeDenoise(
       batch.reserve(denoisePassCount),
       denoiseConfigOffset,
       parallelism,
-      renderedSamplesPerPixel
+      totalSamples
     );
   }
   frameEncoder.encodePresent(batch.reserve(1));
@@ -76,7 +78,7 @@ export function dispatchWavefrontFrameAwaitingGpu({
 }) {
   const samplePassesPerSample = config.maxDepth + 1 + (config.deferredPathResolve ? 1 : 0);
   const denoisePassCount = config.denoise ? (renderedSamplesPerPixel < 4 ? 2 : 1) : 0;
-  const tailPassCount = denoisePassCount + 1;
+  const tailPassCount = denoisePassCount + 1 + (config.progressive ? 1 : 0);
   const sampleBatchSize = Math.max(
     1,
     Math.floor(
@@ -161,19 +163,21 @@ export function dispatchWavefrontFrameAwaitingGpu({
       maxFramePassesPerSubmission: config.maxFramePassesPerSubmission,
       startingSubmissionCount: submissionCount,
     });
-    if (includeDenoise && config.denoise) {
+    if (includeDenoise && (config.denoise || config.progressive)) {
+      const totalSamples = renderedSamplesPerPixel + frameEncoder.getAccumulatedSamples();
       const denoiseConfigOffset = writeFrameConfigSlot(
         slot,
         { x: 0, y: 0, width: config.width, height: config.height },
         frameIndex,
-        { sampleIndex: 0, sampleWeight: 1 / renderedSamplesPerPixel }
+        { sampleIndex: 0, sampleWeight: 1 / totalSamples }
       );
       slot += 1;
+      if (config.progressive) frameEncoder.encodeProgressive(tail.reserve(1), denoiseConfigOffset, parallelism, renderedSamplesPerPixel);
       frameEncoder.encodeDenoise(
         tail.reserve(denoisePassCount),
         denoiseConfigOffset,
         parallelism,
-        renderedSamplesPerPixel
+        totalSamples
       );
     }
     if (includePresent) {

package/src/wavefront-frame-encoder.js

@@ -14,6 +14,7 @@ function resolveGetter(valueOrGetter) {
 
 export function createWavefrontFrameEncoder({
   getConfig,
+  progressive,
   getBindGroups,
   pipelines,
   counterBuffer,
@@ -30,6 +31,12 @@ export function createWavefrontFrameEncoder({
   const resolveBindGroups = resolveGetter(getBindGroups);
 
   return Object.freeze({
+    getAccumulatedSamples() { return progressive?.samples ?? 0; },
+    encodeProgressive(encoder, configOffset, parallelism, samples) {
+      progressive.encode(encoder, configOffset, samples);
+      const config = resolveConfig();
+      recordDirectDispatch(parallelism, [Math.ceil(config.width / 8), Math.ceil(config.height / 8)], WORKGROUP_SIZE);
+    },
     encodeTileSample(encoder, tile, configOffset, parallelism) {
       const config = resolveConfig();
       const bindGroups = resolveBindGroups();

package/src/wavefront-progressive-shader.js

@@ -0,0 +1,25 @@
+export const PROGRESSIVE_WGSL = `
+@group(0) @binding(45) var<storage, read_write> progressiveHistory: array<vec4<f32>>;
+@group(0) @binding(46) var<uniform> progressiveCounts: vec4<u32>;
+
+@compute @workgroup_size(8, 8)
+fn accumulateProgressiveRadiance(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= config.canvasWidth || id.y >= config.canvasHeight) { return; }
+  let pixel = vec2<i32>(id.xy);
+  let index = id.y * config.canvasWidth + id.x;
+  let batch = textureLoad(denoiseInputRadiance, pixel, 0).xyz;
+  let previousCount = f32(progressiveCounts.x);
+  let batchCount = f32(progressiveCounts.y);
+  // Branch explicitly: discarded history may contain non-finite values after a reset.
+  var mean = batch;
+  if (progressiveCounts.x > 0u) {
+    let previous = progressiveHistory[index].xyz;
+    mean = previous + (batch - previous) * (batchCount / (previousCount + batchCount));
+  }
+  progressiveHistory[index] = vec4<f32>(mean, 1.0);
+  textureStore(denoisedRadianceImage, pixel, vec4<f32>(mean, 1.0));
+  if (config.denoise == 0u) {
+    textureStore(denoisedOutputImage, pixel, vec4<f32>(present_radiance(mean), 1.0));
+  }
+}
+`;

package/src/wavefront-progressive.js

@@ -0,0 +1,46 @@
+import { CONFIG_BUFFER_BYTES } from './wavefront-core.js';
+import { createBuffer } from './wavefront-gpu-resources.js';
+import { assertShaderModuleCompiles, createComputePipeline } from './wavefront-runtime-support.js';
+import { WAVEFRONT_COMPUTE_WGSL } from './wavefront-shaders.js';
+import { PROGRESSIVE_WGSL } from './wavefront-progressive-shader.js';
+
+// Accumulate linear, unfiltered radiance. Presentation never feeds back into history.
+export async function createWavefrontProgressiveResources({device, constants, config,
+  configBuffer, radianceTexture, radianceView, outputView}) {
+  if (!config.progressive) return null;
+  const layout = device.createBindGroupLayout({entries:[
+    {binding:5,visibility:constants.shader.COMPUTE,buffer:{type:'uniform',hasDynamicOffset:true,minBindingSize:CONFIG_BUFFER_BYTES}},
+    {binding:14,visibility:constants.shader.COMPUTE,texture:{sampleType:'float'}},
+    {binding:15,visibility:constants.shader.COMPUTE,storageTexture:{access:'write-only',format:'rgba16float'}},
+    {binding:18,visibility:constants.shader.COMPUTE,storageTexture:{access:'write-only',format:'rgba8unorm'}},
+    {binding:45,visibility:constants.shader.COMPUTE,buffer:{type:'storage'}},
+    {binding:46,visibility:constants.shader.COMPUTE,buffer:{type:'uniform'}},
+  ]});
+  const shader=device.createShaderModule({label:'plasius.wavefront.progressiveShader',code:WAVEFRONT_COMPUTE_WGSL+PROGRESSIVE_WGSL});
+  await assertShaderModuleCompiles(shader,'plasius.wavefront.progressiveShader');
+  const pipeline=await createComputePipeline(device,shader,device.createPipelineLayout({bindGroupLayouts:[layout]}),
+    'accumulateProgressiveRadiance','plasius.wavefront.progressive');
+  const history=createBuffer(device,constants.buffer.STORAGE,config.width*config.height*16,'plasius.wavefront.progressiveHistory');
+  const counts=createBuffer(device,constants.buffer.UNIFORM|constants.buffer.COPY_DST,16,'plasius.wavefront.progressiveCounts');
+  const texture=device.createTexture({label:'plasius.wavefront.progressiveRadiance',size:{width:config.width,height:config.height},
+    format:'rgba16float',usage:constants.texture.STORAGE_BINDING|constants.texture.COPY_SRC});
+  const bindGroup=device.createBindGroup({layout,entries:[
+    {binding:5,resource:{buffer:configBuffer,size:CONFIG_BUFFER_BYTES}},
+    {binding:14,resource:radianceView},{binding:15,resource:texture.createView()},
+    {binding:18,resource:outputView},{binding:45,resource:{buffer:history}},{binding:46,resource:{buffer:counts}},
+  ]});
+  let samples=0;
+  return Object.freeze({
+    get samples(){return samples;},
+    reset(){samples=0;},
+    encode(encoder,offset,batchSamples){
+      device.queue.writeBuffer(counts,0,new Uint32Array([samples,batchSamples,0,0]));
+      const pass=encoder.beginComputePass({label:'plasius.wavefront.progressivePass'});
+      pass.setPipeline(pipeline);pass.setBindGroup(0,bindGroup,[offset]);
+      pass.dispatchWorkgroups(Math.ceil(config.width/8),Math.ceil(config.height/8));pass.end();
+      encoder.copyTextureToTexture({texture},{texture:radianceTexture},{width:config.width,height:config.height,depthOrArrayLayers:1});
+      samples+=batchSamples;
+    },
+    destroy(){history.destroy();counts.destroy();texture.destroy();},
+  });
+}