@plasius/gpu-renderer 0.2.56 → 0.2.58

package/package.json

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

package/src/gpu-allocation-budget.js

@@ -0,0 +1,92 @@
+// Accounts for requested WebGPU resource storage, not driver overhead or free VRAM.
+const formats = Object.freeze({
+  r8unorm:1, r8snorm:1, r8uint:1, r8sint:1,
+  rg8unorm:2, rg8snorm:2, rg8uint:2, rg8sint:2, r16float:2, r16uint:2, r16sint:2,
+  rgba8unorm:4, 'rgba8unorm-srgb':4, bgra8unorm:4, 'bgra8unorm-srgb':4,
+  rgba8snorm:4, rgba8uint:4, rgba8sint:4, rg16float:4, rg16uint:4, rg16sint:4,
+  r32float:4, r32uint:4, r32sint:4, rgb10a2unorm:4, rg11b10ufloat:4,
+  rgba16float:8, rgba16uint:8, rgba16sint:8, rg32float:8, rg32uint:8, rg32sint:8,
+  rgba32float:16, rgba32uint:16, rgba32sint:16,
+});
+function integer(value, name, minimum=1) {
+  if(!Number.isSafeInteger(value)||value<minimum) throw new Error(`${name} must be a safe integer >= ${minimum}.`);
+  return value;
+}
+function within(value,limit,name) {
+  if(Number.isFinite(limit)&&value>limit) throw new Error(`GPU ${name} limit exceeded: requested ${value}, available ${limit}.`);
+}
+function textureBytes(descriptor,limits) {
+  const size=descriptor.size;
+  const array=Array.isArray(size)||ArrayBuffer.isView(size);
+  const width=integer(array?size[0]:size?.width,'Texture width');
+  const height=integer((array?size[1]:size?.height)??1,'Texture height');
+  const layers=integer((array?size[2]:size?.depthOrArrayLayers)??1,'Texture depth/layers');
+  const dimension=descriptor.dimension??'2d';
+  if(!['1d','2d','3d'].includes(dimension)) throw new Error('Unsupported GPU texture dimension.');
+  const limit=limits[dimension==='3d'?'maxTextureDimension3D':dimension==='1d'?'maxTextureDimension1D':'maxTextureDimension2D'];
+  within(Math.max(width,height,dimension==='3d'?layers:1),limit,'texture dimension');
+  if(dimension!=='3d') within(layers,limits.maxTextureArrayLayers,'texture layers');
+  const bpp=formats[descriptor.format];
+  if(!bpp) throw new Error(`GPU memory accounting does not support texture format ${descriptor.format}.`);
+  const levels=integer(descriptor.mipLevelCount??1,'Mip count');
+  const samples=integer(descriptor.sampleCount??1,'Sample count');
+  if(levels>Math.floor(Math.log2(Math.max(width,height,dimension==='3d'?layers:1)))+1) throw new Error('Invalid texture mip count.');
+  let bytes=0;
+  for(let level=0;level<levels;level++) bytes+=Math.max(1,Math.floor(width/2**level))*Math.max(1,Math.floor(height/2**level))*
+    (dimension==='3d'?Math.max(1,Math.floor(layers/2**level)):layers)*bpp*samples;
+  return integer(bytes,'Texture allocation');
+}
+
+export function createGpuAllocationTracker(rawDevice,{budgetBytes,storageUsage=globalThis.GPUBufferUsage?.STORAGE??128}={}) {
+  if(budgetBytes!==undefined) integer(budgetBytes,'GPU memory budget');
+  const records=new Map();let allocatedBytes=0,peakAllocatedBytes=0;
+  function allocate(kind,descriptor,bytes,create) {
+    integer(bytes,'GPU allocation',0);
+    const total=integer(allocatedBytes+bytes,'GPU allocation total',0);
+    if(budgetBytes!==undefined&&total>budgetBytes) throw new Error(`GPU memory budget exceeded: ${total} requested bytes, budget ${budgetBytes}. Reduce quality or scene resources.`);
+    const resource=create(descriptor),originalDestroy=resource.destroy.bind(resource);
+    const release=()=>{if(!records.has(resource))return;originalDestroy();records.delete(resource);allocatedBytes-=bytes;};
+    try{Object.defineProperty(resource,'destroy',{value:release,configurable:true});}
+    catch(error){originalDestroy();throw error;}
+    records.set(resource,{kind,label:descriptor.label??'',bytes,release});allocatedBytes=total;peakAllocatedBytes=Math.max(total,peakAllocatedBytes);
+    return resource;
+  }
+  const destroy=()=>{for(const record of [...records.values()])record.release();};
+  const methods={
+    createBuffer(descriptor){
+      const bytes=integer(descriptor.size,'Buffer size',0);
+      within(bytes,rawDevice.limits?.maxBufferSize,'buffer size');
+      if((descriptor.usage??0)&storageUsage) within(bytes,rawDevice.limits?.maxStorageBufferBindingSize,'storage binding size');
+      return allocate('buffer',descriptor,bytes,d=>rawDevice.createBuffer(d));
+    },
+    createTexture(descriptor){return allocate('texture',descriptor,textureBytes(descriptor,rawDevice.limits??{}),d=>rawDevice.createTexture(d));},
+    createQuerySet(descriptor){return allocate('query-set',descriptor,integer(descriptor.count,'Query count')*8,d=>rawDevice.createQuerySet(d));},
+    destroy(){destroy();rawDevice.destroy();},
+  };
+  const device=new Proxy(rawDevice,{get(target,key){
+    if(Object.hasOwn(methods,key))return methods[key];
+    const value=Reflect.get(target,key,target);return typeof value==='function'?value.bind(target):value;
+  }});
+  return Object.freeze({device,destroy,snapshot:()=>Object.freeze({
+    accounting:'requested-resource-bytes',budgetBytes:budgetBytes??null,allocatedBytes,peakAllocatedBytes,
+    resources:Object.freeze([...records.values()].map(({kind,label,bytes})=>Object.freeze({kind,label,bytes}))),
+  })});
+}
+
+/** Pop both scopes before awaiting either, so rejection cannot leave a scope open. */
+export function openGpuAllocationErrorScopes(device) {
+  if(typeof device.pushErrorScope!=='function'||typeof device.popErrorScope!=='function') return async()=>{};
+  let count=0;
+  try{device.pushErrorScope('out-of-memory');count++;device.pushErrorScope('validation');count++;}
+  catch(error){while(count-->0)Promise.resolve(device.popErrorScope()).catch(()=>{});throw error;}
+  return async()=>{
+    const completions=[];
+    while(count>0){count--;try{completions.push(Promise.resolve(device.popErrorScope()));}catch(error){completions.push(Promise.reject(error));}}
+    if(!completions.length)return;
+    let timer;
+    try{
+      const errors=await Promise.race([Promise.all(completions),new Promise((_,reject)=>{timer=setTimeout(()=>reject(new Error('GPU allocation validation timed out.')),10000);})]);
+      const error=errors.find(Boolean);if(error)throw new Error(`GPU allocation failed: ${error.message??String(error)}`);
+    }finally{clearTimeout(timer);}
+  };
+}

package/src/index.d.ts

@@ -899,6 +899,11 @@ export interface WavefrontPathTracingComputeConfig {
   readonly gpuAccelerationBuildRequired: boolean;
   readonly gpuMeshSource: WavefrontGpuMeshSource;
   readonly gpuMaterialSource: WavefrontGpuMaterialSource;
+  readonly instancing: Readonly<{
+    instanceCount: number; geometryCount: number; instanceBytes: number;
+    tlasNodeCount: number; blasNodeCount: number; buffer: ArrayBuffer;
+    acceleration: WavefrontMeshAcceleration;
+  }> | null;
   readonly meshAcceleration: WavefrontMeshAcceleration;
   readonly emissiveTriangleIndices: WavefrontEmissiveTriangleIndexSource;
   readonly emissiveTriangleCount: number;
@@ -1045,6 +1050,10 @@ export interface WavefrontPathTracingMemoryEstimate {
   readonly pathVertexBytes: number;
   readonly sceneObjectBytes: number;
   readonly triangleBytes: number;
+  /** Logical 144-byte records, separate from totalHotBufferBytes and before texture row padding. */
+  readonly instanceBytes: number;
+  /** Requested instance texture storage including row padding. */
+  readonly instanceTextureBytes: number;
   readonly materialTableBytes: number;
   readonly bvhNodeBytes: number;
   readonly bvhCombinedBytes: number;
@@ -1102,6 +1111,21 @@ export interface WavefrontGpuParallelismDiagnostics {
   readonly coreUtilizationStatus: "not-exposed-by-webgpu";
 }
 
+/** Static column-major affine transform referencing a unique mesh. */
+export interface WavefrontMeshInstanceInput {
+  readonly id: number;
+  readonly meshId: number;
+  readonly transform: readonly number[] | Float32Array;
+}
+export interface WavefrontGpuAllocationSnapshot {
+  /** Requested resource storage; excludes driver overhead and externally owned resources. */
+  readonly accounting: "requested-resource-bytes";
+  readonly budgetBytes: number | null;
+  readonly allocatedBytes: number;
+  readonly peakAllocatedBytes: number;
+  readonly resources: readonly Readonly<{kind: string; label: string; bytes: number}>[];
+}
+
 export interface CreateWavefrontPathTracingComputeRendererOptions {
   /** Accumulate linear radiance between frames until camera/scene/reset changes. Default false. */
   readonly progressive?: boolean;
@@ -1127,6 +1151,10 @@ export interface CreateWavefrontPathTracingComputeRendererOptions {
   readonly mediums?: readonly WavefrontMediumInput[];
   readonly mesh?: WavefrontMeshInput;
   readonly meshes?: readonly WavefrontMeshInput[];
+  /** Opt-in shared BLAS/TLAS instances. Every mesh must be referenced. Static, non-emissive meshes; CPU BLAS construction. */
+  readonly instances?: readonly WavefrontMeshInstanceInput[];
+  /** Positive renderer-owned resource byte budget. Device limits apply independently. */
+  readonly memoryBudgetBytes?: number;
   readonly triangleCapacity?: number;
   readonly bvhNodeCapacity?: number;
   readonly bvhLeafSortCapacity?: number;
@@ -1203,6 +1231,8 @@ export interface WavefrontPathTracingComputeRenderer {
     maxFramePassesPerSubmission: number;
     sceneObjectCount: number;
     triangleCount: number;
+    instanceCount: number;
+    geometryCount: number;
     emissiveTriangleCount: number;
     environmentPortalCount: number;
     environmentPortalMode: 0 | 1 | 2;
@@ -1221,6 +1251,7 @@ export interface WavefrontPathTracingComputeRenderer {
     frameConfigSlots: number;
     gpuParallelism: WavefrontGpuParallelismDiagnostics;
     memory: WavefrontPathTracingMemoryEstimate;
+    allocations: WavefrontGpuAllocationSnapshot;
   }>;
   destroy(): void;
 }
@@ -1388,6 +1419,8 @@ export function estimateWavefrontPathTracingMemory(options?: {
   maxDepth?: number;
   sceneObjectCapacity?: number;
   triangleCapacity?: number;
+  instanceBytes?: number;
+  instanceTextureBytes?: number;
   materialCapacity?: number;
   bvhNodeCapacity?: number;
   bvhLeafSortCapacity?: number;
@@ -1557,6 +1590,7 @@ export function renderWavefrontPathTracingComputeFrame(
   }
 ): Promise<WavefrontPathTracingComputeFrameStats>;
 export function createWavefrontPathTracingComputeShaderSource(options?: {
+  readonly instanced?: boolean;
   workgroupSize?: number;
   outputTextureFormat?: GPUTextureFormat | "rgba8unorm";
 }): string;

package/src/wavefront-bind-groups.js

@@ -12,6 +12,7 @@ export function createWavefrontTraceBindGroup({
   counterBuffer,
   outputView,
   triangleBuffer,
+  instanceView,
   bvhNodeBuffer,
   radianceView,
   environmentPortalBuffer,
@@ -70,6 +71,7 @@ export function createWavefrontTraceBindGroup({
       { binding: 42, resource: extensionAtlasResources.iridescence.view },
       { binding: 43, resource: extensionAtlasResources.iridescenceThickness.view },
       { binding: 44, resource: extensionAtlasResources.anisotropy.view },
+      ...(instanceView ? [{binding:47, resource:instanceView}] : []),
     ],
   });
 }

package/src/wavefront-compute.js

@@ -1,3 +1,6 @@
+import { uploadWavefrontBuffer } from './wavefront-upload.js';
+import { planInstanceTexture, uploadInstanceTexture } from './wavefront-instance-texture.js';
+import { createGpuAllocationTracker, openGpuAllocationErrorScopes } from './gpu-allocation-budget.js';
 import { createWavefrontProgressiveResources } from './wavefront-progressive.js';
 import {
   createGpuParallelismCounters,
@@ -190,11 +193,16 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     throw new Error("Unable to acquire a WebGPU adapter for wavefront path tracing.");
   }
 
-  const device = await adapter.requestDevice(
+  const rawDevice = await adapter.requestDevice(
     createWavefrontDeviceDescriptor(adapter, options, initialConfig.memory)
   );
+  const allocationTracker = createGpuAllocationTracker(rawDevice, {budgetBytes:options.memoryBudgetBytes,storageUsage:constants.buffer.STORAGE});
+  const device = allocationTracker.device;
+  let context, finishAllocationScopes;
+  try {
+  finishAllocationScopes = openGpuAllocationErrorScopes(rawDevice);
   const gpuAdapterParallelism = createGpuAdapterParallelismDiagnostics(adapter, device);
-  const context = canvas.getContext("webgpu");
+  context = canvas.getContext("webgpu");
   if (!context || typeof context.configure !== "function") {
     throw new Error("Canvas WebGPU context does not support configure().");
   }
@@ -226,13 +234,21 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
   canvas.width = config.width;
   canvas.height = config.height;
   context.configure({
-    device,
+    device: rawDevice,
     format,
     alphaMode: options.alpha === true ? "premultiplied" : "opaque",
   });
 
   const bufferUsage = constants.buffer.STORAGE | constants.buffer.COPY_DST;
   const memory = config.memory;
+  let instanceTexture = null, instanceView = null;
+  if(config.instancing) {
+    const layout=planInstanceTexture(config.instancing.instanceCount,device.limits?.maxTextureDimension2D);
+    instanceTexture=device.createTexture({label:"plasius.wavefront.instances",size:{width:layout.width,height:layout.height},
+      format:"rgba32uint",usage:constants.texture.TEXTURE_BINDING|constants.texture.COPY_DST});
+    await uploadInstanceTexture(device,instanceTexture,config.instancing.buffer,layout);
+    instanceView=instanceTexture.createView();
+  }
   const activeQueue = createBuffer(device, bufferUsage, memory.queueBytes, "plasius.wavefront.activeQueue");
   const nextQueue = createBuffer(device, bufferUsage, memory.queueBytes, "plasius.wavefront.nextQueue");
   const hitBuffer = createBuffer(device, bufferUsage, memory.hitBytes, "plasius.wavefront.hitBuffer");
@@ -354,11 +370,11 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     packedBvhNodeFloats[nodeOffset + 2] = totalEmissiveWeight;
     packedBvhNodeUints[nodeOffset + 8] = triangleIndex;
   });
-  device.queue.writeBuffer(triangleBuffer, 0, packedTriangles.buffer);
-  device.queue.writeBuffer(bvhNodeBuffer, 0, packedBvhNodes.buffer);
-  device.queue.writeBuffer(meshVertexBuffer, 0, config.gpuMeshSource.vertices.buffer);
-  device.queue.writeBuffer(meshIndexBuffer, 0, config.gpuMeshSource.indices.buffer);
-  device.queue.writeBuffer(meshRangeBuffer, 0, config.gpuMeshSource.meshes.buffer);
+  await uploadWavefrontBuffer(device, triangleBuffer, packedTriangles.buffer);
+  await uploadWavefrontBuffer(device, bvhNodeBuffer, packedBvhNodes.buffer);
+  await uploadWavefrontBuffer(device, meshVertexBuffer, config.gpuMeshSource.vertices.buffer);
+  await uploadWavefrontBuffer(device, meshIndexBuffer, config.gpuMeshSource.indices.buffer);
+  await uploadWavefrontBuffer(device, meshRangeBuffer, config.gpuMeshSource.meshes.buffer);
   const packedEnvironmentPortals = packEnvironmentPortals(
     config.environmentPortals,
     Math.max(1, config.environmentPortalCapacity)
@@ -501,7 +517,7 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     },
     computePipelines: pipelines,
     presentPipeline,
-  } = await createWavefrontPipelineResources({ device, constants, format });
+  } = await createWavefrontPipelineResources({ device, constants, format, instanced:!!config.instancing });
 
   function createTraceBindGroups() {
     return createWavefrontTraceBindGroups({
@@ -516,6 +532,7 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
       counterBuffer,
       outputView,
       triangleBuffer,
+      instanceView,
       bvhNodeBuffer,
       radianceView,
       environmentPortalBuffer,
@@ -1058,6 +1075,8 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
       maxFramePassesPerSubmission: config.maxFramePassesPerSubmission,
       sceneObjectCount: config.sceneObjectCount,
       triangleCount: config.triangleCount,
+      instanceCount: config.instancing?.instanceCount ?? 0,
+      geometryCount: config.instancing?.geometryCount ?? config.gpuMeshSource.meshes.count,
       emissiveTriangleCount: config.emissiveTriangleCount,
       environmentPortalCount: config.environmentPortalCount,
       environmentPortalMode: config.environmentPortalMode,
@@ -1076,6 +1095,7 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
       frameConfigSlots: frameConfigSlotCount,
       gpuParallelism: lastGpuParallelism,
       memory: config.memory,
+      allocations: allocationTracker.snapshot(),
     });
   }
 
@@ -1089,6 +1109,7 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     pathVertexBuffer.destroy?.();
     sceneObjectBuffer.destroy?.();
     triangleBuffer.destroy?.();
+    instanceTexture?.destroy?.();
     bvhNodeBuffer.destroy?.();
     meshVertexBuffer.destroy?.();
     meshIndexBuffer.destroy?.();
@@ -1133,12 +1154,14 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
       }
     });
     context.unconfigure?.();
+    allocationTracker.destroy();
   }
 
+  await finishAllocationScopes();
   return Object.freeze({
     canvas,
     context,
-    device,
+    device: rawDevice,
     format,
     config,
     renderOnce,
@@ -1150,6 +1173,13 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
     getSnapshot,
     destroy,
   });
+  } catch(error) {
+    try { await finishAllocationScopes?.(); } catch { /* Preserve the initiating failure. */ }
+    context?.unconfigure?.();
+    allocationTracker.destroy();
+    rawDevice.destroy?.();
+    throw error;
+  }
 }
 
 export async function renderWavefrontPathTracingComputeFrame(options = {}) {

package/src/wavefront-config.js

@@ -1,3 +1,5 @@
+import { planInstanceTexture } from './wavefront-instance-texture.js';
+import { WAVEFRONT_INSTANCE_BYTES, prepareWavefrontInstances, buildWavefrontInstances } from './wavefront-instances.js';
 import {
   ACCUMULATION_RECORD_BYTES,
   BVH_LEAF_REF_RECORD_BYTES,
@@ -357,6 +359,8 @@ export function estimateWavefrontPathTracingMemory(options = {}) {
   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 instanceBytes = readNonNegativeInteger("instanceBytes", options.instanceBytes, 0);
+  const instanceTextureBytes = readNonNegativeInteger("instanceTextureBytes", options.instanceTextureBytes, instanceBytes);
   const triangleBytes = allocatedRecordBytes(triangleCapacity, TRIANGLE_RECORD_BYTES);
   const materialTableBytes = 0;
   const bvhNodeBytes = bvhNodeCapacity * BVH_NODE_RECORD_BYTES;
@@ -431,6 +435,8 @@ export function estimateWavefrontPathTracingMemory(options = {}) {
     pathVertexBytes,
     sceneObjectBytes,
     triangleBytes,
+    instanceBytes,
+    instanceTextureBytes,
     materialTableBytes,
     bvhNodeBytes,
     bvhCombinedBytes,
@@ -461,6 +467,8 @@ export function estimateWavefrontPathTracingMemoryForConfig(config, limits = {})
     maxDepth: config.maxDepth,
     sceneObjectCapacity: config.sceneObjectCapacity,
     triangleCapacity: config.triangleCapacity,
+    instanceBytes: config.instancing?.instanceBytes ?? 0,
+    instanceTextureBytes: config.instancing ? planInstanceTexture(config.instancing.instanceCount, limits.maxTextureDimension2D).bytes : 0,
     bvhNodeCapacity: config.bvhNodeCapacity,
     bvhLeafSortCapacity: config.bvhLeafSortCapacity,
     emissiveTriangleCapacity: config.emissiveTriangleCapacity,
@@ -482,6 +490,7 @@ export function estimateWavefrontPathTracingMemoryForConfig(config, limits = {})
 export function createWavefrontPathTracingComputeConfig(options = {}) {
   assertAnalyticDisplayQualityPolicy(options);
   const accelerationBuildMode = resolveAccelerationBuildMode(options);
+  if(options.instances !== undefined && accelerationBuildMode === "gpu") throw new Error("Instance BLAS construction currently requires cpu-upload acceleration.");
   const canvas = options.canvas;
   const width = readPositiveInteger("width", options.width, getCanvasDimension(canvas, "width", DEFAULT_WIDTH));
   const height = readPositiveInteger("height", options.height, getCanvasDimension(canvas, "height", DEFAULT_HEIGHT));
@@ -512,6 +521,14 @@ export function createWavefrontPathTracingComputeConfig(options = {}) {
   );
   const meshes = normalizeMeshes(options);
   const meshSourceShape = estimateMeshSourceShape(meshes);
+  if(options.memoryBudgetBytes !== undefined) {
+    if(!Number.isSafeInteger(options.memoryBudgetBytes)||options.memoryBudgetBytes<=0) throw new Error("GPU memory budget must be a positive safe integer.");
+    const count = options.instances?.length ?? 0;
+    const instanceMinimumBytes = count * WAVEFRONT_INSTANCE_BYTES + Math.max(0, count * 2 - 1) * BVH_NODE_RECORD_BYTES;
+    const geometryMinimumBytes = meshSourceShape.triangleCount * TRIANGLE_RECORD_BYTES + instanceMinimumBytes;
+    if(!Number.isSafeInteger(geometryMinimumBytes)||geometryMinimumBytes>options.memoryBudgetBytes) throw new Error("Unique geometry exceeds the GPU memory budget before acceleration construction.");
+  }
+  const instancePlan = options.instances === undefined ? null : prepareWavefrontInstances(meshes, options.instances);
   const gpuMaterialSource =
     meshes.length > 0
       ? createWavefrontGpuMaterialSource(meshes)
@@ -520,10 +537,11 @@ export function createWavefrontPathTracingComputeConfig(options = {}) {
     meshes.length > 0
       ? createWavefrontGpuMeshSource(meshes, gpuMaterialSource)
       : createWavefrontGpuMeshSource([]);
-  const meshAcceleration =
+  const instancing = instancePlan ? buildWavefrontInstances(meshes, instancePlan, gpuMaterialSource) : null;
+  const meshAcceleration = instancing?.acceleration ?? (
     accelerationBuildMode === "cpu-upload"
       ? createWavefrontMeshAcceleration(meshes, gpuMaterialSource)
-      : Object.freeze({ nodes: Object.freeze([]), triangles: Object.freeze([]) });
+      : Object.freeze({ nodes: Object.freeze([]), triangles: Object.freeze([]) }));
   const emissiveTriangleIndices = createWavefrontEmissiveTriangleIndexSource(
     meshes,
     options.emissiveTriangleCapacity
@@ -625,6 +643,7 @@ export function createWavefrontPathTracingComputeConfig(options = {}) {
     gpuAccelerationBuildRequired: accelerationBuildMode === "gpu" && triangleCount > 0,
     gpuMeshSource,
     gpuMaterialSource,
+    instancing,
     meshAcceleration,
     emissiveTriangleIndices,
     emissiveTriangleCount: emissiveTriangleIndices.count,
@@ -663,6 +682,7 @@ export function createWavefrontPathTracingComputeConfig(options = {}) {
       tilePixelCapacity,
       maxDepth,
       sceneObjectCapacity,
+      instanceBytes: instancing?.instanceBytes ?? 0,
       triangleCapacity,
       bvhNodeCapacity,
       bvhLeafSortCapacity,

package/src/wavefront-instance-shader.js

@@ -0,0 +1,88 @@
+export const WAVEFRONT_INSTANCE_SHADER_WGSL = `
+struct MeshInstance {
+  world: mat4x4<f32>,
+  inverse: mat4x4<f32>,
+  objectId: u32,
+  root: u32,
+  handedness: f32,
+  _pad: u32,
+};
+@group(0) @binding(47) var meshInstances: texture_2d<u32>;
+fn read_mesh_instance(index: u32) -> MeshInstance {
+  let recordsPerRow = textureDimensions(meshInstances).x / 9u;
+  let x = i32((index % recordsPerRow) * 9u);
+  let y = i32(index / recordsPerRow);
+  let metadata = textureLoad(meshInstances, vec2<i32>(x + 8, y), 0);
+  return MeshInstance(
+    mat4x4<f32>(bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(x, y), 0)),
+      bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(x + 1, y), 0)),
+      bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(x + 2, y), 0)),
+      bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(x + 3, y), 0))),
+    mat4x4<f32>(bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(x + 4, y), 0)),
+      bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(x + 5, y), 0)),
+      bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(x + 6, y), 0)),
+      bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(x + 7, y), 0))),
+    metadata.x, metadata.y, bitcast<f32>(metadata.z), 0u);
+}
+
+fn instance_normal(instance: MeshInstance, normal: vec3<f32>) -> vec3<f32> {
+  let normalMatrix = transpose(mat3x3<f32>(instance.inverse[0].xyz, instance.inverse[1].xyz, instance.inverse[2].xyz));
+  return safe_normalize(normalMatrix * normal, vec3<f32>(0.0, 1.0, 0.0));
+}
+
+fn triangle_for_candidate(candidate: Candidate) -> TriangleRecord {
+  var triangle = triangles[candidate.triangleIndex];
+  let instance = read_mesh_instance(candidate.instanceIndex);
+  triangle.v0 = instance.world * vec4<f32>(triangle.v0.xyz, 1.0);
+  triangle.v1 = instance.world * vec4<f32>(triangle.v1.xyz, 1.0);
+  triangle.v2 = instance.world * vec4<f32>(triangle.v2.xyz, 1.0);
+  triangle.meshId = instance.objectId;
+  return triangle;
+}
+
+fn intersect_bvh(ray: RayRecord, initialNearest: f32) -> Candidate {
+  var nearest = initialNearest;
+  var best = no_candidate();
+  var stack = array<u32, 64>();
+  var stackSize = 1u;
+  stack[0] = 0u;
+  loop {
+    if (stackSize == 0u) { break; }
+    stackSize -= 1u;
+    let node = bvhNodes[stack[stackSize]];
+    if (!intersect_bounds(ray, node.boundsMin.xyz, node.boundsMax.xyz, nearest)) { continue; }
+    if (node.triangleCount == 0u) {
+      stack[stackSize] = node.childOrFirst;
+      stack[stackSize + 1u] = node.rightChild;
+      stackSize += 2u;
+    } else {
+      let instanceIndex = node.childOrFirst;
+      let instance = read_mesh_instance(instanceIndex);
+      var localRay = ray;
+      localRay.origin = instance.inverse * vec4<f32>(ray.origin.xyz, 1.0);
+      // Keep this direction unnormalized so t remains the world-space ray parameter.
+      localRay.direction = instance.inverse * vec4<f32>(ray.direction.xyz, 0.0);
+      var candidate = intersect_geometry_bvh(localRay, nearest, instance.root);
+      if (candidate.hit == 1u && candidate.distance < nearest) {
+        candidate.geometricNormal = instance_normal(instance, candidate.geometricNormal);
+        candidate.shadingNormal = repair_shading_normal(candidate.geometricNormal,
+          instance_normal(instance, candidate.shadingNormal));
+        if (instance.handedness < 0.0) { candidate.frontFace = 1u - candidate.frontFace; }
+        candidate.instanceIndex = instanceIndex;
+        nearest = candidate.distance;
+        best = candidate;
+      }
+    }
+  }
+  return best;
+}
+`;
+
+export const WAVEFRONT_UNINSTANCED_SHADER_WGSL = `
+fn triangle_for_candidate(candidate: Candidate) -> TriangleRecord {
+  return triangles[candidate.triangleIndex];
+}
+fn intersect_bvh(ray: RayRecord, initialNearest: f32) -> Candidate {
+  return intersect_geometry_bvh(ray, initialNearest, 0u);
+}
+`;

package/src/wavefront-instance-texture.js

@@ -0,0 +1,43 @@
+import { waitForSubmittedGpuWork } from './wavefront-gpu-synchronization.js';
+import { WAVEFRONT_INSTANCE_BYTES } from './wavefront-instances.js';
+
+const TEXELS_PER_RECORD = WAVEFRONT_INSTANCE_BYTES / 16;
+
+/** Whole records never cross rows; limits come from the granted GPU device. */
+export function planInstanceTexture(count, maxDimension = 8192) {
+  if (!Number.isSafeInteger(count) || count < 1 || count >= 0xffffffff) {
+    throw new Error('Instance count must fit unsigned shader addressing.');
+  }
+  if (!Number.isSafeInteger(maxDimension) || maxDimension < TEXELS_PER_RECORD) {
+    throw new Error('GPU instance texture dimension cannot hold one record.');
+  }
+  const recordsPerRow = Math.min(count, Math.floor(maxDimension / TEXELS_PER_RECORD));
+  const width = recordsPerRow * TEXELS_PER_RECORD, height = Math.ceil(count / recordsPerRow);
+  if (height > maxDimension) throw new Error('GPU instance texture dimension limit exceeded.');
+  const bytes = width * height * 16;
+  if (!Number.isSafeInteger(bytes)) throw new Error('Instance texture byte size is out of range.');
+  return Object.freeze({ count, recordsPerRow, width, height, bytes });
+}
+
+/** Queue writes have no 256-byte row-alignment requirement. Bound staging by rows. */
+export async function uploadInstanceTexture(device, texture, buffer, layout, { chunkBytes = 8 * 1024 * 1024 } = {}) {
+  const bytesPerRow = layout.width * 16;
+  if (!Number.isSafeInteger(chunkBytes) || chunkBytes < bytesPerRow) {
+    throw new Error('Instance upload chunk must hold at least one texture row.');
+  }
+  if (buffer.byteLength !== layout.count * WAVEFRONT_INSTANCE_BYTES) {
+    throw new Error('Instance upload does not match its record count.');
+  }
+  const source = new Uint8Array(buffer), rowsPerChunk = Math.floor(chunkBytes / bytesPerRow);
+  for (let y = 0; y < layout.height; y += rowsPerChunk) {
+    const rows = Math.min(rowsPerChunk, layout.height - y), offset = y * bytesPerRow;
+    const length = rows * bytesPerRow;
+    let chunk = source.subarray(offset, offset + length);
+    if (chunk.byteLength < length) {
+      const padded = new Uint8Array(length); padded.set(chunk); chunk = padded;
+    }
+    device.queue.writeTexture({ texture, origin: { x: 0, y, z: 0 } }, chunk,
+      { bytesPerRow, rowsPerImage: rows }, { width: layout.width, height: rows, depthOrArrayLayers: 1 });
+    await waitForSubmittedGpuWork(device, { timeoutMs: 10000, maxWaitMs: 10000, allowTimeout: false });
+  }
+}

package/src/wavefront-instances.js

@@ -0,0 +1,107 @@
+import { buildWavefrontBoundsBvh, createWavefrontMeshAcceleration } from './wavefront-mesh-sources.js';
+import { emissionPower, MATERIAL_EMISSIVE } from './wavefront-core.js';
+
+export const WAVEFRONT_INSTANCE_BYTES = 144;
+const freeze = Object.freeze;
+const uint = value => Number.isInteger(value) && value >= 0 && value < 0xffffffff;
+
+function affineTransform(value) {
+  if ((!Array.isArray(value) && !ArrayBuffer.isView(value)) || value.length !== 16 ||
+      !Array.from(value).every(n => Number.isFinite(n) && Math.abs(n) <= 1e12) ||
+      value[3] !== 0 || value[7] !== 0 || value[11] !== 0 || value[15] !== 1) {
+    throw new Error('Instance transform must be a finite affine column-major matrix.');
+  }
+  // Round to the actual shader representation before inversion and bounds construction.
+  const m = Array.from(value, Math.fround);
+  const [a,b,c,,d,e,f,,g,h,i] = m;
+  const determinant = a*(e*i-f*h)-d*(b*i-c*h)+g*(b*f-c*e);
+  if (!Number.isFinite(determinant) || Math.abs(determinant) < 1e-12) {
+    throw new Error('Instance transform must be invertible.');
+  }
+  const inv = [(e*i-f*h)/determinant,(c*h-b*i)/determinant,(b*f-c*e)/determinant,0,
+    (f*g-d*i)/determinant,(a*i-c*g)/determinant,(c*d-a*f)/determinant,0,
+    (d*h-e*g)/determinant,(b*g-a*h)/determinant,(a*e-b*d)/determinant,0,0,0,0,1];
+  for (let r=0;r<3;r++) inv[12+r]=-(inv[r]*m[12]+inv[4+r]*m[13]+inv[8+r]*m[14]);
+  if (!inv.every(n=>Number.isFinite(n) && Math.abs(n)<=1e12)) throw new Error('Instance inverse transform is out of range.');
+  return {transform:freeze(m),inverse:freeze(inv.map(n=>n===0?0:n)),handedness:Math.sign(determinant)};
+}
+
+export function transformInstancePoint(m, p) {
+  return [0,1,2].map(r=>m[r]*p[0]+m[4+r]*p[1]+m[8+r]*p[2]+m[12+r]);
+}
+
+function meshBounds(mesh) {
+  const localMin=[Infinity,Infinity,Infinity],localMax=[-Infinity,-Infinity,-Infinity];
+  for(let i=0;i<mesh.positions.length;i+=3) for(let a=0;a<3;a++) {
+    localMin[a]=Math.min(localMin[a],Math.fround(mesh.positions[i+a]));localMax[a]=Math.max(localMax[a],Math.fround(mesh.positions[i+a]));
+  }
+  return {min:localMin,max:localMax};
+}
+
+function boundsOf(local, transform) {
+  const localMin=local.min,localMax=local.max;
+  const min=[Infinity,Infinity,Infinity],max=[-Infinity,-Infinity,-Infinity];
+  for(let corner=0;corner<8;corner++) {
+    const p=transformInstancePoint(transform,[0,1,2].map(a=>(corner&(1<<a))?localMax[a]:localMin[a]));
+    for(let a=0;a<3;a++){min[a]=Math.min(min[a],p[a]);max[a]=Math.max(max[a],p[a]);}
+  }
+  if(![...min,...max].every(Number.isFinite)) throw new Error('Instance mesh has invalid bounds.');
+  return freeze({min:freeze(min),max:freeze(max)});
+}
+
+export function prepareWavefrontInstances(meshes, instances) {
+  if(!Array.isArray(instances)||instances.length===0) throw new Error('Instances must be a nonempty array.');
+  const byId=new Map(),localBounds=new Map();
+  for(const mesh of meshes) {
+    if(!uint(mesh.id)||byId.has(mesh.id)) throw new Error('Instanced mesh IDs must be unique unsigned integers.');
+    if(mesh.materialKind===MATERIAL_EMISSIVE||emissionPower(mesh.emission??[0,0,0,1])>0.0001) {
+      throw new Error('Instanced emissive meshes require per-instance light sampling, which is not supported yet.');
+    }
+    byId.set(mesh.id,mesh);localBounds.set(mesh.id,meshBounds(mesh));
+  }
+  const ids=new Set(),used=new Set();
+  const records=instances.map(instance=>{
+    if(!instance||!uint(instance.id)||ids.has(instance.id)) throw new Error('Instance IDs must be unique unsigned integers.');
+    const mesh=byId.get(instance.meshId);
+    if(!mesh) throw new Error('Instance references an unknown mesh.');
+    ids.add(instance.id);used.add(mesh.id);
+    const affine=affineTransform(instance.transform);
+    const bounds=boundsOf(localBounds.get(mesh.id),affine.transform);
+    return freeze({...affine,id:instance.id,meshId:mesh.id,bounds,
+      centroid:freeze(bounds.min.map((v,a)=>(v+bounds.max[a])/2))});
+  });
+  if(used.size!==meshes.length) throw new Error('Every instanced mesh must have at least one instance.');
+  return freeze({records:freeze(records),geometryCount:meshes.length});
+}
+
+export function buildWavefrontInstances(meshes, plan, materialSource) {
+  const tlas=buildWavefrontBoundsBvh(plan.records,1);
+  // Outward padding covers f32 matrix multiplication and packed-bound rounding.
+  const nodes=tlas.nodes.map(node=>{
+    const pad=node.bounds.min.map((v,a)=>Math.max(1,Math.abs(v),Math.abs(node.bounds.max[a]))*1e-6);
+    return freeze({...node,bounds:freeze({min:freeze(node.bounds.min.map((v,a)=>v-pad[a])),
+      max:freeze(node.bounds.max.map((v,a)=>v+pad[a]))})});
+  }),triangles=[],roots=new Map();
+  for(const [meshIndex,mesh] of meshes.entries()) {
+    const blas=createWavefrontMeshAcceleration([mesh],materialSource);
+    const nodeOffset=nodes.length,triangleOffset=triangles.length;
+    roots.set(mesh.id,nodeOffset);
+    for(const node of blas.nodes) nodes.push(freeze({...node,
+      firstTriangle:node.firstTriangle+(node.triangleCount>0?triangleOffset:nodeOffset),
+      leftChild:node.leftChild+nodeOffset,rightChild:node.rightChild+nodeOffset}));
+    for(const triangle of blas.triangles) triangles.push(freeze({...triangle,
+      triangleId:triangle.triangleId+triangleOffset,materialSlot:meshIndex}));
+  }
+  const records=tlas.triangles.map(record=>freeze({...record,root:roots.get(record.meshId)}));
+  const buffer=new ArrayBuffer(records.length*WAVEFRONT_INSTANCE_BYTES);
+  const floats=new Float32Array(buffer),uints=new Uint32Array(buffer);
+  records.forEach((record,index)=>{
+    const offset=index*36;
+    floats.set(record.transform,offset);floats.set(record.inverse,offset+16);
+    uints[offset+32]=record.id;uints[offset+33]=record.root;floats[offset+34]=record.handedness;
+  });
+  return freeze({records:freeze(records),buffer,instanceCount:records.length,
+    geometryCount:meshes.length,instanceBytes:buffer.byteLength,tlasNodeCount:tlas.nodes.length,
+    blasNodeCount:nodes.length-tlas.nodes.length,
+    acceleration:freeze({nodes:freeze(nodes),triangles:freeze(triangles)})});
+}