@forgeax/engine-render 0.1.21 → 0.1.24

package/src/gpu-scene.ts

@@ -37,6 +37,8 @@ interface PrimitiveAllocation {
   readonly instanceStart: number;
   readonly instanceCount: number;
   readonly transformStart: number;
+  readonly instanceTransformStart: number;
+  readonly instanceTransformCount: number;
   readonly drawStart: number;
   readonly drawCount: number;
   readonly materialStart: number;
@@ -85,8 +87,8 @@ class StableRangeAllocator {
     return this.next;
   }
 
-  reset(): void {
-    this.next = 0;
+  reset(start = 0): void {
+    this.next = start;
     this.free.length = 0;
   }
 }
@@ -177,7 +179,14 @@ function stableU32(value: string): number {
 function coalesceSlots(
   slots: readonly number[],
 ): readonly { readonly start: number; readonly end: number }[] {
-  const ordered = [...new Set(slots)].sort((a, b) => a - b);
+  let alreadyOrdered = true;
+  for (let index = 1; index < slots.length; index += 1) {
+    if ((slots[index] ?? 0) <= (slots[index - 1] ?? 0)) {
+      alreadyOrdered = false;
+      break;
+    }
+  }
+  const ordered = alreadyOrdered ? slots : [...new Set(slots)].sort((a, b) => a - b);
   const ranges: Array<{ start: number; end: number }> = [];
   for (const slot of ordered) {
     const previous = ranges.at(-1);
@@ -192,7 +201,10 @@ function coalesceSlots(
 
 /** Persistent GPU tables derived only from renderer projection slots. */
 export class GpuScene {
+  private disposed = false;
   private tableBytes: Record<GpuSceneTableName, ArrayBuffer>;
+  private transformBytes: Uint8Array;
+  private transformView: DataView;
   private buffers: GpuSceneBuffers;
   private uploadRanges = 0;
   private uploadBytes = 0;
@@ -200,11 +212,19 @@ export class GpuScene {
   private fullRebuilds = 0;
   private clearedSlots = 0;
   private noChangeFrames = 0;
-  private readonly allocations = new Map<number, PrimitiveAllocation>();
+  private identityUploaded = false;
+  private readonly allocations: Array<PrimitiveAllocation | undefined> = [];
   private readonly instances = new StableRangeAllocator();
   private readonly transforms = new StableRangeAllocator();
   private readonly draws = new StableRangeAllocator();
   private readonly materials = new StableRangeAllocator();
+  private readonly writesByTable: Record<GpuSceneTableName, number[]> = {
+    primitive: [],
+    instance: [],
+    transform: [],
+    drawTemplate: [],
+    material: [],
+  };
 
   private constructor(
     private readonly device: RhiDevice,
@@ -213,6 +233,10 @@ export class GpuScene {
   ) {
     this.buffers = buffers;
     this.tableBytes = this.allocateCpuTables(capacity);
+    this.transformBytes = new Uint8Array(this.tableBytes.transform);
+    this.transformView = new DataView(this.tableBytes.transform);
+    this.transforms.reset(1);
+    this.writeIdentityTransform();
   }
 
   static create(device: RhiDevice, initialCapacity = 256): Result<GpuSceneAvailability, RhiError> {
@@ -249,25 +273,33 @@ export class GpuScene {
   }
 
   sync(delta: RenderSceneApplyResult): Result<GpuSceneSyncResult, RhiError> {
-    const writes = [...delta.createdSlots, ...delta.updatedSlots, ...delta.recreatedSlots];
-    const changedSlots = [
-      ...writes.map((record) => record.slot),
-      ...delta.removedSlots.map((r) => r.slot),
-    ];
-    if (changedSlots.length === 0) {
+    if (
+      delta.createdSlots.length === 0 &&
+      delta.updatedSlots.length === 0 &&
+      delta.recreatedSlots.length === 0 &&
+      delta.removedSlots.length === 0
+    ) {
       this.noChangeFrames += 1;
       return ok({ ranges: 0, bytes: 0, grew: false, cleared: 0 });
     }
-    const writesByTable: Record<GpuSceneTableName, number[]> = {
-      primitive: [],
-      instance: [],
-      transform: [],
-      drawTemplate: [],
-      material: [],
-    };
-    for (const record of writes) this.ensureAllocation(record, writesByTable);
+    const writesByTable = this.writesByTable;
+    for (const name of TABLE_NAMES) writesByTable[name].length = 0;
+    if (!this.identityUploaded) writesByTable.transform.push(0);
+    let highestChangedSlot = -1;
+    for (const records of [delta.createdSlots, delta.recreatedSlots]) {
+      for (const record of records) {
+        this.ensureAllocation(record, writesByTable);
+        if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
+      }
+    }
+    for (const record of delta.updatedSlots) {
+      if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
+    }
+    for (const record of delta.removedSlots) {
+      if (record.slot > highestChangedSlot) highestChangedSlot = record.slot;
+    }
     const requiredCapacity = Math.max(
-      Math.max(...changedSlots) + 1,
+      highestChangedSlot + 1,
       this.instances.requiredCapacity(),
       this.transforms.requiredCapacity(),
       this.draws.requiredCapacity(),
@@ -280,11 +312,12 @@ export class GpuScene {
     }
 
     for (const record of delta.createdSlots) this.writeSlot(record, true, writesByTable);
-    for (const record of delta.updatedSlots) this.writeSlot(record, false, writesByTable);
+    for (const record of delta.updatedSlots) this.writeRootTransform(record, false, writesByTable);
     for (const record of delta.recreatedSlots) this.writeSlot(record, true, writesByTable);
     for (const record of delta.removedSlots) this.clearSlot(record.slot, writesByTable);
     const uploaded = this.uploadRows(writesByTable);
     if (!uploaded.ok) return uploaded;
+    this.identityUploaded = true;
     this.clearedSlots += delta.removedSlots.length;
     return ok({
       ranges: uploaded.value.ranges,
@@ -295,10 +328,11 @@ export class GpuScene {
   }
 
   /** Publish current transforms as previous only after a successful submit. */
-  commitTemporalFrame(): Result<void, RhiError> {
+  commitTemporalFrame(enabled = true): Result<void, RhiError> {
+    if (!enabled) return ok(undefined);
     const nextTransform = this.tableBytes.transform.slice(0);
     const next = new Uint8Array(nextTransform);
-    const current = new Uint8Array(this.tableBytes.transform);
+    const current = this.transformBytes;
     const currentOffset = offset(TRANSFORM, 'currentWorld');
     const previousOffset = offset(TRANSFORM, 'previousWorld');
     for (let index = 0; index < this.capacity; index += 1) {
@@ -313,15 +347,16 @@ export class GpuScene {
     const uploaded = this.device.queue.writeBuffer(this.buffers.transform, 0, next);
     if (!uploaded.ok) return uploaded;
     this.tableBytes.transform = nextTransform;
+    this.refreshTransformViews();
     this.uploadRanges += 1;
     this.uploadBytes += next.byteLength;
     return ok(undefined);
   }
 
   rebuild(slots: readonly RenderSceneSlot[]): Result<GpuSceneSyncResult, RhiError> {
-    this.allocations.clear();
+    this.allocations.length = 0;
     this.instances.reset();
-    this.transforms.reset();
+    this.transforms.reset(1);
     this.draws.reset();
     this.materials.reset();
     const writesByTable: Record<GpuSceneTableName, number[]> = {
@@ -347,6 +382,7 @@ export class GpuScene {
       grew = true;
     }
     for (const bytes of Object.values(this.tableBytes)) new Uint8Array(bytes).fill(0);
+    this.writeIdentityTransform();
     for (const slot of slots) this.writeSlot(slot, true, writesByTable);
     let bytes = 0;
     for (const name of TABLE_NAMES) {
@@ -358,6 +394,7 @@ export class GpuScene {
     this.uploadRanges += TABLE_NAMES.length;
     this.uploadBytes += bytes;
     this.fullRebuilds += 1;
+    this.identityUploaded = true;
     return ok({ ranges: TABLE_NAMES.length, bytes, grew, cleared: 0 });
   }
 
@@ -396,6 +433,8 @@ export class GpuScene {
   }
 
   dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
     for (const buffer of Object.values(this.buffers)) this.device.destroyBuffer(buffer);
   }
 
@@ -404,7 +443,7 @@ export class GpuScene {
     resetPrevious: boolean,
     writes: Record<GpuSceneTableName, number[]>,
   ): void {
-    const allocation = this.allocations.get(record.slot);
+    const allocation = this.allocations[record.slot];
     if (allocation === undefined) throw new RangeError('GPU Scene allocation unavailable');
     const primitiveOffset = record.slot * PRIMITIVE.stride;
     const primitive = new DataView(this.tableBytes.primitive);
@@ -461,45 +500,34 @@ export class GpuScene {
     ]);
 
     const instance = new DataView(this.tableBytes.instance);
-    const transform = new DataView(this.tableBytes.transform);
+    const transform = this.transformView;
     for (let ordinal = 0; ordinal < allocation.instanceCount; ordinal += 1) {
       const instanceIndex = allocation.instanceStart + ordinal;
       const instanceOffset = instanceIndex * INSTANCE.stride;
-      const transformIndex = allocation.transformStart + 1 + ordinal;
+      const transformIndex =
+        allocation.instanceTransformCount === 0 ? 0 : allocation.instanceTransformStart + ordinal;
       instance.setUint32(instanceOffset + offset(INSTANCE, 'primitiveIndex'), record.slot, true);
       instance.setUint32(instanceOffset + offset(INSTANCE, 'transformIndex'), transformIndex, true);
       instance.setUint32(instanceOffset + offset(INSTANCE, 'customDataStart'), 0, true);
       instance.setUint32(instanceOffset + offset(INSTANCE, 'flags'), PRIMITIVE_ACTIVE, true);
-      const local = record.snapshot.instances?.transforms.subarray(ordinal * 16, ordinal * 16 + 16);
-      const localWorld = local?.length === 16 ? local : IDENTITY_MATRIX;
-      const localOffset = transformIndex * TRANSFORM.stride;
-      const localCurrentOffset = localOffset + offset(TRANSFORM, 'currentWorld');
-      const localPreviousOffset = localOffset + offset(TRANSFORM, 'previousWorld');
-      const priorLocal = new Uint8Array(
-        this.tableBytes.transform.slice(localCurrentOffset, localCurrentOffset + 64),
-      );
-      writeMat4(transform, localCurrentOffset, localWorld);
-      if (!resetPrevious && priorLocal.some((value) => value !== 0)) {
-        new Uint8Array(this.tableBytes.transform, localPreviousOffset, 64).set(priorLocal);
-      } else {
+      if (allocation.instanceTransformCount > 0) {
+        const local = record.snapshot.instances?.transforms.subarray(
+          ordinal * 16,
+          ordinal * 16 + 16,
+        );
+        const localWorld = local?.length === 16 ? local : IDENTITY_MATRIX;
+        const localOffset = transformIndex * TRANSFORM.stride;
+        const localCurrentOffset = localOffset + offset(TRANSFORM, 'currentWorld');
+        const localPreviousOffset = localOffset + offset(TRANSFORM, 'previousWorld');
+        writeMat4(transform, localCurrentOffset, localWorld);
         writeMat4(transform, localPreviousOffset, localWorld);
+        writes.transform.push(transformIndex);
       }
       writes.instance.push(instanceIndex);
-      writes.transform.push(transformIndex);
     }
 
-    const transformOffset = allocation.transformStart * TRANSFORM.stride;
-    const currentOffset = transformOffset + offset(TRANSFORM, 'currentWorld');
-    const previousOffset = transformOffset + offset(TRANSFORM, 'previousWorld');
-    const priorCurrent = new Uint8Array(
-      this.tableBytes.transform.slice(currentOffset, currentOffset + 64),
-    );
-    const hasPrior = !resetPrevious && priorCurrent.some((value) => value !== 0);
-    writeMat4(transform, currentOffset, record.snapshot.transform.world);
-    if (hasPrior) new Uint8Array(this.tableBytes.transform, previousOffset, 64).set(priorCurrent);
-    else writeMat4(transform, previousOffset, record.snapshot.transform.world);
+    this.writeRootTransform(record, resetPrevious, writes);
     writes.primitive.push(record.slot);
-    writes.transform.push(allocation.transformStart);
 
     const draw = new DataView(this.tableBytes.drawTemplate);
     const drawSnapshots = record.snapshot.gpuDrivenDraws ?? [];
@@ -509,7 +537,13 @@ export class GpuScene {
       const drawSnapshot = drawSnapshots[ordinal];
       draw.setUint32(
         drawOffset + offset(DRAW_TEMPLATE, 'pipelineClass'),
-        drawSnapshot === undefined ? 0 : stableU32(drawSnapshot.pipelineClass),
+        drawSnapshot === undefined
+          ? 0
+          : stableU32(
+              drawSnapshot.prepared === undefined
+                ? drawSnapshot.pipelineClass
+                : `${drawSnapshot.prepared.identity.material}|${drawSnapshot.prepared.identity.geometry}|${drawSnapshot.prepared.identity.deformation}`,
+            ),
         true,
       );
       draw.setUint32(
@@ -519,17 +553,17 @@ export class GpuScene {
       );
       draw.setUint32(
         drawOffset + offset(DRAW_TEMPLATE, 'firstIndex'),
-        drawSnapshot?.first ?? 0,
+        drawSnapshot?.prepared?.first ?? drawSnapshot?.first ?? 0,
         true,
       );
       draw.setUint32(
         drawOffset + offset(DRAW_TEMPLATE, 'indexCount'),
-        drawSnapshot?.count ?? 0,
+        drawSnapshot?.prepared?.count ?? drawSnapshot?.count ?? 0,
         true,
       );
       draw.setInt32(
         drawOffset + offset(DRAW_TEMPLATE, 'baseVertex'),
-        drawSnapshot?.baseVertex ?? 0,
+        drawSnapshot?.prepared?.baseVertex ?? drawSnapshot?.baseVertex ?? 0,
         true,
       );
       draw.setUint32(drawOffset + offset(DRAW_TEMPLATE, 'firstInstance'), 0, true);
@@ -552,8 +586,6 @@ export class GpuScene {
       writeVec4(material, materialOffset + offset(MATERIAL, 'params1'), [
         snapshot.metallic ?? 0,
         snapshot.roughness ?? 1,
-        snapshot.clearcoat ?? 0,
-        snapshot.clearcoatRoughness ?? 0,
       ]);
       writeVec4(material, materialOffset + offset(MATERIAL, 'params2'), [
         snapshot.emissive?.[0] ?? 0,
@@ -591,16 +623,35 @@ export class GpuScene {
     }
   }
 
+  private writeRootTransform(
+    record: RenderSceneSlot,
+    resetPrevious: boolean,
+    writes: Record<GpuSceneTableName, number[]>,
+  ): void {
+    const allocation = this.allocations[record.slot];
+    if (allocation === undefined) throw new RangeError('GPU Scene allocation unavailable');
+    const transformOffset = allocation.transformStart * TRANSFORM.stride;
+    const currentOffset = transformOffset + offset(TRANSFORM, 'currentWorld');
+    const previousOffset = transformOffset + offset(TRANSFORM, 'previousWorld');
+    if (resetPrevious) {
+      writeMat4(this.transformView, previousOffset, record.snapshot.transform.world);
+    } else {
+      this.transformBytes.copyWithin(previousOffset, currentOffset, currentOffset + 64);
+    }
+    writeMat4(this.transformView, currentOffset, record.snapshot.transform.world);
+    writes.transform.push(allocation.transformStart);
+  }
+
   private clearSlot(slot: number, writes: Record<GpuSceneTableName, number[]>): void {
     for (const name of ['primitive'] as const) {
       const layout = TABLE_LAYOUTS[name];
       new Uint8Array(this.tableBytes[name], slot * layout.stride, layout.stride).fill(0);
       writes[name].push(slot);
     }
-    const allocation = this.allocations.get(slot);
+    const allocation = this.allocations[slot];
     if (allocation === undefined) return;
     this.clearAllocation(allocation, writes);
-    this.allocations.delete(slot);
+    this.allocations[slot] = undefined;
   }
 
   private uploadRows(
@@ -637,15 +688,18 @@ export class GpuScene {
     // empty: preserve zero so neither the GPU Scene nor the indirect topology
     // turns it into a synthetic identity instance. Entities without the
     // component retain the ordinary one-instance identity path.
+    const explicitInstances = record.snapshot.instances;
     const instanceCount =
-      record.snapshot.instances === undefined
+      explicitInstances === undefined
         ? 1
-        : Math.max(0, Math.floor(record.snapshot.instances.instanceCount));
+        : Math.max(0, Math.floor(explicitInstances.instanceCount));
+    const instanceTransformCount = explicitInstances === undefined ? 0 : instanceCount;
     const drawCount = Math.max(1, record.snapshot.gpuDrivenDraws?.length ?? 0);
     const materialCount = Math.max(1, record.snapshot.materials.length);
-    const existing = this.allocations.get(record.slot);
+    const existing = this.allocations[record.slot];
     if (
       existing?.instanceCount === instanceCount &&
+      existing.instanceTransformCount === instanceTransformCount &&
       existing.drawCount === drawCount &&
       existing.materialCount === materialCount
     ) {
@@ -655,13 +709,16 @@ export class GpuScene {
     const allocation = {
       instanceStart: this.instances.allocate(instanceCount),
       instanceCount,
-      transformStart: this.transforms.allocate(instanceCount + 1),
+      transformStart: this.transforms.allocate(1),
+      instanceTransformStart:
+        instanceTransformCount === 0 ? 0 : this.transforms.allocate(instanceTransformCount),
+      instanceTransformCount,
       drawStart: this.draws.allocate(drawCount),
       drawCount,
       materialStart: this.materials.allocate(materialCount),
       materialCount,
     };
-    this.allocations.set(record.slot, allocation);
+    this.allocations[record.slot] = allocation;
   }
 
   private clearAllocation(
@@ -677,8 +734,9 @@ export class GpuScene {
       ).fill(0);
       writes.instance.push(instanceIndex);
     }
-    for (let ordinal = 0; ordinal <= allocation.instanceCount; ordinal += 1) {
-      const transformIndex = allocation.transformStart + ordinal;
+    for (let ordinal = -1; ordinal < allocation.instanceTransformCount; ordinal += 1) {
+      const transformIndex =
+        ordinal < 0 ? allocation.transformStart : allocation.instanceTransformStart + ordinal;
       new Uint8Array(
         this.tableBytes.transform,
         transformIndex * TRANSFORM.stride,
@@ -705,7 +763,8 @@ export class GpuScene {
       writes.material.push(materialIndex);
     }
     this.instances.release(allocation.instanceStart, allocation.instanceCount);
-    this.transforms.release(allocation.transformStart, allocation.instanceCount + 1);
+    this.transforms.release(allocation.transformStart, 1);
+    this.transforms.release(allocation.instanceTransformStart, allocation.instanceTransformCount);
     this.draws.release(allocation.drawStart, allocation.drawCount);
     this.materials.release(allocation.materialStart, allocation.materialCount);
   }
@@ -731,6 +790,7 @@ export class GpuScene {
     for (const buffer of Object.values(this.buffers)) this.device.destroyBuffer(buffer);
     this.buffers = nextBuffers.value;
     this.tableBytes = nextTables;
+    this.refreshTransformViews();
     this.capacity = nextCapacity;
     this.capacityGrows += 1;
     this.uploadRanges += TABLE_NAMES.length;
@@ -750,4 +810,14 @@ export class GpuScene {
       material: new ArrayBuffer(capacity * MATERIAL.stride),
     };
   }
+
+  private refreshTransformViews(): void {
+    this.transformBytes = new Uint8Array(this.tableBytes.transform);
+    this.transformView = new DataView(this.tableBytes.transform);
+  }
+
+  private writeIdentityTransform(): void {
+    writeMat4(this.transformView, offset(TRANSFORM, 'currentWorld'), IDENTITY_MATRIX);
+    writeMat4(this.transformView, offset(TRANSFORM, 'previousWorld'), IDENTITY_MATRIX);
+  }
 }

package/src/gpu-usage.ts

@@ -12,5 +12,4 @@ export const GPU_BUFFER_USAGE_UNIFORM = 0x40;
 export const GPU_BUFFER_USAGE_STORAGE = 0x80;
 export const GPU_BUFFER_USAGE_INDIRECT = 0x100;
 export const GPU_BUFFER_USAGE_MAP_READ = 0x01;
-/** GPUBufferUsage.QUERY_RESOLVE, used by optional timestamp captures. */
 export const GPU_BUFFER_USAGE_QUERY_RESOLVE = 0x200;

package/src/hdrp-buffers.ts

@@ -19,7 +19,7 @@
 // usage owner; this module stays decoupled from renderer bootstrap.
 //
 // Sizes:
-//   - light_data        : 256 x 64 B  = 16 384 B
+//   - light_data        : 256 x 80 B  = 20 480 B
 //   - cluster_grid      : maxGridCells x 8 B = 64 x 64 x 64 x 8 B = 2 097 152 B max
 //                         (plan D-grid: x,y,z each in [1..64]; maxCells=262144;
 //                          stride 2 u32 = 8B; we allocate at the install-time
@@ -47,7 +47,7 @@ import {
   GPU_BUFFER_USAGE_STORAGE,
   GPU_BUFFER_USAGE_UNIFORM,
 } from './gpu-usage';
-import { BYTES_PER_LIGHT_SLOT } from './light-buffer-layout';
+import { BYTES_PER_DIRECT_LIGHT_SLOT } from './light-buffer-layout';
 import { createPbrSkinMeshBindGroupEntries } from './pbr-pipeline';
 import {
   CLUSTER_GRID_STRIDE_U32,
@@ -95,8 +95,8 @@ export function createHdrpClusterMembershipBindGroupLayoutDescriptor(): BindGrou
  * The persistent HDRP GPU buffers (plan D-1, BGL slot 3..6) plus the unified
  * BGL layout for group(2) (plan D-6, feat-20260609-hdrp-cluster-fragment-ggx M3).
  *
- * AC-11: light_data stride = `BYTES_PER_LIGHT_SLOT` = 64 (double-sided lock with
- * WGSL hdrp-cluster-forward.wgsl LightSlot).
+ * AC-11: light_data stride = `BYTES_PER_DIRECT_LIGHT_SLOT` = 80 (double-sided
+ * lock with WGSL hdrp-cluster-forward.wgsl DirectLightSlot).
  * AC-13: 4 distinct RHI Buffer handles, ready for slot-3..6 BGL binding.
  * AC-14: clusterUniform is a uniform buffer (not storage); runtime grid change
  * is a writeBuffer field update, not a PSO rebuild.
@@ -106,7 +106,7 @@ export function createHdrpClusterMembershipBindGroupLayoutDescriptor(): BindGrou
 export interface HdrpBuffers {
   /** Device identity that owns every handle in this bundle. */
   readonly device: RenderSystemRuntime['device'];
-  /** light_data -- the full 256 x 64 B Standard light budget. */
+  /** light_data -- the full 256 x 80 B DirectLightSlot budget. */
   readonly lightDataBuffer: Buffer;
   readonly lightDataBytes: number;
   /** cluster_grid SSBO -- gridX*gridY*gridZ * 2 u32, BGL slot 4. */
@@ -175,7 +175,7 @@ export function getOrCreateHdrpBuffers(
   }
   const device = runtime.device;
   const clusterUniformBytes = 32;
-  const lightDataBytes = MAX_LIGHTS * BYTES_PER_LIGHT_SLOT;
+  const lightDataBytes = MAX_LIGHTS * BYTES_PER_DIRECT_LIGHT_SLOT;
   const clusterCells = grid.x * grid.y * grid.z;
   const clusterGridBytes = clusterCells * CLUSTER_GRID_STRIDE_U32 * 4;
   const lightIndexListBytes = LIGHT_INDEX_LIST_CAPACITY * 4;