@plasius/gpu-renderer 0.2.57 → 0.2.58

package/package.json

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

package/src/index.d.ts

@@ -1050,8 +1050,10 @@ export interface WavefrontPathTracingMemoryEstimate {
   readonly pathVertexBytes: number;
   readonly sceneObjectBytes: number;
   readonly triangleBytes: number;
-  /** Instance lookup texture bytes; separate from totalHotBufferBytes. */
+  /** 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;
@@ -1417,6 +1419,8 @@ export function estimateWavefrontPathTracingMemory(options?: {
   maxDepth?: number;
   sceneObjectCapacity?: number;
   triangleCapacity?: number;
+  instanceBytes?: number;
+  instanceTextureBytes?: number;
   materialCapacity?: number;
   bvhNodeCapacity?: number;
   bvhLeafSortCapacity?: number;

package/src/wavefront-compute.js

@@ -1,4 +1,5 @@
 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 {
@@ -242,12 +243,10 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
   const memory = config.memory;
   let instanceTexture = null, instanceView = null;
   if(config.instancing) {
-    const count=config.instancing.instanceCount;
-    instanceTexture=device.createTexture({label:"plasius.wavefront.instances",size:{width:9,height:count},
+    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});
-    const upload=new Uint8Array(count*256),source=new Uint8Array(config.instancing.buffer);
-    for(let i=0;i<count;i++) upload.set(source.subarray(i*144,(i+1)*144),i*256);
-    device.queue.writeTexture({texture:instanceTexture},upload,{bytesPerRow:256,rowsPerImage:count},{width:9,height:count,depthOrArrayLayers:1});
+    await uploadInstanceTexture(device,instanceTexture,config.instancing.buffer,layout);
     instanceView=instanceTexture.createView();
   }
   const activeQueue = createBuffer(device, bufferUsage, memory.queueBytes, "plasius.wavefront.activeQueue");

package/src/wavefront-config.js

@@ -1,4 +1,5 @@
-import { prepareWavefrontInstances, buildWavefrontInstances } from './wavefront-instances.js';
+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,
@@ -359,6 +360,7 @@ export function estimateWavefrontPathTracingMemory(options = {}) {
   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;
@@ -434,6 +436,7 @@ export function estimateWavefrontPathTracingMemory(options = {}) {
     sceneObjectBytes,
     triangleBytes,
     instanceBytes,
+    instanceTextureBytes,
     materialTableBytes,
     bvhNodeBytes,
     bvhCombinedBytes,
@@ -465,6 +468,7 @@ export function estimateWavefrontPathTracingMemoryForConfig(config, limits = {})
     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,
@@ -519,7 +523,9 @@ export function createWavefrontPathTracingComputeConfig(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 geometryMinimumBytes = meshSourceShape.triangleCount * TRIANGLE_RECORD_BYTES + (options.instances?.length ?? 0) * 144;
+    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);

package/src/wavefront-instance-shader.js

@@ -9,17 +9,19 @@ struct MeshInstance {
 };
 @group(0) @binding(47) var meshInstances: texture_2d<u32>;
 fn read_mesh_instance(index: u32) -> MeshInstance {
-  let y = i32(index);
-  let metadata = textureLoad(meshInstances, vec2<i32>(8, y), 0);
+  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>(0, y), 0)),
-      bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(1, y), 0)),
-      bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(2, y), 0)),
-      bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(3, y), 0))),
-    mat4x4<f32>(bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(4, y), 0)),
-      bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(5, y), 0)),
-      bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(6, y), 0)),
-      bitcast<vec4<f32>>(textureLoad(meshInstances, vec2<i32>(7, y), 0))),
+    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);
 }
 

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 });
+  }
+}