Skip to content

3D engine that AI agents drive

31.0 KB
Raw Blame
import { buildMegakernelSource, PATH_STATE_VECTORS, WAVEFRONT_SOURCE, WAVEFRONT_WORKGROUP_SIZE, WORKGROUP_SIZE } from './path-tracer-webgpu-kernel.js';
import { resolveLightSelection } from './path-tracer-light-tree.js';
import { gpuTriangleCapacity, packAtlas, packEnvironment, packLightTree, packLights, packMaterials, packNodes, packSubsurface, packTriangles, sceneUsesSubsurface } from './path-tracer-gpu-pack.js';
import { WEBGPU_INSTANCE_VECTORS } from './path-tracer-webgpu-instancing.js';
import { packInstancedScene } from './path-tracer-gpu-instance-pack.js';
import { isInstancedScene, MAX_GPU_TRACE_TRIANGLES, MAX_TRACE_TRIANGLES, uniqueTriangleCount } from './path-tracer-scene.js';
import { assertWebGpuLocalVolumes, packWebGpuLocalVolumes, webGpuVolumeFeatures } from './path-tracer-webgpu-local-volumes.js';

// The WebGPU backend of the path tracer (issue #625): the same scene tables, camera, options and random numbers as the
// WebGL2 backend (path-tracer-gpu.js) go in, the same buffers come out. The tracer is WGSL compute, so a page needs
// navigator.gpu; without it traceOnWebGpu throws and the caller falls back to the "gpu" or "cpu" backend. Volume fog and
// subsurface scattering compile into the megakernel only for a scene that uses them, and traceTexelsOnWebGpu is the texel
// entry of the light bake (light-bake-gpu.js). The wavefront kernel traces neither fog nor subsurface.

/** `megakernel`: one invocation per path (the default, faster on the demo room). `wavefront`: generate, extend, shade, shadow kernels with the path state in a buffer. */
const PORTAL_FLOATS = 16;

// One portal as the kernel reads it: position, width, normal, height, across, along, each vector padded to four floats.
function packPortal(portal) {
  return Float32Array.of(...portal.position, portal.width, ...portal.normal, portal.height, ...portal.across, 0, ...portal.along, 0);
}

export const WEBGPU_KERNELS = ['megakernel', 'wavefront'];
export const DEFAULT_WEBGPU_KERNEL = 'megakernel';
/** Whether the wavefront bins the hits by material before shading them (decided by the measurement in docs/webgpu-decision.md). */
export const DEFAULT_SORT_BY_MATERIAL = false;

const PARAMETER_BYTES = 17 * 16;
// Dynamic uniform offsets must be a multiple of minUniformBufferOffsetAlignment, which is 256 on every adapter; a slot holds the parameter block.
const PARAMETER_SLOT_BYTES = 512;
const STORAGE_BUFFER_COUNT = 10;
const MAXIMUM_TILE_PATHS = 1 << 19;
// The path state of one tile stays under the default maxStorageBufferBindingSize.
const MAXIMUM_STATE_BYTES = 1 << 27;
const MAXIMUM_BUFFER_BYTES = 1 << 30;
const WAVEFRONT_ENTRY_POINTS = ['generatePaths', 'resetBins', 'extendPaths', 'scanBins', 'scatterPaths', 'shadePaths', 'shadowPaths', 'resolvePaths'];

/** True when this page has WebGPU. Whether an adapter exists is only known after requesting one. */
export function isWebGpuTracerAvailable() {
  return typeof navigator !== 'undefined' && Boolean(navigator.gpu);
}

let session = null;
let kernelCompileCount = 0;

/** How many path tracing kernels this page has compiled so far: a job of many frames compiles each kernel once. */
export function webGpuKernelCompileCount() {
  return kernelCompileCount;
}

async function createSession() {
  if (!isWebGpuTracerAvailable()) {
    throw new Error('The WebGPU path tracer needs navigator.gpu, which this page does not have. Use backend "gpu" (WebGL2) or "cpu".');
  }
  const adapter = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' });
  if (!adapter) throw new Error('The WebGPU path tracer found no WebGPU adapter. Use backend "gpu" (WebGL2) or "cpu".');
  if (adapter.limits.maxStorageBuffersPerShaderStage < STORAGE_BUFFER_COUNT) {
    throw new Error(`The WebGPU path tracer needs ${STORAGE_BUFFER_COUNT} storage buffers per shader stage and this adapter allows ${adapter.limits.maxStorageBuffersPerShaderStage}. Use backend "gpu".`);
  }
  const device = await adapter.requestDevice({
    requiredLimits: {
      maxStorageBuffersPerShaderStage: STORAGE_BUFFER_COUNT,
      maxStorageBufferBindingSize: Math.min(adapter.limits.maxStorageBufferBindingSize, MAXIMUM_BUFFER_BYTES),
      maxBufferSize: Math.min(adapter.limits.maxBufferSize, MAXIMUM_BUFFER_BYTES),
    },
  });
  const entries = [{ binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: PARAMETER_BYTES } }];
  for (let binding = 1; binding < STORAGE_BUFFER_COUNT + 1; binding++) {
    entries.push({ binding, visibility: GPUShaderStage.COMPUTE, buffer: { type: binding <= 7 ? 'read-only-storage' : 'storage' } });
  }
  const bindGroupLayout = device.createBindGroupLayout({ entries });
  const info = adapter.info ?? {};
  return {
    device, bindGroupLayout, pipelineLayout: device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] }),
    gpu: `${info.vendor ?? 'webgpu'} ${info.architecture ?? ''}`.trim(), kernels: new Map(),
  };
}

async function getSession() {
  session ??= createSession().catch((error) => {
    session = null;
    throw error;
  });
  return session;
}

/** The WGSL and entry points of a kernel variant; a variant is one of the two kernels, with the optional parts a scene needs. */
function describeVariant({ kernel, hasVolume, hasLocalVolumes, hasGridVolume, hasNoiseOctaves, hasEmissionRamp, hasMeshVolume, hasSubsurface, texelBake, realtime, instanced = false }) {
  if (kernel === 'wavefront') return { code: WAVEFRONT_SOURCE, entryPoints: WAVEFRONT_ENTRY_POINTS };
  if (realtime) return { code: buildMegakernelSource({ hasVolume, hasLocalVolumes, hasGridVolume, hasNoiseOctaves, hasEmissionRamp, hasMeshVolume, hasSubsurface, realtime, instanced }), entryPoints: ['traceRealtime'] };
  return { code: buildMegakernelSource({ hasVolume, hasLocalVolumes, hasGridVolume, hasNoiseOctaves, hasEmissionRamp, hasMeshVolume, hasSubsurface, texelBake, instanced }), entryPoints: [texelBake ? 'bakeTexels' : 'main'] };
}

async function compileKernel(current, variant) {
  const { device, pipelineLayout } = current;
  const started = performance.now();
  const { code, entryPoints } = describeVariant(variant);
  const module = device.createShaderModule({ label: `path tracer ${variant.kernel}`, code });
  const info = await module.getCompilationInfo();
  const errors = info.messages.filter(message => message.type === 'error');
  if (errors.length > 0) throw new Error(`The WebGPU path tracer shader did not compile: ${errors.slice(0, 8).map(message => `${message.lineNum}: ${message.message}`).join('; ')}`);
  const pipelines = await Promise.all(entryPoints.map(entryPoint => device.createComputePipelineAsync({ layout: pipelineLayout, compute: { module, entryPoint } })));
  kernelCompileCount++;
  return { pipelines: Object.fromEntries(entryPoints.map((entryPoint, index) => [entryPoint, pipelines[index]])), compileSeconds: (performance.now() - started) / 1000 };
}

async function getKernel(current, variant) {
  const key = [variant.kernel, variant.hasVolume, variant.hasLocalVolumes, variant.hasGridVolume, variant.hasNoiseOctaves, variant.hasEmissionRamp, variant.hasMeshVolume, variant.hasSubsurface, variant.texelBake, Boolean(variant.realtime), Boolean(variant.instanced)].join(':');
  if (!current.kernels.has(key)) current.kernels.set(key, compileKernel(current, variant));
  return current.kernels.get(key);
}

/** The optional parts the scene needs, as the kernel variant flags. */
function sceneFeatures(scene) {
  return { hasVolume: Boolean(scene.volume), hasLocalVolumes: Boolean(scene.localVolumes), ...webGpuVolumeFeatures(scene.localVolumes), hasSubsurface: sceneUsesSubsurface(scene.materials), texelBake: false, instanced: isInstancedScene(scene) };
}

function createStorageBuffer(device, data, label) {
  const bytes = new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
  const buffer = device.createBuffer({ label, size: Math.max(16, Math.ceil(bytes.byteLength / 4) * 4), usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
  device.queue.writeBuffer(buffer, 0, bytes);
  return buffer;
}

function atlasWords(atlas) {
  return new Uint32Array(atlas.data.buffer, atlas.data.byteOffset, Math.floor(atlas.data.byteLength / 4));
}

/**
 * The node and triangle tables of a scene. A flat scene has one BVH over all its triangles. An instanced scene holds each distinct mesh
 * once (path-tracer-gpu-instance-pack.js); its instance records follow the nodes in the same buffer, behind a header vector that names
 * the top-level root, so the binding count stays what the flat scene uses. `instanceHeader` is the vector index of that header, 0 for a flat scene.
 */
function packGeometryTables(device, scene) {
  if (!isInstancedScene(scene)) return { nodeTable: packNodes(scene.bvh), triangleData: packTriangles(scene, { secondUvSet: true }).data, instanceHeader: 0 };
  const packed = packInstancedScene(scene);
  const nodeFloats = packed.nodes.data.length;
  const recordFloats = scene.instances.length * WEBGPU_INSTANCE_VECTORS * 4;
  const data = new Float32Array(nodeFloats + 4 + recordFloats);
  data.set(packed.nodes.data);
  data[nodeFloats] = packed.topRoot;
  data.set(packed.instances.data.subarray(0, recordFloats), nodeFloats + 4);
  const limit = device.limits.maxStorageBufferBindingSize;
  if (data.byteLength > limit) {
    throw new RangeError(`The instanced scene needs ${data.byteLength} bytes for its BVH nodes and ${scene.instances.length} instance records, and this WebGPU adapter binds at most ${limit} bytes in one storage buffer. Remove copies or merge small meshes, or use backend "gpu".`);
  }
  return { nodeTable: { data }, triangleData: packed.triangles.data, instanceHeader: nodeFloats / 4 };
}

export function uploadScene(device, scene, requestedLightSelection = 'uniform') {
  const atlas = packAtlas(scene.materials);
  const lights = packLights(scene.lights);
  // With the light tree the node table follows the light table in the same buffer; treeBase is the vector index of its first node.
  const useLightTree = resolveLightSelection(requestedLightSelection, scene.lights) === 'tree' && lights.count > 1;
  const lightTableData = lights.table.data;
  const lightTreeBase = useLightTree ? lightTableData.length / 4 : 0;
  const lightTreeData = useLightTree ? packLightTree(scene.lights).data : new Float32Array(0);
  const lightsWithTree = new Float32Array(lightTableData.length + lightTreeData.length);
  lightsWithTree.set(lightTableData);
  lightsWithTree.set(lightTreeData, lightTableData.length);
  const environment = packEnvironment(scene.environment);
  // The portals follow the map's tables, with their count in the last float (path-tracer-webgpu-kernel.js, light portals).
  const portals = environment ? scene.lights.portals ?? [] : [];
  const mapTableLength = environment ? environment.height + environment.width * environment.height : 0;
  const environmentTables = new Float32Array(environment ? mapTableLength + portals.length * PORTAL_FLOATS + 1 : 4);
  if (environment) {
    environmentTables.set(environment.rows.data.subarray(0, environment.height), 0);
    environmentTables.set(environment.pixels.data.subarray(0, environment.width * environment.height), environment.height);
    portals.forEach((portal, index) => environmentTables.set(packPortal(portal), mapTableLength + index * PORTAL_FLOATS));
    environmentTables[environmentTables.length - 1] = portals.length;
  }
  // The subsurface table (two vectors per material) follows the material table in the same buffer.
  const materialData = packMaterials(scene.materials, atlas, scene.shadowOnlyParts).data;
  const subsurfaceOffset = materialData.length / 4;
  const subsurfaceData = sceneUsesSubsurface(scene.materials) ? packSubsurface(scene.materials).data : new Float32Array(0);
  const materialsWithSubsurface = new Float32Array(materialData.length + subsurfaceData.length);
  materialsWithSubsurface.set(materialData);
  materialsWithSubsurface.set(subsurfaceData, materialData.length);
  // The local volume table follows the subsurface table in the same buffer; its first vector index goes to params.seedAndAtlas.w.
  const localVolumeOffset = materialsWithSubsurface.length / 4;
  const localVolumeData = scene.localVolumes ? packWebGpuLocalVolumes(scene.localVolumes, scene.environment) : new Float32Array(0);
  const materialsWithTables = new Float32Array(materialsWithSubsurface.length + localVolumeData.length);
  materialsWithTables.set(materialsWithSubsurface);
  materialsWithTables.set(localVolumeData, materialsWithSubsurface.length);
  const triangleCount = uniqueTriangleCount(scene);
  const largeScene = triangleCount > MAX_TRACE_TRIANGLES;
  const { nodeTable, triangleData, instanceHeader } = packGeometryTables(device, scene);
  if (largeScene) device.pushErrorScope('out-of-memory');
  const buffers = [
    createStorageBuffer(device, nodeTable.data, 'bvh nodes'),
    createStorageBuffer(device, triangleData, 'triangles'),
    createStorageBuffer(device, materialsWithTables, 'materials'),
    createStorageBuffer(device, lightsWithTree, 'lights'),
    createStorageBuffer(device, atlasWords(atlas), 'texture atlas'),
    createStorageBuffer(device, environment?.colors ?? new Float32Array(4), 'environment colors'),
    createStorageBuffer(device, environmentTables, 'environment tables'),
  ];
  // Awaited by the caller before the kernel runs, so a device that could not allocate the tables fails with the count, not a black image.
  const allocationCheck = largeScene ? device.popErrorScope().then((error) => {
    if (error) throw new Error(`The GPU ran out of memory while allocating the scene buffers for ${triangleCount} triangles. Simplify or drop meshes to stay near ${MAX_TRACE_TRIANGLES} triangles, or render the frame with the native Cook backend.`);
  }) : Promise.resolve();
  return { allocationCheck, buffers, lightCount: lights.count, lightTreeBase, atlasWidth: atlas.width, subsurfaceOffset, localVolumeOffset, instanceHeader };
}

/** The words of one uniform block: the 12 vectors of the megakernel parameters, then the tile and shadow slot words. */
function createParameterTemplate(scene, camera, options, uploaded, emitterCount) {
  const words = new ArrayBuffer(PARAMETER_BYTES);
  const floats = new Float32Array(words);
  const integers = new Int32Array(words);
  const unsigned = new Uint32Array(words);
  const { sun } = scene.lights;
  const { environment } = scene;
  floats.set([...camera.eye, 0], 0);
  floats.set([...camera.forward, camera.clipStart ?? 0], 4);
  floats.set([...camera.right, 0], 8);
  floats.set([...camera.above, 0], 12);
  floats.set([...(sun?.direction ?? [0, 1, 0]), 0], 16);
  floats.set([...(sun?.color ?? [0, 0, 0]), Math.cos(Math.PI / 360)], 20);
  floats.set([environment?.width ?? 1, environment?.height ?? 1, environment?.intensity ?? 1, environment?.total ?? 1], 24);
  floats.set([environment?.cosine ?? 1, environment?.sine ?? 0, scene.surfaceOffset, scene.farDistance], 28);
  floats.set([camera.halfWidth, camera.halfHeight, options.fireflyClamp, uploaded.lightTreeBase], 32);
  integers.set([options.width, options.height, options.bounces, uploaded.lightCount], 36);
  integers.set([emitterCount, sun ? 1 : 0, environment ? 1 : 0, 0], 40);
  unsigned.set([options.seed >>> 0, uploaded.atlasWidth, uploaded.subsurfaceOffset, uploaded.localVolumeOffset], 44);
  unsigned[INSTANCE_HEADER_WORD] = uploaded.instanceHeader;
  const { volume } = scene;
  floats.set([...(volume?.minimum ?? [0, 0, 0]), volume?.density ?? 0], 56);
  floats.set([...(volume?.maximum ?? [0, 0, 0]), volume?.anisotropy ?? 0], 60);
  floats.set([...(volume?.albedo ?? [1, 1, 1]), volume?.maxDistance ?? 0], 64);
  return { unsigned, integers };
}

const SAMPLE_INDEX_WORD = 43;
// The fourth word of the shadow slot vector: the vector index of the instance table header (path-tracer-webgpu-instancing.js), 0 without instances.
const INSTANCE_HEADER_WORD = 55;
const TILE_WORD = 48;
const SHADOW_SLOT_WORD = 52;
const SORT_FLAG_WORD = 53;
// The texel kernel keeps the sample count in a shadow slot word the megakernel leaves unused.
const SAMPLE_COUNT_WORD = 54;

/** Fills one 256 byte slot per (tile, depth) of a sample; the kernels find their tile and depth in the slot they are bound to. */
function writeParameterSlots(template, sampleIndex, tiles, depthCount, materialCount, shadowSlots, sortByMaterial) {
  const bytes = new Uint8Array(tiles.length * depthCount * PARAMETER_SLOT_BYTES);
  tiles.forEach((tile, tileIndex) => {
    for (let depth = 0; depth < depthCount; depth++) {
      const slot = new Uint32Array(bytes.buffer, (tileIndex * depthCount + depth) * PARAMETER_SLOT_BYTES, PARAMETER_BYTES / 4);
      slot.set(template.unsigned);
      slot[SAMPLE_INDEX_WORD] = sampleIndex;
      slot.set([tile.start, tile.count, depth, materialCount], TILE_WORD);
      slot[SHADOW_SLOT_WORD] = shadowSlots;
      slot[SORT_FLAG_WORD] = sortByMaterial ? 1 : 0;
    }
  });
  return bytes;
}

// Path numbers run over whole 8 by 8 blocks of pixels, so there can be a few more paths than pixels; a tile is a whole number of blocks.
function planTiles(width, height, shadowSlots) {
  const pathCount = Math.ceil(width / 8) * Math.ceil(height / 8) * 64;
  const pathBytes = (PATH_STATE_VECTORS + 3 * shadowSlots) * 16;
  const tilePaths = Math.min(pathCount, Math.floor(Math.min(MAXIMUM_TILE_PATHS, MAXIMUM_STATE_BYTES / pathBytes) / 64) * 64);
  const tiles = [];
  for (let start = 0; start < pathCount; start += tilePaths) tiles.push({ start, count: Math.min(tilePaths, pathCount - start) });
  return { tiles, tilePaths, stateBytes: tilePaths * pathBytes };
}

function averageBuffers(planes, pixelCount, samples) {
  const buffers = {
    color: new Float32Array(pixelCount * 3), albedo: new Float32Array(pixelCount * 3), normal: new Float32Array(pixelCount * 3),
    depth: new Float32Array(pixelCount), variance: new Float32Array(pixelCount), samplesTaken: new Uint16Array(pixelCount).fill(samples),
  };
  const albedoPlane = pixelCount * 4;
  const normalPlane = pixelCount * 8;
  const statisticsPlane = pixelCount * 12;
  for (let pixel = 0; pixel < pixelCount; pixel++) {
    for (let channel = 0; channel < 3; channel++) {
      buffers.color[pixel * 3 + channel] = planes[pixel * 4 + channel] / samples;
      buffers.albedo[pixel * 3 + channel] = planes[albedoPlane + pixel * 4 + channel] / samples;
      buffers.normal[pixel * 3 + channel] = planes[normalPlane + pixel * 4 + channel] / samples;
    }
    buffers.depth[pixel] = planes[pixel * 4 + 3] / samples;
    const mean = planes[statisticsPlane + pixel * 4] / samples;
    buffers.variance[pixel] = Math.max(0, planes[statisticsPlane + pixel * 4 + 1] / samples - mean * mean) / Math.max(samples - 1, 1);
  }
  return buffers;
}

function encodeWavefrontSample(pass, pipelines, bindGroup, tiles, depthCount, materialCount, sortByMaterial) {
  const groupsFor = count => Math.ceil(count / WAVEFRONT_WORKGROUP_SIZE);
  const run = (entryPoint, groups) => {
    pass.setPipeline(pipelines[entryPoint]);
    pass.dispatchWorkgroups(groups);
  };
  tiles.forEach((tile, tileIndex) => {
    const bind = depth => pass.setBindGroup(0, bindGroup, [(tileIndex * depthCount + depth) * PARAMETER_SLOT_BYTES]);
    bind(0);
    run('generatePaths', groupsFor(tile.count));
    for (let depth = 0; depth < depthCount; depth++) {
      bind(depth);
      if (sortByMaterial) run('resetBins', groupsFor(Math.max(materialCount, 1)));
      run('extendPaths', groupsFor(tile.count));
      if (sortByMaterial) {
        run('scanBins', 1);
        run('scatterPaths', groupsFor(tile.count));
      }
      run('shadePaths', groupsFor(tile.count));
      run('shadowPaths', groupsFor(tile.count));
    }
    bind(0);
    run('resolvePaths', groupsFor(tile.count));
  });
}

/**
 * Traces `options.samples` paths for every pixel and resolves with the same buffers as the WebGL2 tracer (color, albedo,
 * normal, depth, variance, samplesTaken) plus a `gpu` note and the `compileSeconds` of the kernel. `options.kernel` picks
 * `wavefront` or `megakernel` (the default is DEFAULT_WEBGPU_KERNEL). `noiseThreshold` is not used: every pixel draws all its
 * samples. `shouldStop` throws when the time limit passes; it runs between samples.
 */
export async function traceOnWebGpu(scene, camera, options, shouldStop) {
  const kernel = options.kernel ?? DEFAULT_WEBGPU_KERNEL;
  if (!WEBGPU_KERNELS.includes(kernel)) throw new RangeError(`The WebGPU path tracer kernel must be one of ${WEBGPU_KERNELS.join(', ')}.`);
  const features = sceneFeatures(scene);
  if (kernel === 'wavefront' && (features.hasVolume || features.hasLocalVolumes || features.hasSubsurface)) {
    throw new RangeError('The WebGPU wavefront kernel does not trace volume fog, local volumes or subsurface scattering. Use the megakernel, the default.');
  }
  if (kernel === 'wavefront' && features.instanced) {
    throw new RangeError('The WebGPU wavefront kernel does not read instanced scenes. Build the scene without instancing, or use the megakernel, the default.');
  }
  assertWebGpuLocalVolumes(scene);
  const current = await getSession();
  const { device } = current;
  const { pipelines, compileSeconds } = await getKernel(current, { kernel, ...features });
  const { width, height, samples } = options;
  const pixelCount = width * height;
  const planeBytes = pixelCount * 16;
  if (planeBytes * 4 > device.limits.maxStorageBufferBindingSize) {
    throw new RangeError(`A ${width} by ${height} image is too large for this WebGPU adapter. Lower the size or use backend "gpu".`);
  }
  const uploaded = uploadScene(device, scene, options.lightSelection);
  await uploaded.allocationCheck;
  const emitterCount = (scene.lights.sun ? 1 : 0) + uploaded.lightCount + (scene.environment ? 1 : 0);
  const shadowSlots = Math.max(emitterCount, 1);
  const materialCount = scene.materials.length;
  const depthCount = options.bounces + 1;
  const isWavefront = kernel === 'wavefront';
  const sortByMaterial = options.sortByMaterial ?? DEFAULT_SORT_BY_MATERIAL;
  const { tiles, tilePaths, stateBytes } = planTiles(width, height, shadowSlots);
  const slotCount = isWavefront ? tiles.length * depthCount : 1;
  const accumulation = device.createBuffer({ label: 'accumulation', size: planeBytes * 4, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC });
  const parameters = device.createBuffer({ label: 'parameters', size: slotCount * PARAMETER_SLOT_BYTES, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
  const stateBuffer = device.createBuffer({ label: 'path state', size: isWavefront ? stateBytes : 16, usage: GPUBufferUsage.STORAGE });
  const queueWords = 1 + 2 * materialCount + tilePaths;
  const binQueue = device.createBuffer({ label: 'material bins', size: isWavefront ? queueWords * 4 : 16, usage: GPUBufferUsage.STORAGE });
  const bindGroup = device.createBindGroup({
    layout: current.bindGroupLayout,
    entries: [
      { binding: 0, resource: { buffer: parameters, size: PARAMETER_BYTES } },
      ...[...uploaded.buffers, accumulation, stateBuffer, binQueue].map((buffer, index) => ({ binding: index + 1, resource: { buffer } })),
    ],
  });
  const template = createParameterTemplate(scene, camera, options, uploaded, emitterCount);
  for (let sample = 0; sample < samples; sample++) {
    const slots = writeParameterSlots(template, sample, isWavefront ? tiles : [{ start: 0, count: pixelCount }], isWavefront ? depthCount : 1, materialCount, shadowSlots, sortByMaterial);
    device.queue.writeBuffer(parameters, 0, slots);
    const encoder = device.createCommandEncoder();
    const pass = encoder.beginComputePass();
    if (isWavefront) {
      encodeWavefrontSample(pass, pipelines, bindGroup, tiles, depthCount, materialCount, sortByMaterial);
    } else {
      pass.setPipeline(pipelines.main);
      pass.setBindGroup(0, bindGroup, [0]);
      pass.dispatchWorkgroups(Math.ceil(width / WORKGROUP_SIZE), Math.ceil(height / WORKGROUP_SIZE));
    }
    pass.end();
    device.queue.submit([encoder.finish()]);
    await device.queue.onSubmittedWorkDone();
    shouldStop();
  }
  const readback = device.createBuffer({ size: planeBytes * 4, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });
  const encoder = device.createCommandEncoder();
  encoder.copyBufferToBuffer(accumulation, 0, readback, 0, planeBytes * 4);
  device.queue.submit([encoder.finish()]);
  await readback.mapAsync(GPUMapMode.READ);
  const buffers = averageBuffers(new Float32Array(readback.getMappedRange()), pixelCount, samples);
  readback.destroy();
  for (const buffer of [...uploaded.buffers, accumulation, parameters, stateBuffer, binQueue]) buffer.destroy();
  return Object.assign(buffers, { gpu: current.gpu, compileSeconds });
}

/**
 * The pieces the real-time tracer (path-tracer-realtime-webgpu.js) builds its frame from, given its kernel's WGSL `realtimePieces`: the device, the real-time kernel's
 * pipeline and bind group layout for `scene`, the uploaded scene tables, and `parameterWords(camera)`, the words of the
 * parameter block for a camera (the caller sets the sample index and the cache words).
 */
export async function prepareRealtimeKernel(scene, options, realtimePieces) {
  if (isInstancedScene(scene)) {
    throw new RangeError('The WebGPU real-time tracer does not read instanced scenes yet. Build the scene for it without instancing (buildTraceSceneForDevice with a module that does not set supportsInstancing).');
  }
  const current = await getSession();
  const { device } = current;
  const { pipelines, compileSeconds } = await getKernel(current, { kernel: 'megakernel', ...sceneFeatures(scene), realtime: realtimePieces });
  const uploaded = uploadScene(device, scene);
  await uploaded.allocationCheck;
  const emitterCount = (scene.lights.sun ? 1 : 0) + uploaded.lightCount + (scene.environment ? 1 : 0);
  return {
    device, gpu: current.gpu, compileSeconds, uploaded,
    bindGroupLayout: current.bindGroupLayout,
    pipeline: pipelines.traceRealtime,
    parameterBytes: PARAMETER_BYTES,
    parameterWords: camera => createParameterTemplate(scene, camera, options, uploaded, emitterCount).unsigned,
  };
}

const TEXEL_GROUPS_PER_ROW = 4096;
const TEXEL_SAMPLES_PER_WAIT = 16;

function padVectors(vectors, count) {
  const padded = new Float32Array(Math.max(count, 1) * 4);
  for (let index = 0; index < count; index++) padded.set(vectors.subarray(index * 3, index * 3 + 3), index * 4);
  return padded;
}

/**
 * The texel entry of the light bake, the WebGPU form of `traceTexelsOnGpu` in path-tracer-gpu.js: traces `options.samples`
 * cosine weighted paths from every texel in `texels` (`count`, `points` and `normals`, three floats each) and resolves with
 * the mean `radiance` that arrives (three floats per texel), the share of first rays that `escaped`, the `gpu` name and the
 * `compileSeconds` of the kernel. `options.bounces` counts hits, as in the CPU bake.
 */
export async function traceTexelsOnWebGpu(scene, texels, options, shouldStop) {
  const current = await getSession();
  const { device } = current;
  const { count, points, normals } = texels;
  const { samples, seed } = options;
  const features = { ...sceneFeatures(scene), texelBake: true };
  const { pipelines, compileSeconds } = await getKernel(current, { kernel: 'megakernel', ...features });
  const accumulationBytes = Math.max(count, 1) * 16 * 2;
  if (accumulationBytes > device.limits.maxStorageBufferBindingSize) {
    throw new RangeError(`${count} lightmap texels are too many for this WebGPU adapter. Lower the lightmap resolution or use backend "gpu".`);
  }
  const uploaded = uploadScene(device, scene);
  await uploaded.allocationCheck;
  const emitterCount = (scene.lights.sun ? 1 : 0) + uploaded.lightCount + (scene.environment ? 1 : 0);
  const camera = { eye: [0, 0, 0], forward: [0, 0, 1], right: [1, 0, 0], above: [0, 1, 0], halfWidth: 1, halfHeight: 1 };
  const template = createParameterTemplate(scene, camera, { width: count, height: 1, seed, bounces: options.bounces - 1, fireflyClamp: options.fireflyClamp }, uploaded, emitterCount);
  template.unsigned[SAMPLE_COUNT_WORD] = samples;
  const accumulation = device.createBuffer({ label: 'accumulation', size: accumulationBytes, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC });
  const parameters = device.createBuffer({ label: 'parameters', size: PARAMETER_SLOT_BYTES, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
  const texelBuffers = [padVectors(points, count), padVectors(normals, count)].map((vectors, index) => createStorageBuffer(device, vectors, index === 0 ? 'texel points' : 'texel normals'));
  const bindGroup = device.createBindGroup({
    layout: current.bindGroupLayout,
    entries: [
      { binding: 0, resource: { buffer: parameters, size: PARAMETER_BYTES } },
      ...[...uploaded.buffers, accumulation, ...texelBuffers].map((buffer, index) => ({ binding: index + 1, resource: { buffer } })),
    ],
  });
  const groups = Math.max(1, Math.ceil(count / WAVEFRONT_WORKGROUP_SIZE));
  const groupsAcross = Math.min(groups, TEXEL_GROUPS_PER_ROW);
  for (let sample = 0; sample < samples; sample++) {
    device.queue.writeBuffer(parameters, 0, writeParameterSlots(template, sample, [{ start: 0, count }], 1, 0, 1, false));
    const encoder = device.createCommandEncoder();
    const pass = encoder.beginComputePass();
    pass.setPipeline(pipelines.bakeTexels);
    pass.setBindGroup(0, bindGroup, [0]);
    pass.dispatchWorkgroups(groupsAcross, Math.ceil(groups / groupsAcross));
    pass.end();
    device.queue.submit([encoder.finish()]);
    // A texel pass is short, so the queue is awaited every few samples: one round trip per sample would dominate the bake.
    if ((sample + 1) % TEXEL_SAMPLES_PER_WAIT === 0 || sample === samples - 1) {
      await device.queue.onSubmittedWorkDone();
      shouldStop();
    }
  }
  const readback = device.createBuffer({ size: accumulationBytes, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });
  const encoder = device.createCommandEncoder();
  encoder.copyBufferToBuffer(accumulation, 0, readback, 0, accumulationBytes);
  device.queue.submit([encoder.finish()]);
  await readback.mapAsync(GPUMapMode.READ);
  const sums = new Float32Array(readback.getMappedRange());
  const radiance = new Float32Array(count * 3);
  const escaped = new Float32Array(count);
  for (let texel = 0; texel < count; texel++) {
    for (let channel = 0; channel < 3; channel++) radiance[texel * 3 + channel] = sums[texel * 4 + channel] / samples;
    escaped[texel] = sums[(count + texel) * 4] / samples;
  }
  readback.destroy();
  for (const buffer of [...uploaded.buffers, accumulation, parameters, ...texelBuffers]) buffer.destroy();
  return { radiance, escaped, gpu: current.gpu, compileSeconds };
}

// The megakernel reads instanced scenes (path-tracer-webgpu-instancing.js): buildTraceSceneForDevice keeps copies of one mesh as instances for it.
// The wavefront kernel and the real-time tracer do not, and their callers ask for a flat scene.
export const supportsInstancing = true;

// The names path-tracer.js looks for in a backend module, the same as path-tracer-gpu.js.
export { traceOnWebGpu as traceOnGpu, webGpuKernelCompileCount as gpuKernelCompileCount, webGpuTriangleLimit as gpuTriangleLimit };

/** The triangles one storage buffer of this device holds, up to MAX_GPU_TRACE_TRIANGLES. Asks for the adapter when the page has none open yet. */
export async function webGpuTriangleLimit() {
  const { device } = await getSession();
  return gpuTriangleCapacity({ maximumBufferBytes: device.limits.maxStorageBufferBindingSize, maximumBufferSize: device.limits.maxBufferSize }, MAX_GPU_TRACE_TRIANGLES);
}