@plasius/gpu-renderer 0.1.15 → 0.2.1

package/src/wavefront-compute.js

@@ -6,6 +6,9 @@ const DEFAULT_SAMPLES_PER_PIXEL = 1;
 const DEFAULT_SCENE_OBJECT_CAPACITY = 128;
 const DEFAULT_ENVIRONMENT_PORTAL_CAPACITY = 32;
 const WORKGROUP_SIZE = 64;
+export const rendererWavefrontComputeMode = "webgpu-compute";
+export const rendererWavefrontComputeWorkgroupSize = WORKGROUP_SIZE;
+export const rendererWavefrontComputeStatsStride = 8;
 const RAY_RECORD_BYTES = 80;
 const HIT_RECORD_BYTES = 208;
 const SCENE_OBJECT_RECORD_BYTES = 96;
@@ -18,7 +21,9 @@ const EMISSIVE_TRIANGLE_INDEX_BYTES = 4;
 const ENVIRONMENT_PORTAL_RECORD_BYTES = 96;
 const ACCUMULATION_RECORD_BYTES = 16;
 const CONFIG_BUFFER_BYTES = 272;
-const COUNTER_BUFFER_BYTES = 16;
+const COUNTER_DISPATCH_ARGS_OFFSET = 16;
+const INDIRECT_DISPATCH_ARGS_BYTES = 12;
+const COUNTER_BUFFER_BYTES = 32;
 const TRACE_STORAGE_BUFFER_BINDINGS = 9;
 const HIT_TYPE_SURFACE = 0;
 const HIT_TYPE_EMISSIVE = 1;
@@ -64,6 +69,8 @@ export const wavefrontPathTracingComputeLimits = Object.freeze({
   emissiveTriangleMetadataRecordBytes: BVH_NODE_RECORD_BYTES,
   environmentPortalRecordBytes: ENVIRONMENT_PORTAL_RECORD_BYTES,
   accumulationRecordBytes: ACCUMULATION_RECORD_BYTES,
+  counterRecordBytes: COUNTER_BUFFER_BYTES,
+  indirectDispatchRecordBytes: INDIRECT_DISPATCH_ARGS_BYTES,
 });
 
 export const wavefrontSceneObjectKinds = Object.freeze({
@@ -194,6 +201,33 @@ function normalize(value, fallback = [0, 0, 1]) {
   return [value[0] / length, value[1] / length, value[2] / length];
 }
 
+function hashUint32(value) {
+  let x = value >>> 0;
+  x = ((((x >>> 16) ^ x) >>> 0) * 0x45d9f3b) >>> 0;
+  x = ((((x >>> 16) ^ x) >>> 0) * 0x45d9f3b) >>> 0;
+  return ((x >>> 16) ^ x) >>> 0;
+}
+
+function mixSeed(pixelId, sampleId, bounce, frameIndex, dimension) {
+  let x =
+    ((pixelId >>> 0) * 747796405) ^
+    ((sampleId >>> 0) * 2891336453) ^
+    ((bounce >>> 0) * 277803737) ^
+    ((frameIndex >>> 0) * 1442695041) ^
+    ((dimension >>> 0) * 1597334677);
+  x >>>= 0;
+  x ^= x >>> 16;
+  x = (x * 0x7feb352d) >>> 0;
+  x ^= x >>> 15;
+  x = (x * 0x846ca68b) >>> 0;
+  x ^= x >>> 16;
+  return x >>> 0;
+}
+
+function random01FromSeed(seed) {
+  return (hashUint32(seed) & 0x00ffffff) / 16777215;
+}
+
 function getArrayLikeLength(value) {
   return Array.isArray(value) || ArrayBuffer.isView(value) ? value.length : 0;
 }
@@ -882,6 +916,36 @@ function resolveEnvironmentLighting(input, environmentColor, ambientColor) {
   });
 }
 
+function evaluateReferenceEnvironmentRadiance(config, origin, direction) {
+  void origin;
+  const rayDirection = normalize(direction, [0, 1, 0]);
+  const upFactor = clamp(rayDirection[1] * 0.5 + 0.5, 0, 1);
+  const sunDirection = normalize(
+    config.environmentLighting?.sunDirection ?? DEFAULT_ENVIRONMENT_LIGHTING.sunDirection,
+    DEFAULT_ENVIRONMENT_LIGHTING.sunDirection
+  );
+  const sunGlow = Math.pow(clamp(dot(rayDirection, sunDirection), 0, 1), 192);
+  const horizonColor =
+    config.environmentLighting?.horizonColor ?? DEFAULT_ENVIRONMENT_LIGHTING.horizonColor;
+  const zenithColor =
+    config.environmentLighting?.zenithColor ?? DEFAULT_ENVIRONMENT_LIGHTING.zenithColor;
+  const sunColor = config.environmentLighting?.sunColor ?? DEFAULT_ENVIRONMENT_LIGHTING.sunColor;
+  const intensity = Math.max(
+    0.0001,
+    Number(config.environmentLighting?.intensity ?? DEFAULT_ENVIRONMENT_LIGHTING.intensity)
+  );
+
+  return Object.freeze([
+    (horizonColor[0] * (1 - upFactor) + zenithColor[0] * upFactor + sunColor[0] * sunGlow) *
+      intensity,
+    (horizonColor[1] * (1 - upFactor) + zenithColor[1] * upFactor + sunColor[1] * sunGlow) *
+      intensity,
+    (horizonColor[2] * (1 - upFactor) + zenithColor[2] * upFactor + sunColor[2] * sunGlow) *
+      intensity,
+    1,
+  ]);
+}
+
 function resolveEnvironmentPortalMode(value, hasPortals) {
   if (value === undefined || value === null) {
     return hasPortals ? 2 : 0;
@@ -1099,6 +1163,7 @@ export function estimateWavefrontPathTracingMemory(options = {}) {
     environmentPortalBytes,
     configBytes: CONFIG_BUFFER_BYTES,
     counterBytes: COUNTER_BUFFER_BYTES,
+    indirectDispatchBytes: INDIRECT_DISPATCH_ARGS_BYTES,
     totalHotBufferBytes:
       queueBytes * 2 +
       hitBytes +
@@ -1110,7 +1175,8 @@ export function estimateWavefrontPathTracingMemory(options = {}) {
       emissiveTriangleMetadataBytes +
       environmentPortalBytes +
       CONFIG_BUFFER_BYTES +
-      COUNTER_BUFFER_BYTES,
+      COUNTER_BUFFER_BYTES +
+      INDIRECT_DISPATCH_ARGS_BYTES,
   });
 }
 
@@ -1212,6 +1278,7 @@ export function createWavefrontPathTracingComputeConfig(options = {}) {
   );
 
   return Object.freeze({
+    mode: rendererWavefrontComputeMode,
     width,
     height,
     maxDepth,
@@ -1272,6 +1339,9 @@ function getGpuUsageConstants() {
   ) {
     throw new Error("WebGPU runtime unavailable. Required GPU constants are missing.");
   }
+  if (typeof GPUBufferUsage.INDIRECT !== "number") {
+    throw new Error("WebGPU runtime unavailable. GPUBufferUsage.INDIRECT is missing.");
+  }
 
   return {
     buffer: GPUBufferUsage,
@@ -1489,6 +1559,229 @@ function createTiles(width, height, tileSize) {
   return Object.freeze(tiles);
 }
 
+function normalizeReferenceTile(config, tileInput = {}) {
+  const tileX = clamp(
+    readNonNegativeInteger("tile.x", tileInput.x, 0),
+    0,
+    Math.max(0, config.width - 1)
+  );
+  const tileY = clamp(
+    readNonNegativeInteger("tile.y", tileInput.y, 0),
+    0,
+    Math.max(0, config.height - 1)
+  );
+  const tileWidth = clamp(
+    readPositiveInteger("tile.width", tileInput.width, config.width - tileX),
+    1,
+    config.width - tileX
+  );
+  const tileHeight = clamp(
+    readPositiveInteger("tile.height", tileInput.height, config.height - tileY),
+    1,
+    config.height - tileY
+  );
+
+  return Object.freeze({
+    x: tileX,
+    y: tileY,
+    width: tileWidth,
+    height: tileHeight,
+  });
+}
+
+function repairReferenceShadingNormal(geometricNormal, shadingNormal) {
+  const normal = normalize(shadingNormal, geometricNormal);
+  return dot(normal, geometricNormal) < 0 ? scale(normal, -1) : normal;
+}
+
+function readOptionalMaxDistance(value) {
+  if (value === undefined || value === null) {
+    return Number.POSITIVE_INFINITY;
+  }
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric <= 0) {
+    throw new Error("maxDistance must be a positive finite number when provided.");
+  }
+  return numeric;
+}
+
+export function createWavefrontReferenceRay(config, options = {}) {
+  if (!config || typeof config !== "object") {
+    throw new Error("config must be a wavefront path tracing config.");
+  }
+
+  const tile = normalizeReferenceTile(config, options.tile);
+  const tilePixelCount = tile.width * tile.height;
+  const pixelIndex = readNonNegativeInteger("pixelIndex", options.pixelIndex, 0);
+  if (pixelIndex >= tilePixelCount) {
+    throw new Error(`pixelIndex ${pixelIndex} exceeds tile capacity ${tilePixelCount}.`);
+  }
+
+  const sampleIndex = readNonNegativeInteger("sampleIndex", options.sampleIndex, 0);
+  const frameIndex = readNonNegativeInteger("frameIndex", options.frameIndex, config.frameIndex ?? 0);
+  const jitterScale = clamp(readFiniteNumber("jitterScale", options.jitterScale, 0.35), 0, 1);
+  const localX = pixelIndex % tile.width;
+  const localY = Math.floor(pixelIndex / tile.width);
+  const pixelX = tile.x + localX;
+  const pixelY = tile.y + localY;
+  const sourcePixelId = pixelY * config.width + pixelX;
+  const jitterX = random01FromSeed(mixSeed(sourcePixelId, sampleIndex, 0, frameIndex, 1)) - 0.5;
+  const jitterY = random01FromSeed(mixSeed(sourcePixelId, sampleIndex, 0, frameIndex, 2)) - 0.5;
+  const ndcX = ((pixelX + 0.5 + jitterX * jitterScale) / config.width) * 2 - 1;
+  const ndcY = 1 - ((pixelY + 0.5 + jitterY * jitterScale) / config.height) * 2;
+  const viewX = ndcX * config.camera.tanHalfFovY * config.camera.aspect;
+  const viewY = ndcY * config.camera.tanHalfFovY;
+  const direction = normalize(
+    add(
+      add(config.camera.forward, scale(config.camera.right, viewX)),
+      scale(config.camera.up, viewY)
+    ),
+    config.camera.forward
+  );
+
+  return Object.freeze({
+    rayId: pixelIndex,
+    parentRayId: 0xffffffff,
+    sourcePixelId,
+    sampleId: sampleIndex,
+    bounce: 0,
+    mediumRefId: 0,
+    flags: 0,
+    origin: Object.freeze([...config.camera.position]),
+    direction: Object.freeze(direction),
+    throughput: Object.freeze([1, 1, 1, 1]),
+    pixelX,
+    pixelY,
+  });
+}
+
+export function intersectWavefrontReferenceTriangle(ray, triangle, options = {}) {
+  if (!ray || typeof ray !== "object") {
+    throw new Error("ray must be a wavefront reference ray.");
+  }
+  if (!triangle || typeof triangle !== "object") {
+    throw new Error("triangle must be a wavefront triangle record.");
+  }
+
+  const maxDistance = readOptionalMaxDistance(options.maxDistance);
+  const triangleIndex = readNonNegativeInteger("triangleIndex", options.triangleIndex, 0);
+  const edge1 = subtract(triangle.v1, triangle.v0);
+  const edge2 = subtract(triangle.v2, triangle.v0);
+  const pvec = cross(ray.direction, edge2);
+  const determinant = dot(edge1, pvec);
+  if (Math.abs(determinant) < 0.0000001) {
+    return null;
+  }
+
+  const invDet = 1 / determinant;
+  const tvec = subtract(ray.origin, triangle.v0);
+  const u = dot(tvec, pvec) * invDet;
+  if (u < 0 || u > 1) {
+    return null;
+  }
+
+  const qvec = cross(tvec, edge1);
+  const v = dot(ray.direction, qvec) * invDet;
+  if (v < 0 || u + v > 1) {
+    return null;
+  }
+
+  const distance = dot(edge2, qvec) * invDet;
+  if (distance <= 0.001 || distance > maxDistance) {
+    return null;
+  }
+
+  const geometric = normalize(cross(edge1, edge2), [0, 1, 0]);
+  const frontFace = dot(ray.direction, geometric) < 0;
+  const orientedGeometric = frontFace ? geometric : scale(geometric, -1);
+  const w = 1 - u - v;
+  const interpolated = [
+    triangle.n0[0] * w + triangle.n1[0] * u + triangle.n2[0] * v,
+    triangle.n0[1] * w + triangle.n1[1] * u + triangle.n2[1] * v,
+    triangle.n0[2] * w + triangle.n1[2] * u + triangle.n2[2] * v,
+  ];
+  const shadingNormal = repairReferenceShadingNormal(orientedGeometric, interpolated);
+  const uv = [
+    triangle.uv0[0] * w + triangle.uv1[0] * u + triangle.uv2[0] * v,
+    triangle.uv0[1] * w + triangle.uv1[1] * u + triangle.uv2[1] * v,
+  ];
+  const position = add(ray.origin, scale(ray.direction, distance));
+
+  return Object.freeze({
+    hitType: "surface",
+    rayId: ray.rayId,
+    sourcePixelId: ray.sourcePixelId,
+    distance,
+    entityId: triangle.meshId,
+    instanceId: 0,
+    primitiveId: triangle.triangleId,
+    materialId: triangle.materialKind,
+    materialRefId: triangle.materialRefId,
+    mediumRefId: triangle.mediumRefId,
+    barycentrics: Object.freeze([w, u, v]),
+    uv: Object.freeze(uv),
+    geometricNormal: Object.freeze(orientedGeometric),
+    shadingNormal: Object.freeze(shadingNormal),
+    frontFace,
+    triangleIndex,
+    triangleId: triangle.triangleId,
+    position: Object.freeze(position),
+    color: triangle.color,
+    emission: triangle.emission,
+    material: triangle.material,
+  });
+}
+
+function createWavefrontReferenceEnvironmentHit(config, ray) {
+  const radiance = evaluateReferenceEnvironmentRadiance(config, ray.origin, ray.direction);
+  return Object.freeze({
+    hitType: "environment",
+    rayId: ray.rayId,
+    sourcePixelId: ray.sourcePixelId,
+    distance: -1,
+    entityId: 0,
+    instanceId: 0,
+    primitiveId: 0,
+    materialId: 0,
+    materialRefId: 0,
+    mediumRefId: 0,
+    barycentrics: Object.freeze([0, 0, 0]),
+    uv: Object.freeze([0, 0]),
+    geometricNormal: Object.freeze(scale(ray.direction, -1)),
+    shadingNormal: Object.freeze(scale(ray.direction, -1)),
+    frontFace: true,
+    triangleIndex: -1,
+    triangleId: -1,
+    position: Object.freeze(add(ray.origin, scale(ray.direction, 1000))),
+    color: Object.freeze([0, 0, 0, 0]),
+    emission: radiance,
+    material: Object.freeze([1, 0, 1, 1]),
+  });
+}
+
+export function traceWavefrontReferenceTriangles(config, ray, triangles, options = {}) {
+  if (!config || typeof config !== "object") {
+    throw new Error("config must be a wavefront path tracing config.");
+  }
+
+  const source = Array.isArray(triangles) ? triangles : [];
+  let nearestHit = null;
+  let nearestDistance = readOptionalMaxDistance(options.maxDistance);
+
+  source.forEach((triangle, index) => {
+    const hit = intersectWavefrontReferenceTriangle(ray, triangle, {
+      maxDistance: Number.isFinite(nearestDistance) ? nearestDistance : undefined,
+      triangleIndex: index,
+    });
+    if (hit && hit.distance < nearestDistance) {
+      nearestDistance = hit.distance;
+      nearestHit = hit;
+    }
+  });
+
+  return nearestHit ?? createWavefrontReferenceEnvironmentHit(config, ray);
+}
+
 function clampTileSizeForDevice(config, device) {
   const limit = Number(device?.limits?.maxStorageBufferBindingSize);
   if (!Number.isFinite(limit) || limit <= 0) {
@@ -1738,6 +2031,10 @@ struct Counters {
   nextCount: atomic<u32>,
   terminatedCount: atomic<u32>,
   hitCount: atomic<u32>,
+  dispatchX: u32,
+  dispatchY: u32,
+  dispatchZ: u32,
+  dispatchPad: u32,
 };
 
 struct Candidate {
@@ -1900,6 +2197,18 @@ fn gated_environment_radiance(origin: vec3<f32>, direction: vec3<f32>) -> vec3<f
   return environment_radiance(origin, direction);
 }
 
+fn terminal_surface_environment_contribution(ray: RayRecord, hit: HitRecord) -> vec3<f32> {
+  let normal = safe_normalize(hit.shadingNormal.xyz, vec3<f32>(0.0, 1.0, 0.0));
+  let surfaceColor = max(hit.color.xyz, config.ambientColor.xyz);
+  let normalEnvironment = gated_environment_radiance(
+    hit.position.xyz + normal * 0.003,
+    normal
+  );
+  let environmentFloor = max(config.ambientColor.xyz, normalEnvironment * 0.12);
+  let materialFloor = select(0.7, 1.0, hit.materialKind == 0u || hit.materialKind == 3u);
+  return clamp_sample_radiance(ray.throughput.xyz * surfaceColor * environmentFloor * materialFloor);
+}
+
 fn default_mesh_range() -> MeshRange {
   return MeshRange(
     0u,
@@ -2471,6 +2780,17 @@ fn tone_map_radiance(value: vec3<f32>) -> vec3<f32> {
   return pow(clamp(mapped, vec3<f32>(0.0), vec3<f32>(1.0)), vec3<f32>(1.0 / 2.2));
 }
 
+fn ray_workgroups_for_count(rayCount: u32) -> u32 {
+  return max(1u, (rayCount + 63u) / 64u);
+}
+
+fn write_active_dispatch_args(activeCount: u32) {
+  counters.dispatchX = ray_workgroups_for_count(activeCount);
+  counters.dispatchY = 1u;
+  counters.dispatchZ = 1u;
+  counters.dispatchPad = 0u;
+}
+
 fn denoise_range_space(value: vec3<f32>) -> vec3<f32> {
   return value / (vec3<f32>(1.0) + value);
 }
@@ -2483,6 +2803,7 @@ fn generatePrimaryRays(@builtin(global_invocation_id) globalId: vec3<u32>) {
     atomicStore(&counters.nextCount, 0u);
     atomicStore(&counters.terminatedCount, 0u);
     atomicStore(&counters.hitCount, 0u);
+    write_active_dispatch_args(config.tilePixelCount);
   }
   if (index >= config.tilePixelCount) {
     return;
@@ -2758,9 +3079,9 @@ fn resolveSurfaceRecords(@builtin(global_invocation_id) globalId: vec3<u32>) {
   }
 
   if (ray.bounce + 1u >= config.maxDepth) {
+    let terminalEnvironment = terminal_surface_environment_contribution(ray, hit);
     accumulation[ray.rayId] =
-      accumulation[ray.rayId] +
-      vec4<f32>(ray.throughput.xyz * config.ambientColor.xyz * sample_weight(), 1.0);
+      accumulation[ray.rayId] + vec4<f32>(terminalEnvironment * sample_weight(), 1.0);
     atomicAdd(&counters.terminatedCount, 1u);
     return;
   }
@@ -2769,6 +3090,10 @@ fn resolveSurfaceRecords(@builtin(global_invocation_id) globalId: vec3<u32>) {
   let scatter = scatter_direction(ray, hit, seed);
   let nextIndex = atomicAdd(&counters.nextCount, 1u);
   if (nextIndex >= config.tilePixelCount) {
+    let overflowEnvironment = terminal_surface_environment_contribution(ray, hit);
+    accumulation[ray.rayId] =
+      accumulation[ray.rayId] + vec4<f32>(overflowEnvironment * sample_weight(), 1.0);
+    atomicAdd(&counters.terminatedCount, 1u);
     return;
   }
   let color = clamp(hit.color.xyz, vec3<f32>(0.0), vec3<f32>(1.0));
@@ -2797,8 +3122,10 @@ fn compactAndSwapQueues(@builtin(global_invocation_id) globalId: vec3<u32>) {
     return;
   }
   let nextCount = atomicLoad(&counters.nextCount);
-  atomicStore(&counters.activeCount, min(nextCount, config.tilePixelCount));
+  let activeCount = min(nextCount, config.tilePixelCount);
+  atomicStore(&counters.activeCount, activeCount);
   atomicStore(&counters.nextCount, 0u);
+  write_active_dispatch_args(activeCount);
 }
 
 @compute @workgroup_size(64)
@@ -3093,10 +3420,16 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
   );
   const counterBuffer = createBuffer(
     device,
-    constants.buffer.STORAGE | constants.buffer.COPY_DST,
+    constants.buffer.STORAGE | constants.buffer.COPY_DST | constants.buffer.COPY_SRC,
     COUNTER_BUFFER_BYTES,
     "plasius.wavefront.counters"
   );
+  const activeDispatchBuffer = createBuffer(
+    device,
+    constants.buffer.INDIRECT | constants.buffer.COPY_DST,
+    INDIRECT_DISPATCH_ARGS_BYTES,
+    "plasius.wavefront.activeDispatchArgs"
+  );
 
   let packedScene = packWavefrontSceneObjects(config.sceneObjects, config.sceneObjectCapacity);
   device.queue.writeBuffer(sceneObjectBuffer, 0, packedScene.buffer);
@@ -3538,27 +3871,36 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
   }
 
   function encodeTileSample(encoder, tile, configOffset) {
-    const passEncoder = encoder.beginComputePass({
-      label: "plasius.wavefront.computePass",
+    const generatePass = encoder.beginComputePass({
+      label: "plasius.wavefront.generatePrimaryRaysPass",
     });
     const tileWorkgroups = Math.ceil((tile.width * tile.height) / WORKGROUP_SIZE);
-    const capacityWorkgroups = Math.ceil(config.tilePixelCapacity / WORKGROUP_SIZE);
 
-    passEncoder.setBindGroup(0, bindGroups[0], [configOffset]);
-    passEncoder.setPipeline(pipelines.generatePrimaryRays);
-    passEncoder.dispatchWorkgroups(tileWorkgroups);
+    generatePass.setBindGroup(0, bindGroups[0], [configOffset]);
+    generatePass.setPipeline(pipelines.generatePrimaryRays);
+    generatePass.dispatchWorkgroups(tileWorkgroups);
+    generatePass.end();
 
     for (let bounceIndex = 0; bounceIndex < config.maxDepth; bounceIndex += 1) {
+      encoder.copyBufferToBuffer(
+        counterBuffer,
+        COUNTER_DISPATCH_ARGS_OFFSET,
+        activeDispatchBuffer,
+        0,
+        INDIRECT_DISPATCH_ARGS_BYTES
+      );
+      const passEncoder = encoder.beginComputePass({
+        label: `plasius.wavefront.bounce.${bounceIndex}`,
+      });
       passEncoder.setBindGroup(0, bindGroups[bounceIndex % 2], [configOffset]);
       passEncoder.setPipeline(pipelines.intersectActiveQueue);
-      passEncoder.dispatchWorkgroups(capacityWorkgroups);
+      passEncoder.dispatchWorkgroupsIndirect(activeDispatchBuffer, 0);
       passEncoder.setPipeline(pipelines.resolveSurfaceRecords);
-      passEncoder.dispatchWorkgroups(capacityWorkgroups);
+      passEncoder.dispatchWorkgroupsIndirect(activeDispatchBuffer, 0);
       passEncoder.setPipeline(pipelines.compactAndSwapQueues);
       passEncoder.dispatchWorkgroups(1);
+      passEncoder.end();
     }
-
-    passEncoder.end();
   }
 
   function encodeTileOutput(encoder, tile, configOffset) {
@@ -3710,6 +4052,32 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     });
   }
 
+  async function renderFrame(renderOptions = {}) {
+    const frameStats = renderOnce();
+    const probe =
+      renderOptions.readOutputProbe === false ? null : await readOutputProbe(renderOptions.probe);
+    const maxChannel = probe ? Math.max(...probe.rgba.slice(0, 3)) : 0;
+    return Object.freeze({
+      ...frameStats,
+      outputProbe: probe
+        ? Object.freeze({
+            ...probe,
+            sampledPixels: 1,
+            nonZeroSamples: maxChannel > 0 ? 1 : 0,
+            maxChannel,
+          })
+        : null,
+      bounces: [],
+      termination: Object.freeze({
+        emissive: 0,
+        environment: 0,
+        ambientFallback: 0,
+        maxDepth: 0,
+      }),
+      queueOverflow: 0,
+    });
+  }
+
   function updateSceneObjects(sceneObjects) {
     const nextPackedScene = packWavefrontSceneObjects(sceneObjects, config.sceneObjectCapacity);
     packedScene = nextPackedScene;
@@ -3770,6 +4138,7 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     configBuffer.destroy?.();
     bvhBuildConfigBuffer.destroy?.();
     counterBuffer.destroy?.();
+    activeDispatchBuffer.destroy?.();
     radianceTexture.destroy?.();
     denoiseScratchTexture.destroy?.();
     outputTexture.destroy?.();
@@ -3783,9 +4152,31 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     format,
     config,
     renderOnce,
+    renderFrame,
     readOutputProbe,
     updateSceneObjects,
     getSnapshot,
     destroy,
   });
 }
+
+export async function renderWavefrontPathTracingComputeFrame(options = {}) {
+  const renderer = await createWavefrontPathTracingComputeRenderer(options);
+  try {
+    return await renderer.renderFrame(options);
+  } finally {
+    renderer.destroy();
+  }
+}
+
+export function createWavefrontPathTracingComputeShaderSource(options = {}) {
+  const workgroupSize = readPositiveInteger(
+    "workgroupSize",
+    options.workgroupSize ?? rendererWavefrontComputeWorkgroupSize,
+    rendererWavefrontComputeWorkgroupSize
+  );
+  if (workgroupSize !== rendererWavefrontComputeWorkgroupSize) {
+    throw new Error(`wavefront mesh compute currently requires workgroupSize=${rendererWavefrontComputeWorkgroupSize}.`);
+  }
+  return WAVEFRONT_COMPUTE_WGSL;
+}