@forgeax/engine-render 0.1.32 → 0.1.34

package/src/ssao-buffers.ts

@@ -114,6 +114,48 @@ interface SsaoFallbackResources {
 
 const fallbackCache = new WeakMap<RenderSystemRuntime, SsaoFallbackResources>();
 
+function destroyBuffer(
+  runtime: RenderSystemRuntime,
+  device: RenderSystemRuntime['device'],
+  buffer: Buffer,
+): void {
+  const destroyed = device.destroyBuffer(buffer);
+  if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+}
+
+function destroyTexture(
+  runtime: RenderSystemRuntime,
+  device: RenderSystemRuntime['device'],
+  texture: Texture,
+): void {
+  const destroyed = device.destroyTexture(texture);
+  if (!destroyed.ok) runtime.errorRegistry.fire(destroyed.error);
+}
+
+function retireSsaoResources(device: RenderSystemRuntime['device'], release: () => void): void {
+  const queue = device.queue as {
+    readonly onSubmittedWorkDone?: () => Promise<undefined>;
+  };
+  if (typeof queue.onSubmittedWorkDone === 'function') {
+    try {
+      void queue.onSubmittedWorkDone().then(release, release);
+      return;
+    } catch {
+      // A lost or minimal test device may reject the fence synchronously.
+    }
+  }
+  // There is no submitted work to fence on minimal RHI fixtures.  Releasing
+  // synchronously keeps cache reset deterministic for those callers.
+  release();
+}
+
+function destroySsaoFallbackResources(
+  runtime: RenderSystemRuntime,
+  resources: SsaoFallbackResources,
+): void {
+  destroyTexture(runtime, resources.device, resources.texture);
+}
+
 /**
  * Lazily allocate the 1x1 r8unorm white fallback texture + a sampler for
  * SSAO disabled / resource-missing path. Cached per RenderSystemRuntime so
@@ -128,7 +170,10 @@ export function getOrCreateSsaoFallbackTexture(
 ): SsaoFallbackResources | null {
   const cached = fallbackCache.get(runtime);
   if (cached !== undefined && cached.device === runtime.device) return cached;
-  if (cached !== undefined) fallbackCache.delete(runtime);
+  if (cached !== undefined) {
+    fallbackCache.delete(runtime);
+    retireSsaoResources(cached.device, () => destroySsaoFallbackResources(runtime, cached));
+  }
 
   const device = runtime.device;
   const texRes = device.createTexture({
@@ -160,6 +205,7 @@ export function getOrCreateSsaoFallbackTexture(
   );
   if (!writeRes.ok) {
     runtime.errorRegistry.fire(writeRes.error);
+    destroyTexture(runtime, device, texRes.value);
     return null;
   }
 
@@ -175,6 +221,7 @@ export function getOrCreateSsaoFallbackTexture(
   });
   if (!viewRes.ok) {
     runtime.errorRegistry.fire(viewRes.error);
+    destroyTexture(runtime, device, texRes.value);
     return null;
   }
 
@@ -189,6 +236,7 @@ export function getOrCreateSsaoFallbackTexture(
   });
   if (!samplerRes.ok) {
     runtime.errorRegistry.fire(samplerRes.error);
+    destroyTexture(runtime, device, texRes.value);
     return null;
   }
 
@@ -222,6 +270,44 @@ export interface SsaoBuffers {
 
 const cache = new WeakMap<RenderSystemRuntime, SsaoBuffers>();
 
+function destroySsaoBufferResources(runtime: RenderSystemRuntime, buffers: SsaoBuffers): void {
+  for (const buffer of [buffers.kernelBuffer, buffers.uniformBuffer]) {
+    destroyBuffer(runtime, buffers.device, buffer);
+  }
+  destroyTexture(runtime, buffers.device, buffers.noiseTexture);
+}
+
+function destroyCreatedSsaoResources(
+  runtime: RenderSystemRuntime,
+  device: RenderSystemRuntime['device'],
+  buffers: readonly Buffer[],
+  textures: readonly Texture[],
+): void {
+  for (const buffer of buffers) destroyBuffer(runtime, device, buffer);
+  for (const texture of textures) destroyTexture(runtime, device, texture);
+}
+
+/**
+ * Release every persistent SSAO resource owned by one renderer runtime.
+ *
+ * The fallback texture and the enabled-path buffers are module caches keyed by
+ * the runtime object, so Renderer.dispose()/recover() must explicitly retire
+ * them.  Cache eviction alone loses the only owner and leaves the backing RHI
+ * handles live until the device itself is collected.
+ */
+export function resetSsaoResources(runtime: RenderSystemRuntime): void {
+  const buffers = cache.get(runtime);
+  if (buffers !== undefined) {
+    cache.delete(runtime);
+    retireSsaoResources(buffers.device, () => destroySsaoBufferResources(runtime, buffers));
+  }
+  const fallback = fallbackCache.get(runtime);
+  if (fallback !== undefined) {
+    fallbackCache.delete(runtime);
+    retireSsaoResources(fallback.device, () => destroySsaoFallbackResources(runtime, fallback));
+  }
+}
+
 /**
  * Lazily allocate the 3 SSAO GPU resources for `runtime`. Returns the
  * same `SsaoBuffers` object on subsequent calls (per-RenderSystem
@@ -235,7 +321,10 @@ const cache = new WeakMap<RenderSystemRuntime, SsaoBuffers>();
 export function getOrCreateSsaoBuffers(runtime: RenderSystemRuntime): SsaoBuffers | null {
   const cached = cache.get(runtime);
   if (cached !== undefined && cached.device === runtime.device) return cached;
-  if (cached !== undefined) cache.delete(runtime);
+  if (cached !== undefined) {
+    cache.delete(runtime);
+    retireSsaoResources(cached.device, () => destroySsaoBufferResources(runtime, cached));
+  }
 
   const device = runtime.device;
 
@@ -266,6 +355,7 @@ export function getOrCreateSsaoBuffers(runtime: RenderSystemRuntime): SsaoBuffer
   const kernelWriteRes = device.queue.writeBuffer(kernelBufferRes.value, 0, kernelData);
   if (!kernelWriteRes.ok) {
     runtime.errorRegistry.fire(kernelWriteRes.error);
+    destroyBuffer(runtime, device, kernelBufferRes.value);
     return null;
   }
 
@@ -292,6 +382,7 @@ export function getOrCreateSsaoBuffers(runtime: RenderSystemRuntime): SsaoBuffer
   });
   if (!noiseTexRes.ok) {
     runtime.errorRegistry.fire(noiseTexRes.error);
+    destroyBuffer(runtime, device, kernelBufferRes.value);
     return null;
   }
 
@@ -312,6 +403,7 @@ export function getOrCreateSsaoBuffers(runtime: RenderSystemRuntime): SsaoBuffer
   );
   if (!noiseCopyRes.ok) {
     runtime.errorRegistry.fire(noiseCopyRes.error);
+    destroyCreatedSsaoResources(runtime, device, [kernelBufferRes.value], [noiseTexRes.value]);
     return null;
   }
 
@@ -324,6 +416,7 @@ export function getOrCreateSsaoBuffers(runtime: RenderSystemRuntime): SsaoBuffer
   });
   if (!uniformBufRes.ok) {
     runtime.errorRegistry.fire(uniformBufRes.error);
+    destroyCreatedSsaoResources(runtime, device, [kernelBufferRes.value], [noiseTexRes.value]);
     return null;
   }
 

package/src/surface/__tests__/dynamic-input.unit.test.ts

@@ -0,0 +1,374 @@
+import { describe, expect, it } from 'vitest';
+import { ReadonlyDynamicInputPage } from '../dynamic-input.js';
+
+const schema = {
+  name: 'waterEvents',
+  fields: [
+    { name: 'position', type: 'vec3<f32>' as const },
+    { name: 'time', type: 'f32' as const },
+    { name: 'eventId', type: 'u32' as const },
+  ],
+  maxRecords: 4,
+  maxDomains: 2,
+  maxPageBytes: 128,
+  maxBindings: 1,
+  maxEventsPerSample: 8,
+};
+
+const member = (instanceOrdinal = 0) => ({
+  worldIdentity: 'world-a',
+  entityKey: 1,
+  drawItemIndex: 0,
+  instanceOrdinal,
+});
+
+describe('Render read-only dynamic input page', () => {
+  it('uploads dirty records and consumes an explicit instance range', () => {
+    const created = ReadonlyDynamicInputPage.create({
+      sourceId: 'project-water',
+      pageId: 7,
+      schema,
+    });
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const page = created.value;
+    expect(page.writeRecord(0, { position: [1, 2, 3], time: 4, eventId: 11 })).toMatchObject({
+      ok: true,
+    });
+    const range = page.reserveRange({
+      domain: 'river-a',
+      recordStart: 0,
+      recordCount: 1,
+      instanceIndex: 0xffffffff,
+      member: member(),
+    });
+    expect(range.ok).toBe(true);
+    if (!range.ok) return;
+    expect(page.consume(range.value, 14)).toMatchObject({
+      ok: false,
+      error: { code: 'not-uploaded' },
+    });
+
+    const upload = page.upload();
+    expect(upload).toMatchObject({
+      ok: true,
+      value: {
+        contentRevision: 2,
+        bufferGeneration: 1,
+        bytes: 32,
+        ranges: [{ byteStart: 0, byteEnd: 32 }],
+      },
+    });
+    expect(page.consume(range.value, 14)).toMatchObject({
+      ok: true,
+      value: {
+        pageId: 7,
+        domain: 'river-a',
+        instanceIndex: 0xffffffff,
+        frameNumber: 14,
+        uploadedRevision: 2,
+      },
+    });
+  });
+
+  it('keeps dirty bytes pending until the owning queue commits the receipt', () => {
+    const created = ReadonlyDynamicInputPage.create({ sourceId: 'water', pageId: 8, schema });
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const page = created.value;
+    expect(page.writeRecord(0, { position: [1, 2, 3], time: 4, eventId: 11 })).toMatchObject({
+      ok: true,
+    });
+    const range = page.reserveRange({
+      domain: 'water-surface',
+      recordStart: 0,
+      recordCount: 1,
+      instanceIndex: 3,
+      member: member(),
+    });
+    expect(range.ok).toBe(true);
+    if (!range.ok) return;
+
+    const first = page.beginUpload();
+    expect(first).toMatchObject({ ok: true, value: { bytes: 32, contentRevision: 2 } });
+    expect(page.uploadedRevision).toBe(0);
+    expect(page.lastUploadedBytes).toBe(0);
+    expect(page.consume(range.value, 21)).toMatchObject({
+      ok: false,
+      error: { code: 'not-uploaded' },
+    });
+    if (!first.ok) return;
+
+    // A producer update while the queue write is in flight invalidates only
+    // the receipt. The original dirty bytes and the new revision remain
+    // available for the retry.
+    expect(page.writeRecord(0, { position: [4, 5, 6], time: 7, eventId: 12 })).toMatchObject({
+      ok: true,
+    });
+    expect(page.commitUpload(first.value)).toMatchObject({
+      ok: false,
+      error: { code: 'stale-generation' },
+    });
+    expect(page.uploadedRevision).toBe(0);
+    const retry = page.beginUpload();
+    expect(retry).toMatchObject({ ok: true, value: { bytes: 32, contentRevision: 3 } });
+    if (!retry.ok) return;
+    expect(page.commitUpload(retry.value)).toMatchObject({ ok: true, value: true });
+    expect(page.consume(range.value, 22)).toMatchObject({
+      ok: true,
+      value: { frameNumber: 22, uploadedRevision: 3 },
+    });
+  });
+
+  it('bounds domains, preserves page identity across device rebuild, and rejects stale ranges', () => {
+    const created = ReadonlyDynamicInputPage.create({ sourceId: 'water', pageId: 1, schema });
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const page = created.value;
+    expect(
+      page.reserveRange({
+        domain: 'a',
+        recordStart: 0,
+        recordCount: 1,
+        instanceIndex: 0,
+        member: member(),
+      }).ok,
+    ).toBe(true);
+    expect(
+      page.reserveRange({
+        domain: 'b',
+        recordStart: 1,
+        recordCount: 1,
+        instanceIndex: 1,
+        member: member(1),
+      }).ok,
+    ).toBe(true);
+    expect(
+      page.reserveRange({
+        domain: 'c',
+        recordStart: 2,
+        recordCount: 1,
+        instanceIndex: 2,
+        member: member(2),
+      }),
+    ).toMatchObject({
+      ok: false,
+      error: { code: 'domain-overflow' },
+    });
+
+    const before = page.reserveRange({
+      domain: 'a',
+      recordStart: 0,
+      recordCount: 1,
+      instanceIndex: 9,
+      member: member(),
+    });
+    expect(before.ok).toBe(true);
+    if (!before.ok) return;
+    expect(page.reconfigureDevice(2)).toMatchObject({ ok: true, value: 2 });
+    expect(page.consume(before.value, 15)).toMatchObject({
+      ok: false,
+      error: { code: 'stale-generation' },
+    });
+    expect(page.upload()).toMatchObject({ ok: true, value: { bytes: 128, deviceGeneration: 2 } });
+  });
+
+  it('accepts the renderer initial device generation', () => {
+    const page = ReadonlyDynamicInputPage.create({ sourceId: 'water', pageId: 9, schema }).unwrap();
+    expect(page.reconfigureDevice(0)).toMatchObject({ ok: true, value: 2 });
+    expect(page.deviceGeneration).toBe(0);
+  });
+
+  it('rejects a stale device generation without changing page state', () => {
+    const page = ReadonlyDynamicInputPage.create({
+      sourceId: 'water',
+      pageId: 10,
+      schema,
+    }).unwrap();
+    page.writeRecord(0, { position: [1, 2, 3], time: 4, eventId: 11 }).unwrap();
+    page.reconfigureDevice(2).unwrap();
+    const before = page.beginUpload().unwrap();
+
+    expect(page.reconfigureDevice(1)).toMatchObject({
+      ok: false,
+      error: { code: 'stale-generation' },
+    });
+    expect(page.deviceGeneration).toBe(2);
+    expect(page.bufferGeneration).toBe(before.bufferGeneration);
+    expect(page.contentRevision).toBe(before.contentRevision);
+    expect(page.uploadedRevision).toBe(0);
+    expect(page.beginUpload()).toEqual({ ok: true, value: before });
+  });
+
+  it('keeps invalid records structured and release terminal', () => {
+    const created = ReadonlyDynamicInputPage.create({ sourceId: 'water', pageId: 2, schema });
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const page = created.value;
+    expect(page.writeRecord(0, { position: [0, 0], time: 0, eventId: 1 })).toMatchObject({
+      ok: false,
+      error: { code: 'invalid-record' },
+    });
+    expect(page.release()).toMatchObject({ ok: true });
+    expect(page.upload()).toMatchObject({ ok: false, error: { code: 'released' } });
+  });
+
+  it('rejects released-page receipts and ranges after same-id page replacement', () => {
+    const createdA = ReadonlyDynamicInputPage.create({
+      sourceId: 'same-source',
+      pageId: 12,
+      schema,
+    });
+    expect(createdA.ok).toBe(true);
+    if (!createdA.ok) return;
+    const pageA = createdA.value;
+    expect(pageA.writeRecord(0, { position: [1, 2, 3], time: 4, eventId: 101 })).toMatchObject({
+      ok: true,
+    });
+    const rangeA = pageA.reserveRange({
+      domain: 'water',
+      recordStart: 0,
+      recordCount: 1,
+      instanceIndex: 0,
+      member: member(),
+    });
+    expect(rangeA.ok).toBe(true);
+    if (!rangeA.ok) return;
+    const receiptA = pageA.beginUpload();
+    expect(receiptA.ok).toBe(true);
+    if (!receiptA.ok) return;
+    expect(pageA.release()).toMatchObject({ ok: true });
+    expect(pageA.writeRecord(0, { position: [9, 8, 7], time: 6, eventId: 102 })).toMatchObject({
+      ok: false,
+      error: { code: 'released' },
+    });
+    expect(pageA.commitUpload(receiptA.value)).toMatchObject({
+      ok: false,
+      error: { code: 'released' },
+    });
+    expect(pageA.consume(rangeA.value, 40)).toMatchObject({
+      ok: false,
+      error: { code: 'released' },
+    });
+
+    const createdB = ReadonlyDynamicInputPage.create({
+      sourceId: 'same-source',
+      pageId: 12,
+      schema,
+    });
+    expect(createdB.ok).toBe(true);
+    if (!createdB.ok) return;
+    const pageB = createdB.value;
+    expect(pageB.writeRecord(0, { position: [5, 6, 7], time: 8, eventId: 201 })).toMatchObject({
+      ok: true,
+    });
+    const rangeB = pageB.reserveRange({
+      domain: 'water',
+      recordStart: 0,
+      recordCount: 1,
+      instanceIndex: 0,
+      member: member(),
+    });
+    expect(rangeB.ok).toBe(true);
+    if (!rangeB.ok) return;
+    const beforeBytes = pageB.bytes.slice();
+    const beforeContentRevision = pageB.contentRevision;
+    const beforeUploadedRevision = pageB.uploadedRevision;
+    const beforeUpload = pageB.beginUpload();
+    expect(beforeUpload.ok).toBe(true);
+    if (!beforeUpload.ok) return;
+
+    expect(pageB.commitUpload(receiptA.value)).toMatchObject({
+      ok: false,
+      error: { code: 'stale-generation' },
+    });
+    expect(pageB.consume(rangeA.value, 41)).toMatchObject({
+      ok: false,
+      error: { code: 'stale-generation' },
+    });
+    expect(pageB.bytes).toEqual(beforeBytes);
+    expect(pageB.contentRevision).toBe(beforeContentRevision);
+    expect(pageB.uploadedRevision).toBe(beforeUploadedRevision);
+    expect(pageB.beginUpload()).toEqual(beforeUpload);
+    expect(pageB.consume(rangeB.value, 42)).toMatchObject({
+      ok: false,
+      error: { code: 'not-uploaded' },
+    });
+  });
+
+  it('does not publish partial bytes when a later field is invalid', () => {
+    const created = ReadonlyDynamicInputPage.create({ sourceId: 'water', pageId: 3, schema });
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const page = created.value;
+    expect(page.writeRecord(0, { position: [1, 2, 3], time: 4, eventId: 5 })).toMatchObject({
+      ok: true,
+    });
+    const beforeBytes = page.bytes.slice();
+    const beforeRevision = page.contentRevision;
+    expect(page.writeRecord(0, { position: [9, 8, 7], time: 6, eventId: 1.5 })).toMatchObject({
+      ok: false,
+      error: { code: 'invalid-record', detail: { field: 'eventId' } },
+    });
+    expect(page.bytes).toEqual(beforeBytes);
+    expect(page.contentRevision).toBe(beforeRevision);
+    expect(page.upload()).toMatchObject({ ok: true, value: { bytes: 32 } });
+  });
+
+  it('rejects an instance address outside the exact u32 range', () => {
+    const created = ReadonlyDynamicInputPage.create({ sourceId: 'water', pageId: 4, schema });
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    expect(
+      created.value.reserveRange({
+        domain: 'overflow',
+        recordStart: 0,
+        recordCount: 1,
+        instanceIndex: 0x1_0000_0000,
+        member: member(),
+      }),
+    ).toMatchObject({
+      ok: false,
+      error: { code: 'range-overflow', detail: { field: 'instanceIndex' } },
+    });
+  });
+
+  it('keeps two explicit instance addresses independent', () => {
+    const created = ReadonlyDynamicInputPage.create({ sourceId: 'water', pageId: 5, schema });
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const page = created.value;
+    expect(page.writeRecord(0, { position: [1, 0, 0], time: 1, eventId: 10 })).toMatchObject({
+      ok: true,
+    });
+    expect(page.writeRecord(1, { position: [2, 0, 0], time: 2, eventId: 20 })).toMatchObject({
+      ok: true,
+    });
+    const first = page.reserveRange({
+      domain: 'first-instance',
+      recordStart: 0,
+      recordCount: 1,
+      instanceIndex: 0,
+      member: member(),
+    });
+    const second = page.reserveRange({
+      domain: 'second-instance',
+      recordStart: 1,
+      recordCount: 1,
+      instanceIndex: 1,
+      member: member(1),
+    });
+    expect(first).toMatchObject({ ok: true, value: { instanceIndex: 0, recordStart: 0 } });
+    expect(second).toMatchObject({ ok: true, value: { instanceIndex: 1, recordStart: 1 } });
+    if (!first.ok || !second.ok) return;
+    expect(page.upload()).toMatchObject({ ok: true, value: { bytes: 64 } });
+    expect(page.consume(first.value, 20)).toMatchObject({
+      ok: true,
+      value: { instanceIndex: 0, recordStart: 0 },
+    });
+    expect(page.consume(second.value, 20)).toMatchObject({
+      ok: true,
+      value: { instanceIndex: 1, recordStart: 1 },
+    });
+  });
+});

package/src/surface/__tests__/gpu-driven.unit.test.ts

@@ -0,0 +1,87 @@
+import type { MaterialProgramAbi } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { admitSingleLayerMediumSubmission } from '../gpu-driven.js';
+
+const abi: MaterialProgramAbi = {
+  directEntry: 'vs_main',
+  sceneIndexEntry: 'vs_scene_index',
+  materialRow: { byteLength: 416, fields: [] },
+  resourceSlots: [],
+  uvSets: [],
+  vertexInputs: [{ semantic: 'position', location: 0, format: 'float32x3' }],
+  alphaMask: { cutoff: '', source: '' },
+  reflection: {
+    layoutIdentity: 'material-program/test',
+    resourceSlots: [],
+    vertexInputs: [{ semantic: 'position', location: 0, format: 'float32x3' }],
+  },
+  receiptIdentity: 'material-program/test',
+  generation: 3,
+  surface: {
+    model: 'single-layer-medium',
+    module: 'game::water_surface',
+    inputAbi: 'SingleLayerMediumSurfaceInput',
+    outputAbi: 'SingleLayerMediumSurfaceData',
+    passes: ['nearest-layer', 'color'],
+  },
+};
+
+const ready = {
+  abi,
+  caps: { compute: true, storageBuffer: true, indirectDrawing: true },
+  sceneIndexReady: true,
+  resourcesReady: true,
+  dynamicInputReady: true,
+  deviceGeneration: 3,
+  preparedDeviceGeneration: 3,
+};
+
+describe('single-layer Surface GPU-driven admission', () => {
+  it('admits nearest-layer and color to the same GPU-driven lane', () => {
+    const result = admitSingleLayerMediumSubmission(ready);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.lane).toBe('gpu-driven');
+    expect(result.value.passes).toMatchObject([
+      {
+        pass: 'nearest-layer',
+        lane: 'gpu-driven',
+      },
+      {
+        pass: 'color',
+        lane: 'gpu-driven',
+      },
+    ]);
+  });
+
+  it('uses the same two pass members on a capability fallback and names the reason', () => {
+    const result = admitSingleLayerMediumSubmission({
+      ...ready,
+      caps: { compute: false, storageBuffer: true, indirectDrawing: true },
+    });
+    expect(result).toMatchObject({
+      ok: true,
+      value: {
+        lane: 'direct',
+        passes: [
+          { pass: 'nearest-layer', lane: 'direct', reason: 'compute' },
+          { pass: 'color', lane: 'direct', reason: 'compute' },
+        ],
+      },
+    });
+  });
+
+  it('blocks missing publication and stale prepared generations', () => {
+    const { surface: _surface, ...abiWithoutSurface } = abi;
+    expect(admitSingleLayerMediumSubmission({ ...ready, abi: abiWithoutSurface })).toMatchObject({
+      ok: false,
+      error: { code: 'surface-abi-missing', owner: 'surface-producer' },
+    });
+    expect(
+      admitSingleLayerMediumSubmission({ ...ready, preparedDeviceGeneration: 2 }),
+    ).toMatchObject({
+      ok: false,
+      error: { code: 'surface-generation-stale', owner: 'render-generation' },
+    });
+  });
+});