@forgeax/engine-render 0.1.19 → 0.1.21

package/src/__tests__/render-target-inspection.unit.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import type { ReflectionProbeSelectionInspection } from '../inspection-types';
+import { ReflectionProbeProjection } from '../reflection/projection';
+import { createRenderTargetOwner } from '../targets/owner';
+
+describe('bounded render-target inspection', () => {
+  it('retains only POD owner facts and no GPU handles or unbounded history', () => {
+    const owner = createRenderTargetOwner({ rendererId: Symbol('renderer'), initialGeneration: 4 });
+    const target = owner.create({
+      shape: '2d',
+      width: 8,
+      height: 8,
+      format: 'rgba8unorm',
+      mipLevels: 1,
+      sampleCount: 1,
+      sampled: true,
+      readback: true,
+    });
+    expect(target.ok).toBe(true);
+    if (!target.ok) return;
+    const inspection = owner.inspect(target.value);
+    expect(inspection.ok).toBe(true);
+    if (!inspection.ok) return;
+    expect(Object.keys(inspection.value).sort()).toEqual([
+      'descriptor',
+      'generation',
+      'state',
+      'token',
+    ]);
+    expect(inspection.value).not.toHaveProperty('history');
+    expect(inspection.value).not.toHaveProperty('device');
+  });
+
+  it('keeps selection inspection bounded to current primitives', () => {
+    const projection = new ReflectionProbeProjection();
+    const snapshot = projection.update([], []);
+    expect(snapshot.scannedPrimitives).toBe(0);
+    expect(snapshot.selected.size).toBe(0);
+    expect(projection.selection(1, 2)).toEqual({ kind: 'skylight' });
+  });
+
+  it('uses a closed identity for selected probes and Skylight fallback', () => {
+    const selected: ReflectionProbeSelectionInspection = {
+      kind: 'probe',
+      worldId: 2,
+      entityKey: 7,
+    };
+    const fallback: ReflectionProbeSelectionInspection = { kind: 'skylight' };
+    expect(selected).toEqual({ kind: 'probe', worldId: 2, entityKey: 7 });
+    expect(fallback).toEqual({ kind: 'skylight' });
+  });
+});

package/src/__tests__/render-target-material-source.test-d.ts

@@ -0,0 +1,30 @@
+import type { SchemaOf, ShapeOf } from '@forgeax/engine-ecs';
+import type { Handle } from '@forgeax/engine-types';
+import { expectTypeOf, it } from 'vitest';
+import type { Camera } from '../components/camera';
+import type { FrameObservationRequest } from '../render-contract';
+import type {
+  RenderTargetReadbackData,
+  RenderTargetReadbackTicket,
+  RenderTargetTextureSource,
+} from '../targets/contracts';
+
+it('keeps Camera target as a simulation-transient shared RenderTarget handle', () => {
+  expectTypeOf<ShapeOf<SchemaOf<typeof Camera>>['target']>().toEqualTypeOf<
+    Handle<'RenderTarget', 'shared'>
+  >();
+});
+
+it('keeps target material source opaque and receipt readback data explicit', () => {
+  type NoProperty<T, K extends PropertyKey> = Extract<keyof T, K> extends never ? true : false;
+  expectTypeOf<NoProperty<RenderTargetTextureSource, 'texture'>>().toEqualTypeOf<true>();
+  expectTypeOf<NoProperty<RenderTargetTextureSource, 'view'>>().toEqualTypeOf<true>();
+  expectTypeOf<NoProperty<RenderTargetTextureSource, 'colorSpace'>>().toEqualTypeOf<true>();
+  expectTypeOf<FrameObservationRequest['include'][number]>().toMatchTypeOf<
+    'target-readbacks' | 'timings' | 'draws' | 'bindings'
+  >();
+  expectTypeOf<FrameObservationRequest['targetReadbacks']>().toEqualTypeOf<
+    readonly RenderTargetReadbackTicket[] | undefined
+  >();
+  expectTypeOf<RenderTargetReadbackData['bytes']>().toEqualTypeOf<Uint8Array>();
+});

package/src/__tests__/render-target-material-source.unit.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import { materialRenderTargetSourceForField } from '../record/main-pass-material';
+import type { MaterialSnapshot } from '../render-system-extract';
+import type { RenderTargetDescriptor } from '../targets/contracts';
+import {
+  createRenderTargetMaterialSource,
+  validateRenderTargetMaterialSource,
+} from '../targets/material-source';
+import { createRenderTargetOwner } from '../targets/owner';
+
+const descriptor: RenderTargetDescriptor = {
+  shape: '2d',
+  width: 32,
+  height: 16,
+  format: 'rgba8unorm-srgb',
+  mipLevels: 'full',
+  sampleCount: 1,
+  sampled: true,
+  readback: false,
+};
+
+function target() {
+  const owner = createRenderTargetOwner({ rendererId: Symbol('renderer'), initialGeneration: 4 });
+  const created = owner.create(descriptor);
+  if (!created.ok) throw created.error;
+  return created.value;
+}
+
+describe('RenderTarget material source', () => {
+  it('binds one target generation and one exact view subresource', () => {
+    const binding = createRenderTargetMaterialSource(target(), descriptor, {
+      aspect: 'color',
+      dimension: '2d',
+      mipLevel: 2,
+      generation: 4,
+    });
+    expect(binding.ok).toBe(true);
+    if (!binding.ok) return;
+    expect(binding.value.source).toBeDefined();
+    expect(binding.value.generation).toBe(4);
+    expect(binding.value.view).toMatchObject({ dimension: '2d', mipLevel: 2 });
+    expect(
+      validateRenderTargetMaterialSource(binding.value, {
+        target: binding.value.target,
+        shape: '2d',
+        format: 'rgba8unorm-srgb',
+        dimension: '2d',
+        mipLevel: 2,
+        generation: 4,
+      }).ok,
+    ).toBe(true);
+  });
+
+  it('rejects a wrong shape, format, view, or stale generation before binding', () => {
+    const binding = createRenderTargetMaterialSource(target(), descriptor, {
+      aspect: 'color',
+      dimension: '2d',
+      mipLevel: 0,
+      generation: 4,
+    });
+    expect(binding.ok).toBe(true);
+    if (!binding.ok) return;
+    const wrong = validateRenderTargetMaterialSource(binding.value, {
+      target: binding.value.target,
+      shape: 'cube',
+      format: 'rgba16float',
+      dimension: 'cube',
+      mipLevel: 1,
+      generation: 5,
+    });
+    expect(wrong.ok).toBe(false);
+    if (!wrong.ok)
+      expect(['render-target-state-invalid', 'render-target-descriptor-invalid']).toContain(
+        wrong.error.code,
+      );
+  });
+
+  it('uses the renderer-owned physical view resolver before material bind assembly', () => {
+    const binding = createRenderTargetMaterialSource(target(), descriptor, {
+      aspect: 'color',
+      dimension: '2d',
+      mipLevel: 0,
+      generation: 4,
+    });
+    expect(binding.ok).toBe(true);
+    if (!binding.ok) return;
+    const material = {
+      textureSources: new Map([['baseColorTexture', binding.value.source]]),
+    } as unknown as MaterialSnapshot;
+    const physicalView = {} as NonNullable<typeof binding.value.textureView>;
+    const resolved = materialRenderTargetSourceForField(material, 'baseColorTexture', () => ({
+      ...binding.value,
+      textureView: physicalView,
+    }));
+    expect(resolved?.textureView).toBe(physicalView);
+  });
+});

package/src/__tests__/render-target-owner-placement.unit.test.ts

@@ -0,0 +1,203 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { createRenderTargetHost } from '../assembly/render-target-host';
+
+const testDirectory = dirname(fileURLToPath(import.meta.url));
+const factorySourcePath = resolve(testDirectory, '../assembly/factory.ts');
+const hostSourcePath = resolve(testDirectory, '../assembly/render-target-host.ts');
+const renderGraphSourcePath = resolve(testDirectory, '../../../render-graph/src');
+
+describe('RenderTarget owner placement', () => {
+  it('places the lifecycle seam under the existing Renderer assembly owner', () => {
+    expect(existsSync(hostSourcePath)).toBe(true);
+    const factorySource = readFileSync(factorySourcePath, 'utf8');
+    const hostSource = readFileSync(hostSourcePath, 'utf8');
+
+    expect(factorySource).toContain('createRenderTargetHost()');
+    expect(factorySource).toContain('const renderTargetHost =');
+    expect(hostSource).toContain("owner: 'renderer'");
+    expect(hostSource).not.toContain('@forgeax/engine-render-graph');
+    expect(hostSource).toContain('@forgeax/engine-rhi');
+    expect(hostSource).not.toContain('@forgeax/engine-assets-runtime');
+    expect(existsSync(renderGraphSourcePath)).toBe(true);
+  });
+
+  it('keeps one frame submission and one recovery entrypoint', () => {
+    const factorySource = readFileSync(factorySourcePath, 'utf8');
+    const drawBoundary = factorySource.slice(
+      factorySource.indexOf('drawFrame(request'),
+      factorySource.indexOf('observe(', factorySource.indexOf('drawFrame(request')),
+    );
+
+    expect(drawBoundary.match(/^\s+const submitted = renderSystem\.draw\(/m)).not.toBeNull();
+    expect(drawBoundary).toContain('renderTargetHost.beginFrame()');
+    expect(drawBoundary).toContain('renderTargetHost.onFrameSubmitted(completed)');
+    expect(factorySource.match(/recover\(\): Promise/g)).toHaveLength(1);
+    expect(factorySource.match(/renderTargetHost\.recover\(\)/g)).toHaveLength(1);
+  });
+
+  it('keeps the off path free of target allocation and graph submission', () => {
+    const factorySource = readFileSync(factorySourcePath, 'utf8');
+    const hostSource = readFileSync(hostSourcePath, 'utf8');
+
+    expect(factorySource).not.toContain('new RenderTarget');
+    expect(factorySource).not.toContain('CubeCamera');
+    expect(factorySource).not.toContain('ReflectionProbe');
+    expect(hostSource).toContain('createTexture');
+    expect(hostSource).toContain('RhiCommandEncoder');
+    expect(hostSource).not.toMatch(/queue\.submit|finish\(/);
+    expect(hostSource).not.toMatch(/RenderGraph|AssetRegistry/);
+  });
+
+  it('keeps host lifecycle calls idempotent after renderer disposal', () => {
+    const host = createRenderTargetHost();
+
+    expect(host.owner).toBe('renderer');
+    host.beginFrame();
+    host.onFrameSubmitted();
+    host.recover();
+    host.dispose();
+    host.beginFrame();
+    host.onFrameSubmitted();
+    host.recover();
+    host.dispose();
+  });
+
+  it('binds only the active physical view after the completion receipt settles', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const host = createRenderTargetHost({ getDevice: () => device });
+    const targetResult = host.createRenderTarget({
+      shape: 'cube',
+      width: 2,
+      height: 2,
+      format: 'rgba8unorm',
+      mipLevels: 1,
+      sampleCount: 1,
+      sampled: true,
+      readback: false,
+    });
+    expect(targetResult.ok).toBe(true);
+    if (!targetResult.ok) return;
+    const sourceResult = host.createRenderTargetTextureSource(targetResult.value, {
+      aspect: 'color',
+      dimension: 'cube',
+      mipLevel: 0,
+    });
+    expect(sourceResult.ok).toBe(true);
+    if (!sourceResult.ok) return;
+    const target = targetResult.value;
+    const source = sourceResult.value;
+    host.beginFrame();
+    const before = host.resolveRenderTargetTextureSource(source);
+    expect(before?.textureView).toBeUndefined();
+    let resolveCompletion:
+      | ((value: { readonly ok: true; readonly value: undefined }) => void)
+      | undefined;
+    const completion = new Promise<{ readonly ok: true; readonly value: undefined }>((resolve) => {
+      resolveCompletion = resolve;
+    });
+    host.onFrameSubmitted(completion);
+    resolveCompletion?.({ ok: true, value: undefined });
+    await completion;
+    await Promise.resolve();
+    const after = host.resolveRenderTargetTextureSource(source);
+    expect(after?.textureView).toBeDefined();
+    host.dispose();
+    expect(host.getPhysicalTarget(target)).toBeUndefined();
+  });
+
+  it('holds a progressive cube candidate until the renderer promotion gate opens', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    let canPromote = false;
+    const host = createRenderTargetHost({
+      getDevice: () => device,
+      canPromoteTarget: () => canPromote,
+    });
+    const targetResult = host.createRenderTarget({
+      shape: 'cube',
+      width: 2,
+      height: 2,
+      format: 'rgba8unorm',
+      mipLevels: 1,
+      sampleCount: 1,
+      sampled: true,
+      readback: false,
+    });
+    expect(targetResult.ok).toBe(true);
+    if (!targetResult.ok) return;
+    const sourceResult = host.createRenderTargetTextureSource(targetResult.value, {
+      aspect: 'color',
+      dimension: 'cube',
+      mipLevel: 0,
+    });
+    expect(sourceResult.ok).toBe(true);
+    if (!sourceResult.ok) return;
+
+    host.beginFrame();
+    const completion = Promise.resolve({ ok: true, value: undefined } as const);
+    host.onFrameSubmitted(completion);
+    await completion;
+    await Promise.resolve();
+    expect(host.resolveRenderTargetTextureSource(sourceResult.value)?.textureView).toBeUndefined();
+
+    canPromote = true;
+    host.onFrameSubmitted(Promise.resolve({ ok: true, value: undefined } as const));
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(host.resolveRenderTargetTextureSource(sourceResult.value)?.textureView).toBeDefined();
+    host.dispose();
+  });
+
+  it('retires physical generations and readback tickets across recovery', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    let generation = 0;
+    const host = createRenderTargetHost({
+      getDevice: () => device,
+      getGeneration: () => generation,
+    });
+    const targetResult = host.createRenderTarget({
+      shape: '2d',
+      width: 2,
+      height: 2,
+      format: 'rgba8unorm',
+      mipLevels: 1,
+      sampleCount: 1,
+      sampled: true,
+      readback: true,
+    });
+    expect(targetResult.ok).toBe(true);
+    if (!targetResult.ok) return;
+    const target = targetResult.value;
+    host.beginFrame();
+    host.onFrameSubmitted();
+    await Promise.resolve();
+    expect(host.getPhysicalTarget(target)).toBeDefined();
+    const ticket = host.requestTargetReadback(target, {
+      mipLevel: 0,
+    });
+    expect(ticket.ok).toBe(true);
+
+    generation = 1;
+    host.recover();
+    expect(host.getPhysicalTarget(target)).toBeUndefined();
+    if (ticket.ok) {
+      const stale = await host.observeTargetReadbacks({ frameId: 1, deviceGeneration: 0 }, [
+        ticket.value,
+      ]);
+      expect(stale.ok).toBe(false);
+      if (!stale.ok) expect(stale.error.code).toBe('render-target-state-invalid');
+    }
+
+    host.beginFrame();
+    host.onFrameSubmitted();
+    await Promise.resolve();
+    expect(host.getPhysicalTarget(target)).toBeDefined();
+    host.dispose();
+  });
+});

package/src/__tests__/render-target-owner.unit.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest';
+import type { RenderTargetDescriptor } from '../targets/contracts';
+import {
+  createRenderTargetOwner,
+  type RenderTargetOwner,
+  type RenderTargetOwnerInspection,
+} from '../targets/owner';
+
+const descriptor: RenderTargetDescriptor = {
+  shape: '2d',
+  width: 128,
+  height: 64,
+  format: 'rgba8unorm',
+  mipLevels: 1,
+  sampleCount: 1,
+  sampled: true,
+  readback: true,
+};
+
+function makeOwner(): RenderTargetOwner {
+  return createRenderTargetOwner({ rendererId: Symbol('renderer'), initialGeneration: 7 });
+}
+
+function inspect(owner: RenderTargetOwner, target: Parameters<RenderTargetOwner['inspect']>[0]) {
+  const result = owner.inspect(target);
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+function value<T>(
+  result:
+    | { readonly ok: true; readonly value: T }
+    | { readonly ok: false; readonly error: unknown },
+): T {
+  if (!result.ok) throw result.error;
+  return result.value;
+}
+
+describe('RenderTarget logical owner', () => {
+  it('keeps the logical token stable while promotion is receipt-gated', () => {
+    const owner = makeOwner();
+    const created = owner.create(descriptor);
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+
+    const target = created.value;
+    expect(inspect(owner, target)).toMatchObject({ state: 'uninitialized', generation: 0 });
+
+    const candidate = owner.stage(target);
+    expect(candidate.ok).toBe(true);
+    if (!candidate.ok) return;
+    expect(inspect(owner, target)).toMatchObject({
+      state: 'candidate',
+      generation: 0,
+      candidate: candidate.value,
+    });
+
+    expect(owner.promote(target, candidate.value.generation).ok).toBe(true);
+    expect(inspect(owner, target)).toMatchObject({ state: 'active', generation: 7 });
+    const promoted = owner.inspect(target);
+    expect(promoted.ok).toBe(true);
+    if (promoted.ok) expect(promoted.value.token).toBe(target);
+  });
+
+  it('retains active descriptor and LKG when a candidate fails at any stage', () => {
+    const owner = makeOwner();
+    const target = value(owner.create(descriptor));
+    value(owner.stage(target));
+    value(owner.promote(target, 7));
+
+    const resized = { ...descriptor, width: 256, height: 128 };
+    const candidate = value(owner.stage(target, resized));
+    const failed = owner.rejectCandidate(target, candidate.generation, 'submit');
+    expect(failed.ok).toBe(false);
+    expect(inspect(owner, target)).toMatchObject({
+      state: 'active',
+      generation: 7,
+      descriptor,
+    });
+    expect(inspect(owner, target).candidate).toBeUndefined();
+  });
+
+  it('separates logical token identity from physical generation during recovery', () => {
+    const owner = makeOwner();
+    const target = value(owner.create(descriptor));
+    value(owner.stage(target));
+    value(owner.promote(target, 7));
+
+    const recovered = owner.beginRecovery(target, 8);
+    expect(recovered.ok).toBe(true);
+    expect(inspect(owner, target)).toMatchObject({ state: 'rebuilding', generation: 8 });
+    expect(owner.finishRecovery(target).ok).toBe(true);
+    expect(inspect(owner, target)).toMatchObject({ state: 'uninitialized', generation: 8 });
+    expect(inspect(owner, target).token).toBe(target);
+  });
+
+  it('retires only the old generation, keeps destroy idempotent, and rejects foreign tokens', () => {
+    const owner = makeOwner();
+    const other = makeOwner();
+    const target = value(owner.create(descriptor));
+    value(owner.stage(target));
+    value(owner.promote(target, 7));
+
+    expect(owner.retire(target, 7).ok).toBe(true);
+    expect(owner.destroy(target).ok).toBe(true);
+    expect(owner.destroy(target).ok).toBe(true);
+    expect(owner.inspect(target).ok).toBe(false);
+
+    const foreign = value(other.create(descriptor));
+    const foreignResult = owner.inspect(foreign);
+    expect(foreignResult.ok).toBe(false);
+    if (!foreignResult.ok) expect(foreignResult.error.code).toBe('render-target-state-invalid');
+  });
+
+  it('exposes only bounded inspection facts for the owner state', () => {
+    const owner = makeOwner();
+    const target = value(owner.create(descriptor));
+    const snapshot = inspect(owner, target);
+    const publicFacts: RenderTargetOwnerInspection = snapshot;
+    expect(Object.keys(publicFacts).sort()).toEqual(['descriptor', 'generation', 'state', 'token']);
+  });
+});

package/src/__tests__/render-target-probe-soak.perf.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+import { createCubeCaptureScheduler } from '../capture/scheduler';
+import { boundedReflectionProbeFilterWork } from '../record/typed-frame-graph';
+import { advanceProbeFilter, createProbeFilterState } from '../reflection/filter';
+import type { RenderTarget } from '../targets/contracts';
+
+const FRAME_COUNT = 300;
+const target = {} as RenderTarget;
+
+describe('RenderTarget and ReflectionProbe 300-frame soak contract', () => {
+  it('keeps off and settled steady-state work exactly zero', () => {
+    const scheduler = createCubeCaptureScheduler({ maxFacesPerFrame: 1 });
+    const initialFilter = createProbeFilterState({ probeIndex: 0, faceCount: 6, mipCount: 5 });
+    const completeFilter = {
+      ...initialFilter,
+      cursor: initialFilter.faceCount * initialFilter.mipCount,
+    };
+
+    for (let frame = 0; frame < FRAME_COUNT; frame += 1) {
+      scheduler.beginFrame();
+      expect(scheduler.nextWork()).toHaveLength(0);
+      expect(boundedReflectionProbeFilterWork({ work: [], maxStepsPerFrame: 1 })).toHaveLength(0);
+      expect(advanceProbeFilter(completeFilter)).toBeUndefined();
+    }
+
+    expect({ extraction: 0, encoder: 0, finish: 0, submit: 0 }).toEqual({
+      extraction: 0,
+      encoder: 0,
+      finish: 0,
+      submit: 0,
+    });
+  });
+
+  it('bounds one capture face and one filter step while settling one update', () => {
+    const scheduler = createCubeCaptureScheduler({ maxFacesPerFrame: 1 });
+    const requested = scheduler.request({
+      target,
+      position: [0, 0, 0],
+      near: 0.1,
+      far: 100,
+      updateIntent: 'on-demand',
+      requestVersion: 1,
+      faceBudget: 1,
+    });
+    expect(requested.ok).toBe(true);
+
+    let filter = createProbeFilterState({ probeIndex: 0, faceCount: 6, mipCount: 5 });
+    let captureFrames = 0;
+    let filterFrames = 0;
+    let extraction = 0;
+    let encoder = 0;
+    let finish = 0;
+    let submit = 0;
+    let peakCandidates = 0;
+
+    for (let frame = 0; frame < FRAME_COUNT; frame += 1) {
+      scheduler.beginFrame();
+      const faces = scheduler.nextWork();
+      const filterStep = advanceProbeFilter(filter);
+      const filterWork = boundedReflectionProbeFilterWork({
+        work: filterStep === undefined ? [] : [filterStep],
+        maxStepsPerFrame: 1,
+      });
+      expect(faces.length).toBeLessThanOrEqual(1);
+      expect(filterWork.length).toBeLessThanOrEqual(1);
+
+      if (faces.length > 0) {
+        captureFrames += 1;
+        extraction += 1;
+        encoder += 1;
+        finish += 1;
+        submit += 1;
+        expect(scheduler.completeSubmission(true).ok).toBe(true);
+      }
+      if (filterStep !== undefined) {
+        filterFrames += 1;
+        filter = { ...filter, cursor: filter.cursor + 1 };
+      }
+      peakCandidates = Math.max(peakCandidates, scheduler.inspect(target).candidateGeneration ?? 0);
+    }
+
+    expect(captureFrames).toBe(6);
+    expect(filterFrames).toBe(30);
+    expect({ extraction, encoder, finish, submit }).toEqual({
+      extraction: 6,
+      encoder: 6,
+      finish: 6,
+      submit: 6,
+    });
+    expect(peakCandidates).toBe(1);
+    expect(scheduler.inspect(target).pendingFaces).toEqual([]);
+    expect(scheduler.inspect(target).activeGeneration).toBe(1);
+  });
+});