@forgeax/engine-render 0.1.33 → 0.1.34

package/src/gpu-scene.ts

@@ -1,6 +1,7 @@
 import type { Buffer, Result, RhiDevice } from '@forgeax/engine-rhi';
 import { err, ok, RhiError } from '@forgeax/engine-rhi';
 import { createStandardPbrArtifactReceipt } from '@forgeax/engine-shader';
+import { GpuDirtyRanges } from './gpu-dirty-ranges';
 import {
   GPU_SCENE_LAYOUTS,
   type GpuSceneTableLayout,
@@ -13,6 +14,7 @@ import {
 } from './gpu-usage';
 import type { GpuSceneInspection } from './inspection-types';
 import { packMaterialProgramRow, packStandardPbrMaterialRow } from './material-row';
+import type { MaterialSnapshot } from './render-system-extract';
 import type { RenderSceneApplyResult, RenderSceneSlot } from './scene/render-scene-types';
 
 export type { GpuSceneInspection } from './inspection-types';
@@ -206,22 +208,6 @@ function stableU32(value: string): number {
   return hash >>> 0;
 }
 
-function coalesceSlots(
-  slots: readonly number[],
-): readonly { readonly start: number; readonly end: number }[] {
-  const ordered = [...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);
-    if (previous !== undefined && previous.end === slot) {
-      previous.end = slot + 1;
-    } else {
-      ranges.push({ start: slot, end: slot + 1 });
-    }
-  }
-  return ranges;
-}
-
 /**
  * Build a lookup from the current instance identity to its submitted ordinal.
  * The GPU table is physically compacted by ordinal, so this small CPU lookup
@@ -274,6 +260,9 @@ function instanceIdentityChanged(
 
 /** Persistent GPU tables derived only from renderer projection slots. */
 export class GpuScene {
+  private readonly dirtyRanges = new GpuDirtyRanges();
+  private readonly rowScratch = new Uint8Array(Math.max(PRIMITIVE.stride, DRAW_TEMPLATE.stride));
+  private readonly rowScratchView = new DataView(this.rowScratch.buffer);
   private disposed = false;
   private tableBytes: Record<GpuSceneTableName, ArrayBuffer>;
   private transformBytes: Uint8Array;
@@ -444,6 +433,9 @@ export class GpuScene {
       if (!grown.ok) return grown;
     }
 
+    // A shared material has one packed value per publication, independent of
+    // how many primitives reference it. Do not retain mutable caller snapshots.
+    const materialRows = new Map<MaterialSnapshot, Uint8Array>();
     const publications = [...delta.createdSlots, ...delta.updatedSlots, ...delta.recreatedSlots];
     const newSlots = new Set(
       [...delta.createdSlots, ...delta.recreatedSlots].map((record) => record.slot),
@@ -451,7 +443,7 @@ export class GpuScene {
     for (const record of publications) {
       const reset = newSlots.has(record.slot) || allocationResets.has(record.slot);
       if (reset || contentUpdatedSlotIds.has(record.slot)) {
-        this.writeSlot(record, reset, writesByTable, temporalResolver?.(record));
+        this.writeSlot(record, reset, writesByTable, materialRows, temporalResolver?.(record));
         continue;
       }
       if (instanceUpdatedSlotIds.has(record.slot))
@@ -483,7 +475,7 @@ export class GpuScene {
     if (this.pendingTemporalTransforms.size === 0) return ok(undefined);
     const currentOffset = offset(TRANSFORM, 'currentWorld');
     const previousOffset = offset(TRANSFORM, 'previousWorld');
-    const ranges = coalesceSlots([...this.pendingTemporalTransforms]);
+    const ranges = this.dirtyRanges.coalesce([...this.pendingTemporalTransforms]);
     for (const range of ranges) {
       for (let index = range.start; index < range.end; index += 1) {
         this.pendingTemporalUploads.add(index);
@@ -549,7 +541,8 @@ export class GpuScene {
     }
     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);
+    const materialRows = new Map<MaterialSnapshot, Uint8Array>();
+    for (const slot of slots) this.writeSlot(slot, true, writesByTable, materialRows);
     let bytes = 0;
     for (const name of TABLE_NAMES) {
       const table = this.tableBytes[name];
@@ -610,64 +603,44 @@ export class GpuScene {
     record: RenderSceneSlot,
     resetPrevious: boolean,
     writes: Record<GpuSceneTableName, number[]>,
+    materialRows: Map<MaterialSnapshot, Uint8Array>,
     temporal?: GpuSceneTemporalSnapshot,
   ): void {
     const allocation = this.allocations.get(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);
+    this.rowScratch.fill(0);
+    const primitive = this.rowScratchView;
     const bounds = record.snapshot.localAabb;
-    primitive.setUint32(primitiveOffset + offset(PRIMITIVE, 'generation'), record.generation, true);
+    primitive.setUint32(offset(PRIMITIVE, 'generation'), record.generation, true);
     primitive.setUint32(
-      primitiveOffset + offset(PRIMITIVE, 'flags'),
+      offset(PRIMITIVE, 'flags'),
       PRIMITIVE_ACTIVE |
         (bounds === undefined ? 0 : PRIMITIVE_HAS_BOUNDS) |
         (record.snapshot.gpuDrivenDraws === undefined ? 0 : PRIMITIVE_GPU_DRIVEN),
       true,
     );
-    primitive.setUint32(
-      primitiveOffset + offset(PRIMITIVE, 'transformIndex'),
-      allocation.transformStart,
-      true,
-    );
-    primitive.setUint32(
-      primitiveOffset + offset(PRIMITIVE, 'materialIndex'),
-      allocation.materialStart,
-      true,
-    );
-    primitive.setUint32(
-      primitiveOffset + offset(PRIMITIVE, 'drawTemplateIndex'),
-      allocation.drawStart,
-      true,
-    );
-    primitive.setUint32(
-      primitiveOffset + offset(PRIMITIVE, 'instanceStart'),
-      allocation.instanceStart,
-      true,
-    );
-    primitive.setUint32(
-      primitiveOffset + offset(PRIMITIVE, 'instanceCount'),
-      allocation.instanceCount,
-      true,
-    );
-    primitive.setUint32(
-      primitiveOffset + offset(PRIMITIVE, 'assetHandle'),
-      record.snapshot.assetHandle,
-      true,
-    );
-    writeVec4(primitive, primitiveOffset + offset(PRIMITIVE, 'localBoundsMin'), [
+    primitive.setUint32(offset(PRIMITIVE, 'transformIndex'), allocation.transformStart, true);
+    primitive.setUint32(offset(PRIMITIVE, 'materialIndex'), allocation.materialStart, true);
+    primitive.setUint32(offset(PRIMITIVE, 'drawTemplateIndex'), allocation.drawStart, true);
+    primitive.setUint32(offset(PRIMITIVE, 'instanceStart'), allocation.instanceStart, true);
+    primitive.setUint32(offset(PRIMITIVE, 'instanceCount'), allocation.instanceCount, true);
+    primitive.setUint32(offset(PRIMITIVE, 'assetHandle'), record.snapshot.assetHandle, true);
+    writeVec4(primitive, offset(PRIMITIVE, 'localBoundsMin'), [
       bounds?.[0] ?? 0,
       bounds?.[1] ?? 0,
       bounds?.[2] ?? 0,
       0,
     ]);
-    writeVec4(primitive, primitiveOffset + offset(PRIMITIVE, 'localBoundsMax'), [
+    writeVec4(primitive, offset(PRIMITIVE, 'localBoundsMax'), [
       bounds?.[3] ?? 0,
       bounds?.[4] ?? 0,
       bounds?.[5] ?? 0,
       0,
     ]);
 
+    if (this.writeRow('primitive', record.slot, this.rowScratch) || resetPrevious)
+      writes.primitive.push(record.slot);
+
     const instance = new DataView(this.tableBytes.instance);
     const transform = this.transformView;
     const instances = record.snapshot.instances;
@@ -773,16 +746,15 @@ export class GpuScene {
     this.rememberInstanceGenerations(record.slot, currentGenerations, allocation.instanceCount);
 
     this.writeRootTransform(record, resetPrevious, writes);
-    writes.primitive.push(record.slot);
 
-    const draw = new DataView(this.tableBytes.drawTemplate);
+    const draw = this.rowScratchView;
     const drawSnapshots = record.snapshot.gpuDrivenDraws ?? [];
     for (let ordinal = 0; ordinal < allocation.drawCount; ordinal += 1) {
       const drawIndex = allocation.drawStart + ordinal;
-      const drawOffset = drawIndex * DRAW_TEMPLATE.stride;
+      this.rowScratch.fill(0);
       const drawSnapshot = drawSnapshots[ordinal];
       draw.setUint32(
-        drawOffset + offset(DRAW_TEMPLATE, 'pipelineClass'),
+        offset(DRAW_TEMPLATE, 'pipelineClass'),
         drawSnapshot === undefined
           ? 0
           : stableU32(
@@ -793,58 +765,77 @@ export class GpuScene {
         true,
       );
       draw.setUint32(
-        drawOffset + offset(DRAW_TEMPLATE, 'materialIndex'),
+        offset(DRAW_TEMPLATE, 'materialIndex'),
         allocation.materialStart + (drawSnapshot?.materialSlot ?? 0),
         true,
       );
       draw.setUint32(
-        drawOffset + offset(DRAW_TEMPLATE, 'firstIndex'),
+        offset(DRAW_TEMPLATE, 'firstIndex'),
         drawSnapshot?.prepared?.first ?? drawSnapshot?.first ?? 0,
         true,
       );
       draw.setUint32(
-        drawOffset + offset(DRAW_TEMPLATE, 'indexCount'),
+        offset(DRAW_TEMPLATE, 'indexCount'),
         drawSnapshot?.prepared?.count ?? drawSnapshot?.count ?? 0,
         true,
       );
       draw.setInt32(
-        drawOffset + offset(DRAW_TEMPLATE, 'baseVertex'),
+        offset(DRAW_TEMPLATE, 'baseVertex'),
         drawSnapshot?.prepared?.baseVertex ?? drawSnapshot?.baseVertex ?? 0,
         true,
       );
-      draw.setUint32(drawOffset + offset(DRAW_TEMPLATE, 'firstInstance'), 0, true);
-      draw.setUint32(drawOffset + offset(DRAW_TEMPLATE, 'passFlags'), 0, true);
-      draw.setUint32(drawOffset + offset(DRAW_TEMPLATE, 'reserved'), 0, true);
-      writes.drawTemplate.push(drawIndex);
+      draw.setUint32(offset(DRAW_TEMPLATE, 'firstInstance'), 0, true);
+      draw.setUint32(offset(DRAW_TEMPLATE, 'passFlags'), 0, true);
+      draw.setUint32(offset(DRAW_TEMPLATE, 'reserved'), 0, true);
+      if (this.writeRow('drawTemplate', drawIndex, this.rowScratch) || resetPrevious)
+        writes.drawTemplate.push(drawIndex);
     }
 
-    this.writeMaterialSlot(record, writes);
+    this.writeMaterialSlot(record, writes, materialRows, resetPrevious);
+  }
+
+  /** Compare against the resident CPU bytes; pending upload rows survive failure. */
+  private writeRow(table: GpuSceneTableName, index: number, row: Uint8Array): boolean {
+    const stride = TABLE_LAYOUTS[table].stride;
+    const destination = new Uint8Array(this.tableBytes[table], index * stride, stride);
+    let changed = false;
+    for (let byte = 0; byte < stride; byte += 1) {
+      const value = row[byte] ?? 0;
+      if (destination[byte] === value) continue;
+      destination[byte] = value;
+      changed = true;
+    }
+    return changed;
   }
 
   private writeMaterialSlot(
     record: RenderSceneSlot,
     writes: Record<GpuSceneTableName, number[]>,
+    materialRows: Map<MaterialSnapshot, Uint8Array>,
+    reset: boolean,
   ): void {
     const allocation = this.allocations.get(record.slot);
     if (allocation === undefined) throw new RangeError('GPU Scene allocation unavailable');
     for (let ordinal = 0; ordinal < allocation.materialCount; ordinal += 1) {
       const materialIndex = allocation.materialStart + ordinal;
-      const materialOffset = materialIndex * MATERIAL.stride;
       const snapshot = record.snapshot.materials[ordinal] ?? record.snapshot.material;
-      const shaderId = snapshot.materialShaderId;
-      const schema = snapshot.materialParamSchema;
-      const row =
-        shaderId !== undefined &&
-        shaderId !== 'forgeax::default-standard-pbr' &&
-        shaderId !== 'forgeax::pbr-skin' &&
-        shaderId !== 'forgeax::default-standard-pbr-skin' &&
-        schema !== undefined
-          ? packMaterialProgramRow(schema, snapshot, MATERIAL.stride)
-          : packStandardPbrMaterialRow(STANDARD_PBR_RECEIPT, snapshot);
-      const destination = new Uint8Array(this.tableBytes.material, materialOffset, MATERIAL.stride);
-      destination.fill(0);
-      if (row !== undefined) destination.set(row.subarray(0, MATERIAL.stride));
-      writes.material.push(materialIndex);
+      let row = materialRows.get(snapshot);
+      if (row === undefined) {
+        const shaderId = snapshot.materialShaderId;
+        const schema = snapshot.materialParamSchema;
+        row =
+          shaderId !== undefined &&
+          shaderId !== 'forgeax::default-standard-pbr' &&
+          shaderId !== 'forgeax::pbr-skin' &&
+          shaderId !== 'forgeax::default-standard-pbr-skin' &&
+          schema !== undefined
+            ? packMaterialProgramRow(schema, snapshot, MATERIAL.stride)
+            : packStandardPbrMaterialRow(STANDARD_PBR_RECEIPT, snapshot);
+        row ??= new Uint8Array(MATERIAL.stride);
+        materialRows.set(snapshot, row);
+      }
+      if (this.writeRow('material', materialIndex, row) || reset)
+        writes.material.push(materialIndex);
     }
   }
 
@@ -972,7 +963,7 @@ export class GpuScene {
     let rangeCount = 0;
     let bytes = 0;
     for (const name of TABLE_NAMES) {
-      const ranges = coalesceSlots(rows[name]);
+      const ranges = this.dirtyRanges.coalesce(rows[name]);
       rangeCount += ranges.length;
       for (const range of ranges) {
         const layout = TABLE_LAYOUTS[name];

package/src/hdrp-buffers.ts

@@ -559,6 +559,7 @@ export function createHdrpUnifiedBindGroup(
   hdrpBuffers: HdrpBuffers,
   meshStorageBuffer: Buffer,
   ssaoOptions: SsaoBindOptions = { enabled: false },
+  meshBindingBytes = MESH_PER_ENTITY_STRIDE,
 ): BindGroup | null {
   const fallback = getOrCreateSsaoFallbackTexture(runtime);
   if (fallback === null) return null;
@@ -579,7 +580,7 @@ export function createHdrpUnifiedBindGroup(
           value: {
             buffer: meshStorageBuffer,
             offset: 0,
-            size: MESH_PER_ENTITY_STRIDE,
+            size: meshBindingBytes,
           },
         },
       },
@@ -602,17 +603,17 @@ export function createHdrpSkinUnifiedBindGroup(
   paletteBuffer: Buffer,
   paletteBindingWindowBytes: number,
   ssaoOptions: SsaoBindOptions = { enabled: false },
+  meshBindingBytes = MESH_PER_ENTITY_STRIDE,
 ): BindGroup | null {
   const fallback = getOrCreateSsaoFallbackTexture(runtime);
   if (fallback === null) return null;
-  const meshSize = MESH_PER_ENTITY_STRIDE;
   const result = runtime.device.createBindGroup({
     label: 'hdrp-skin-unified-bg-group2',
     layout,
     entries: [
       ...createPbrSkinMeshBindGroupEntries(
         meshStorageBuffer,
-        meshSize,
+        meshBindingBytes,
         paletteBuffer,
         paletteBindingWindowBytes,
       ),

package/src/ibl/skylight-bind-group.ts

@@ -242,6 +242,16 @@ export interface TransmissionBindGroupResources {
   readonly backdropView?: TextureView | null;
 }
 
+/** Renderer-owned sampled resources consumed by the single-layer medium. */
+export interface SurfaceMediumBindGroupResources {
+  readonly rawDepthSampler: Sampler;
+  readonly rawDepthView: TextureView;
+  readonly nearestLayerSampler: Sampler;
+  readonly nearestLayerView: TextureView;
+  readonly nearestDepthSampler: Sampler;
+  readonly nearestDepthView: TextureView;
+}
+
 /** Engine-owned texture injection resources derived from material parameters. */
 export interface TextureInjectionResource {
   readonly slot: number;
@@ -258,6 +268,7 @@ export function assembleMaterialWithSkylightEntries(
   skylight: SkylightBindGroupResources,
   transmission?: TransmissionBindGroupResources | null | undefined,
   textureInjections: readonly TextureInjectionResource[] = [],
+  surfaceMedium?: SurfaceMediumBindGroupResources | undefined,
 ): BindGroupEntry[] {
   // IBL injection start = end of the user-region. The user-region IS
   // `materialEntries` (UBO binding 0 + N sampler/texture pairs), so its length
@@ -314,6 +325,35 @@ export function assembleMaterialWithSkylightEntries(
         resource: { kind: 'textureView', value: transmissionView },
       },
     );
+  if (surfaceMedium !== undefined) {
+    const surfaceStart = result.length;
+    result.push(
+      {
+        binding: surfaceStart,
+        resource: { kind: 'sampler', value: surfaceMedium.rawDepthSampler },
+      },
+      {
+        binding: surfaceStart + 1,
+        resource: { kind: 'textureView', value: surfaceMedium.rawDepthView },
+      },
+      {
+        binding: surfaceStart + 2,
+        resource: { kind: 'sampler', value: surfaceMedium.nearestLayerSampler },
+      },
+      {
+        binding: surfaceStart + 3,
+        resource: { kind: 'textureView', value: surfaceMedium.nearestLayerView },
+      },
+      {
+        binding: surfaceStart + 4,
+        resource: { kind: 'sampler', value: surfaceMedium.nearestDepthSampler },
+      },
+      {
+        binding: surfaceStart + 5,
+        resource: { kind: 'textureView', value: surfaceMedium.nearestDepthView },
+      },
+    );
+  }
   // Standard physical maps occupy fixed bindings 26..45.  The `slot` value
   // is the canonical index from STANDARD_PHYSICAL_TEXTURE_FIELDS; preserve
   // gaps for omitted authored maps instead of compacting this tail.
@@ -333,13 +373,15 @@ export function assembleMaterialWithSkylightEntries(
       },
     );
   }
-  result.push({
-    binding: 47,
-    resource: {
-      kind: 'textureView',
-      value: skylight.skylightPrefilterView ?? skylight.prefilterView,
-    },
-  });
+  if (surfaceMedium === undefined) {
+    result.push({
+      binding: 47,
+      resource: {
+        kind: 'textureView',
+        value: skylight.skylightPrefilterView ?? skylight.prefilterView,
+      },
+    });
+  }
   return result;
 }