@forgeax/engine-render 0.1.4 → 0.1.6

package/src/__tests__/render-feature-graphics-staging.unit.test.ts

@@ -1,200 +0,0 @@
-import { RenderGraph, type ResourceDescriptor } from '@forgeax/engine-render-graph';
-import { err } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
-import { RenderFeaturePreparationFailedError } from '../errors/render';
-import type { RenderFeatureGraphContribution } from '../features/graph-contribution';
-import {
-  composeRenderFeatureGraph,
-  createRenderFeatureContributionStaging,
-} from '../features/graph-contribution';
-import type {
-  RenderFeatureGraphicsPassDescriptor,
-  RenderFeaturePreparedGraphicsState,
-  RenderFeaturePreparedRef,
-} from '../features/prepared-graphics';
-import { createRenderFeatureTarget } from '../features/targets';
-
-const target: ResourceDescriptor = { kind: 'texture', lifetime: 'transient' };
-
-const pass: RenderFeatureGraphicsPassDescriptor = {
-  attachments: {
-    colors: [{ resource: 'color', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' }],
-  },
-  draws: [
-    {
-      kind: 'draw',
-      pipeline: { kind: 'pipeline', generation: 2 } as RenderFeaturePreparedRef<'pipeline'>,
-      bindings: [{ kind: 'bindings', generation: 2 }],
-      vertexData: [{ slot: 0, resource: { kind: 'vertex-data', generation: 2 } }],
-      command: { vertexCount: 3, instanceCount: 1 },
-    },
-  ],
-};
-
-describe('render feature graphics staging', () => {
-  it('projects the latest resolved graphics snapshot after a topology-stable update', () => {
-    const graphicsState: RenderFeaturePreparedGraphicsState = {
-      capabilityAvailable: true,
-      generation: 1,
-      attachments: [],
-      pipeline: pass.draws[0]?.pipeline,
-      bindings: pass.draws[0]?.bindings ?? [],
-      vertexData: pass.draws[0]?.vertexData.map((vertex) => vertex.resource) ?? [],
-      indexData: [],
-    };
-    const contribution = (generation: number): RenderFeatureGraphContribution => ({
-      featureIdentity: 'synthetic.graphics',
-      order: 0,
-      resources: [],
-      passes: [
-        {
-          featureIdentity: 'synthetic.graphics',
-          order: 0,
-          name: 'synthetic.graphics::forward',
-          descriptor: { reads: [], writes: [] },
-          dependsOn: [],
-          graphics: pass,
-          graphicsState,
-          resolvedGraphics: {
-            generation,
-            resolve: () => undefined,
-          },
-        },
-      ],
-      topologySignature: 'synthetic.graphics::forward',
-    });
-    const observed: number[] = [];
-    const graph = new RenderGraph();
-    const composed = composeRenderFeatureGraph(graph, [contribution(1)], (ctx, current) => {
-      void ctx;
-      observed.push(current.resolvedGraphics?.generation ?? -1);
-    });
-    expect(composed.ok).toBe(true);
-    if (!composed.ok) return;
-    expect(graph.compile({ backendKind: 'null', caps: {} as never }).ok).toBe(true);
-    graph.execute(undefined);
-    expect(composed.value.update([contribution(2)]).topologyChanged).toBe(false);
-    graph.execute(undefined);
-    expect(observed).toEqual([1, 2]);
-  });
-
-  it('projects an accepted graphics pass into the active graph contribution', () => {
-    const staging = createRenderFeatureContributionStaging('synthetic.graphics', 0);
-    expect(staging.addResource('color', target).ok).toBe(true);
-    expect(staging.addGraphicsPass('forward', pass).ok).toBe(true);
-
-    const contribution = staging.commit();
-    expect(contribution.ok).toBe(true);
-    if (!contribution.ok) return;
-    expect(contribution.value.passes).toHaveLength(1);
-    expect(contribution.value.passes[0]).toMatchObject({
-      name: 'synthetic.graphics::forward',
-      graphics: pass,
-    });
-
-    const graph = new RenderGraph();
-    const composed = composeRenderFeatureGraph(graph, [contribution.value]);
-    expect(composed.ok).toBe(true);
-    if (composed.ok) {
-      expect(composed.value.passNames).toEqual(['synthetic.graphics::forward']);
-      expect(composed.value.graph).toBe(graph);
-    }
-  });
-
-  it('keeps the reserved swapchain attachment unqualified', () => {
-    const staging = createRenderFeatureContributionStaging('synthetic.graphics', 0);
-    const swapchainPass: RenderFeatureGraphicsPassDescriptor = {
-      ...pass,
-      attachments: {
-        colors: [
-          { resource: 'swapchain', format: 'rgba8unorm-srgb', loadOp: 'load', storeOp: 'store' },
-        ],
-      },
-    };
-    expect(staging.addGraphicsPass('overlay', swapchainPass).ok).toBe(true);
-    const contribution = staging.commit();
-    expect(contribution.ok).toBe(true);
-    if (!contribution.ok) return;
-    expect(contribution.value.passes[0]?.descriptor.writes).toEqual(['swapchain']);
-  });
-
-  it('projects render-pipeline target handles to semantic graph dependencies', () => {
-    const colorTarget = createRenderFeatureTarget({
-      kind: 'scene-color',
-      format: 'rgba16float',
-      sampleCount: 1,
-    });
-    const depthTarget = createRenderFeatureTarget({
-      kind: 'scene-depth',
-      format: 'depth24plus-stencil8',
-      sampleCount: 1,
-    });
-    const targetPass: RenderFeatureGraphicsPassDescriptor = {
-      ...pass,
-      attachments: {
-        colors: [
-          { resource: colorTarget, format: colorTarget.format, loadOp: 'load', storeOp: 'store' },
-        ],
-        depthStencil: {
-          resource: depthTarget,
-          format: depthTarget.format,
-          depthLoadOp: 'load',
-          depthStoreOp: 'store',
-        },
-      },
-    };
-    const staging = createRenderFeatureContributionStaging('synthetic.scene', 0);
-    expect(staging.addGraphicsPass('particles', targetPass).ok).toBe(true);
-    const contribution = staging.commit();
-    expect(contribution.ok).toBe(true);
-    if (!contribution.ok) return;
-
-    expect(contribution.value.passes[0]?.descriptor).toMatchObject({
-      reads: ['scene-depth'],
-      writes: ['scene-color'],
-    });
-  });
-
-  it('keeps ordinary addPass graph-only and contributes no work for an empty draw list', () => {
-    const staging = createRenderFeatureContributionStaging('synthetic.empty', 0);
-    const empty: RenderFeatureGraphicsPassDescriptor = { ...pass, draws: [] };
-    expect(staging.addGraphicsPass('empty', empty).ok).toBe(true);
-    const contribution = staging.commit();
-    expect(contribution.ok).toBe(true);
-    if (contribution.ok) {
-      expect(contribution.value.passes).toHaveLength(0);
-      expect(contribution.value.resources).toHaveLength(0);
-    }
-  });
-
-  it('treats asynchronous pipeline warm-up as an empty retryable frame', () => {
-    const staging = createRenderFeatureContributionStaging('synthetic.warmup', 0, undefined, () =>
-      err(
-        new RenderFeaturePreparationFailedError(
-          'synthetic.warmup',
-          0,
-          'resolve',
-          'pipeline',
-          'custom-material',
-          'pipeline-pending',
-          'next-frame',
-        ),
-      ),
-    );
-
-    expect(staging.addGraphicsPass('warmup', pass).ok).toBe(true);
-    const contribution = staging.commit();
-    expect(contribution.ok).toBe(true);
-    if (contribution.ok) expect(contribution.value.passes).toHaveLength(0);
-  });
-
-  it('aborts graphics staging without creating a feature-private graph', () => {
-    const staging = createRenderFeatureContributionStaging('synthetic.failed', 0);
-    expect(staging.addResource('color', target).ok).toBe(true);
-    expect(staging.addGraphicsPass('forward', pass).ok).toBe(true);
-    staging.abort();
-    expect(staging.resources).toEqual([]);
-    expect(staging.passes).toEqual([]);
-    expect(staging.commit().ok).toBe(false);
-  });
-});

package/src/__tests__/render-feature-order.unit.test.ts

@@ -1,66 +0,0 @@
-import type { ResourceDescriptor } from '@forgeax/engine-render-graph';
-import { describe, expect, it } from 'vitest';
-import {
-  createRenderFeatureContributionStaging,
-  mergeRenderFeatureContributions,
-} from '../features/graph-contribution';
-
-const resource: ResourceDescriptor = {
-  kind: 'texture',
-  lifetime: 'transient',
-};
-
-function pass(reads: readonly string[] = []) {
-  return { reads, writes: [], execute: () => undefined };
-}
-
-describe('render feature contribution order', () => {
-  it('sorts contributions by registration order before preserving declaration order', () => {
-    const late = createRenderFeatureContributionStaging('synthetic.late', 2);
-    const early = createRenderFeatureContributionStaging('synthetic.early', 0);
-    late.addResource('target', resource);
-    early.addResource('target', resource);
-    late.addPass('late-pass', pass(['target']));
-    early.addPass('first-pass', pass(['target']));
-
-    const merged = mergeRenderFeatureContributions([
-      late.commit().unwrap(),
-      early.commit().unwrap(),
-    ]);
-
-    expect(merged.ok).toBe(true);
-    if (!merged.ok) return;
-    expect(merged.value.passes.map((entry) => entry.name)).toEqual([
-      'synthetic.early::first-pass',
-      'synthetic.late::late-pass',
-    ]);
-  });
-
-  it('keeps a same-feature dependency in declared order', () => {
-    const feature = createRenderFeatureContributionStaging('synthetic.feature', 0);
-    feature.addResource('target', resource);
-    feature.addPass('first', pass(['target']));
-    feature.addPass('second', pass(['target']), {
-      dependsOn: [{ featureIdentity: 'synthetic.feature', passIdentity: 'first' }],
-    });
-
-    const merged = mergeRenderFeatureContributions([feature.commit().unwrap()]);
-
-    expect(merged.ok).toBe(true);
-  });
-
-  it('reports a same-feature dependency on a later declaration', () => {
-    const feature = createRenderFeatureContributionStaging('synthetic.feature', 0);
-    feature.addResource('target', resource);
-    feature.addPass('first', pass(['target']), {
-      dependsOn: [{ featureIdentity: 'synthetic.feature', passIdentity: 'second' }],
-    });
-    feature.addPass('second', pass(['target']));
-
-    const merged = mergeRenderFeatureContributions([feature.commit().unwrap()]);
-
-    expect(merged.ok).toBe(false);
-    if (merged.ok) return;
-    expect(merged.error.code).toBe('render-feature-pass-order-conflict');
-  });
-});

package/src/__tests__/render-feature-prepared-graphics-recording.unit.test.ts

@@ -1,107 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import type {
-  RenderFeatureGraphicsPassDescriptor,
-  RenderFeaturePreparedGraphicsState,
-  RenderFeaturePreparedRef,
-} from '../features/prepared-graphics';
-import { recordRenderFeatureGraphicsPass } from '../record/frame-targets';
-
-type RecordingLedger = {
-  pipeline: number;
-  binding: number;
-  vertex: number;
-  index: number;
-  draw: number;
-};
-
-function ledger(): RecordingLedger {
-  return { pipeline: 0, binding: 0, vertex: 0, index: 0, draw: 0 };
-}
-
-function ref<Kind extends RenderFeaturePreparedRef['kind']>(
-  kind: Kind,
-  generation = 3,
-): RenderFeaturePreparedRef<Kind> {
-  return { kind, generation };
-}
-
-const pipeline = ref('pipeline');
-const bindings = ref('bindings');
-const vertices = ref('vertex-data');
-const indices = ref('index-data');
-
-const pass: RenderFeatureGraphicsPassDescriptor = {
-  attachments: {
-    colors: [{ resource: 'color', format: 'rgba8unorm', loadOp: 'load', storeOp: 'store' }],
-  },
-  draws: [
-    {
-      kind: 'draw',
-      pipeline,
-      bindings: [bindings],
-      vertexData: [{ slot: 0, resource: vertices }],
-      command: { vertexCount: 3, instanceCount: 1 },
-    },
-  ],
-};
-
-const state: RenderFeaturePreparedGraphicsState = {
-  capabilityAvailable: true,
-  generation: 3,
-  attachments: [{ resource: 'color', format: 'rgba8unorm' }],
-  pipeline,
-  bindings: [bindings],
-  vertexData: [vertices],
-  indexData: [indices],
-};
-
-describe('host-owned prepared graphics recording', () => {
-  it.each([
-    ['pipeline', { pipeline: undefined }],
-    ['bindings', { bindings: [] }],
-    ['vertex', { vertexData: [] }],
-    ['attachment', { attachments: [] }],
-  ] as const)('rejects missing %s before any RHI mutation', (_label, change) => {
-    const calls = ledger();
-    const result = recordRenderFeatureGraphicsPass(
-      'synthetic.invalid',
-      pass,
-      { ...state, ...change },
-      calls,
-    );
-    expect(result.ok).toBe(false);
-    expect(calls).toEqual(ledger());
-  });
-
-  it('rejects stale and foreign-kind records before recording the healthy feature', () => {
-    const stale = ledger();
-    const staleResult = recordRenderFeatureGraphicsPass(
-      'synthetic.invalid',
-      pass,
-      { ...state, generation: 4 },
-      stale,
-    );
-    expect(staleResult.ok).toBe(false);
-    expect(stale).toEqual(ledger());
-
-    const originalDraw = pass.draws[0];
-    expect(originalDraw).toBeDefined();
-    if (originalDraw === undefined) return;
-    const foreign = ledger();
-    const foreignResult = recordRenderFeatureGraphicsPass(
-      'synthetic.invalid',
-      { ...pass, draws: [{ ...originalDraw, pipeline: ref('bindings') as never }] },
-      state,
-      foreign,
-    );
-    expect(foreignResult.ok).toBe(false);
-    expect(foreign).toEqual(ledger());
-  });
-
-  it('records a complete draw only after all validation succeeds', () => {
-    const calls = ledger();
-    const result = recordRenderFeatureGraphicsPass('synthetic.valid', pass, state, calls);
-    expect(result).toMatchObject({ ok: true, value: { acceptedDrawCount: 1 } });
-    expect(calls).toEqual({ pipeline: 1, binding: 1, vertex: 1, index: 0, draw: 1 });
-  });
-});

package/src/__tests__/render-feature-staging.unit.test.ts

@@ -1,94 +0,0 @@
-import type { ResourceDescriptor } from '@forgeax/engine-render-graph';
-import { describe, expect, it } from 'vitest';
-import {
-  createRenderFeatureContributionStaging,
-  mergeRenderFeatureContributions,
-} from '../features/graph-contribution';
-
-const transientTexture: ResourceDescriptor = {
-  kind: 'texture',
-  lifetime: 'transient',
-};
-
-function pass() {
-  return { reads: [], writes: ['color'], execute: () => undefined };
-}
-
-describe('render feature contribution staging', () => {
-  it('commits resources and passes only after a successful callback', () => {
-    const staging = createRenderFeatureContributionStaging('synthetic.alpha', 0);
-    expect(staging.addResource('color', transientTexture).ok).toBe(true);
-    expect(staging.addPass('draw', pass()).ok).toBe(true);
-
-    const contribution = staging.commit();
-
-    expect(contribution.ok).toBe(true);
-    if (!contribution.ok) return;
-    expect(contribution.value.resources).toHaveLength(1);
-    expect(contribution.value.passes.map((entry) => entry.name)).toEqual(['synthetic.alpha::draw']);
-  });
-
-  it('does not publish a partial contribution when staging is aborted', () => {
-    const staging = createRenderFeatureContributionStaging('synthetic.failed', 0);
-    expect(staging.addResource('color', transientTexture).ok).toBe(true);
-    expect(staging.addPass('draw', pass()).ok).toBe(true);
-
-    staging.abort();
-
-    expect(staging.commit().ok).toBe(false);
-    expect(staging.resources).toHaveLength(0);
-    expect(staging.passes).toHaveLength(0);
-  });
-
-  it('keeps identical local names isolated by feature namespace', () => {
-    const alpha = createRenderFeatureContributionStaging('synthetic.alpha', 0);
-    const beta = createRenderFeatureContributionStaging('synthetic.beta', 1);
-    alpha.addResource('color', transientTexture);
-    beta.addResource('color', transientTexture);
-    alpha.addPass('draw', pass());
-    beta.addPass('draw', pass());
-
-    const merged = mergeRenderFeatureContributions([
-      alpha.commit().unwrap(),
-      beta.commit().unwrap(),
-    ]);
-
-    expect(merged.ok).toBe(true);
-    if (!merged.ok) return;
-    expect(merged.value.resources.map((entry) => entry.name)).toEqual([
-      'synthetic.alpha::color',
-      'synthetic.beta::color',
-    ]);
-    expect(merged.value.passes.map((entry) => entry.name)).toEqual([
-      'synthetic.alpha::draw',
-      'synthetic.beta::draw',
-    ]);
-  });
-
-  it('rejects a dependency that points to a later feature', () => {
-    const alpha = createRenderFeatureContributionStaging('synthetic.alpha', 0);
-    const beta = createRenderFeatureContributionStaging('synthetic.beta', 1);
-    alpha.addResource('color', transientTexture);
-    beta.addResource('color', transientTexture);
-    alpha.addPass('draw', pass(), {
-      dependsOn: [{ featureIdentity: 'synthetic.beta', passIdentity: 'draw' }],
-    });
-    beta.addPass('draw', pass());
-
-    const merged = mergeRenderFeatureContributions([
-      alpha.commit().unwrap(),
-      beta.commit().unwrap(),
-    ]);
-
-    expect(merged.ok).toBe(false);
-    if (merged.ok) return;
-    expect(merged.error.code).toBe('render-feature-pass-order-conflict');
-    if (merged.error.code === 'render-feature-pass-order-conflict') {
-      expect(merged.error.detail).toMatchObject({
-        featureIdentity: 'synthetic.alpha',
-        passIdentity: 'synthetic.alpha::draw',
-        dependencyIdentity: 'synthetic.beta::draw',
-      });
-    }
-  });
-});

package/src/__tests__/renderer-render-scene-public.test-d.ts

@@ -1,27 +0,0 @@
-import { expectTypeOf } from 'vitest';
-import type { Renderer } from '../renderer';
-
-declare const renderer: Renderer;
-
-expectTypeOf(renderer.renderScene.fullRebuilds).toEqualTypeOf<number>();
-expectTypeOf(renderer.renderScene.worldEntitiesScanned).toEqualTypeOf<number>();
-expectTypeOf(renderer.renderScene.instanceUpdates).toEqualTypeOf<number>();
-expectTypeOf(renderer.renderScene.lastResyncReason).toEqualTypeOf<
-  | 'attach'
-  | 'asset-catalog-changed'
-  | 'shared-ref-changed'
-  | 'journal-overflow'
-  | 'unsupported-change'
-  | 'non-rigid-lane'
-  | 'explicit-invalidate'
-  | undefined
->();
-
-if (renderer.renderScene.gpu.status === 'resident') {
-  expectTypeOf(renderer.renderScene.gpu.uploadBytes).toEqualTypeOf<number>();
-}
-
-expectTypeOf(renderer.renderScene.gpuDriven.candidateUploadBytes).toEqualTypeOf<number>();
-expectTypeOf(renderer.renderScene.gpuDriven.batchUploadBytes).toEqualTypeOf<number>();
-expectTypeOf(renderer.renderScene.gpuDriven.validatedGpuOwnedRows).toEqualTypeOf<number>();
-expectTypeOf(renderer.renderScene.gpuDriven.cpuFallbackDrawItems).toEqualTypeOf<number>();