@forgeax/engine-render 0.1.4 → 0.1.7

package/src/__tests__/render-dispatch-membership.unit.test.ts

@@ -1,117 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-  buildSubmissionCandidateMembership,
-  type SubmissionPlan,
-} from '../gpu-driven/batch-topology';
-import {
-  buildRenderCandidateDomain,
-  buildRenderDispatchMembership,
-  renderCandidateCsmCandidates,
-} from '../render-dispatch-membership';
-import type { DispatchEntry, RenderableSnapshot } from '../render-system-extract';
-import { defaultMaterialSnapshot } from '../render-system-extract';
-
-function dispatchEntry(renderableIndex: number, lightMode: string): DispatchEntry {
-  return { renderableIndex, tags: { LightMode: lightMode } } as unknown as DispatchEntry;
-}
-
-describe('render dispatch membership owner', () => {
-  it('caches one Set per immutable dispatch identity', () => {
-    const dispatch = [dispatchEntry(2, 'ShadowCaster'), dispatchEntry(7, 'Forward')];
-    const first = buildRenderDispatchMembership(dispatch);
-    const second = buildRenderDispatchMembership(dispatch);
-
-    expect(second).toBe(first);
-    expect(first.dispatch).toBe(dispatch);
-    expect([...first.shadowCasterCandidateIndices]).toEqual([2]);
-    expect(first.shadowCasterCandidateIndices.has(7)).toBe(false);
-  });
-
-  it('publishes a new owner when the dispatch domain changes', () => {
-    const firstDispatch = [dispatchEntry(0, 'ShadowCaster')];
-    const secondDispatch = [dispatchEntry(0, 'Forward')];
-
-    const first = buildRenderDispatchMembership(firstDispatch);
-    const second = buildRenderDispatchMembership(secondDispatch);
-
-    expect(second).not.toBe(first);
-    expect(second.shadowCasterCandidateIndices.size).toBe(0);
-  });
-
-  it('reuses the immutable default material projection for handle zero', () => {
-    expect(defaultMaterialSnapshot(0)).toBe(defaultMaterialSnapshot(0));
-    expect(defaultMaterialSnapshot(1)).not.toBe(defaultMaterialSnapshot(0));
-  });
-
-  it('caches the candidate identity index with the dispatch owner', () => {
-    const candidates = [
-      { worldId: 3, entityKey: 11 },
-      { worldId: 4, entityKey: 12 },
-    ] as RenderableSnapshot[];
-    const dispatch = [dispatchEntry(0, 'ShadowCaster')];
-    const first = buildRenderCandidateDomain(candidates, dispatch);
-    const second = buildRenderCandidateDomain(candidates, dispatch);
-
-    expect(second).toBe(first);
-    expect(first.membership).toBe(buildRenderDispatchMembership(dispatch));
-    expect(first.indexByIdentity.get('3:11')).toBe(0);
-    expect(first.indexByIdentity.get('4:12')).toBe(1);
-  });
-
-  it('caches the derived CSM caster view with the candidate owner', () => {
-    const candidates = [
-      {
-        worldId: 3,
-        entityKey: 11,
-        transform: { world: new Float32Array(16) },
-        localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
-      },
-    ] as unknown as RenderableSnapshot[];
-    const dispatch = [dispatchEntry(0, 'ShadowCaster')];
-    const domain = buildRenderCandidateDomain(candidates, dispatch);
-
-    expect(renderCandidateCsmCandidates(domain)).toBe(renderCandidateCsmCandidates(domain));
-    expect(renderCandidateCsmCandidates(domain)[0]?.shadowCaster).toBe(true);
-  });
-
-  it('caches the candidate-to-batch reverse owner per immutable submission plan', () => {
-    const plan = {
-      revision: 1,
-      candidateCount: 2,
-      visibleCapacity: 2,
-      batches: [
-        {
-          batchId: 4,
-          generation: 1,
-          key: {} as never,
-          candidates: [{ primitiveIndex: 2, generation: 1, drawItemIndex: 0, instanceOrdinal: 0 }],
-          visibleBase: 0,
-          visibleCapacity: 1,
-          indirectOffset: 0,
-        },
-        {
-          batchId: 9,
-          generation: 1,
-          key: {} as never,
-          candidates: [
-            { primitiveIndex: 2, generation: 1, drawItemIndex: 1, instanceOrdinal: 0 },
-            { primitiveIndex: 7, generation: 1, drawItemIndex: 0, instanceOrdinal: 0 },
-          ],
-          visibleBase: 64,
-          visibleCapacity: 2,
-          indirectOffset: 256,
-        },
-      ],
-    } satisfies SubmissionPlan;
-
-    const first = buildSubmissionCandidateMembership(plan);
-    const second = buildSubmissionCandidateMembership(plan);
-
-    expect(second).toBe(first);
-    expect(first.byPrimitiveIndex.get(2)?.map((entry) => entry.batchId)).toEqual([4, 9]);
-    expect(first.byPrimitiveIndex.get(7)?.[0]?.batchId).toBe(9);
-    expect(first.byBatchId.get(4)?.candidates.map((candidate) => candidate.primitiveIndex)).toEqual(
-      [2],
-    );
-  });
-});

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

@@ -1,124 +0,0 @@
-import { err, ok } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
-import { RenderFeatureStageFailedError } from '../errors/render';
-import { createRenderFeatureHost, type RenderFeatureOwnedResource } from '../features/host';
-import type { RenderFeature } from '../features/types';
-
-function feature(identity: string): RenderFeature<{ readonly ready: true }> {
-  return {
-    identity,
-    extract: () => ok({ ready: true }),
-    prepare: () => ok(undefined),
-    contribute: () => ok(undefined),
-  };
-}
-
-function resource(
-  name: string,
-  release: () => ReturnType<RenderFeatureOwnedResource['release']>,
-): RenderFeatureOwnedResource {
-  return {
-    handle: { __renderFeatureResource: Symbol(name) } as never,
-    release,
-  };
-}
-
-describe('render feature construction ownership', () => {
-  it('rejects duplicate identity before a host can acquire resources', () => {
-    const result = createRenderFeatureHost([
-      feature('synthetic.shared'),
-      feature('synthetic.shared'),
-    ]);
-
-    expect(result.ok).toBe(false);
-    if (!result.ok && result.error.code === 'render-feature-registration-conflict') {
-      expect(result.error.code).toBe('render-feature-registration-conflict');
-      expect(result.error.detail.featureIdentity).toBe('synthetic.shared');
-    }
-  });
-
-  it('cleans transferred resources in registration order and isolates failures', () => {
-    const host = createRenderFeatureHost([
-      feature('synthetic.first'),
-      feature('synthetic.second'),
-    ]).unwrap();
-    const released: string[] = [];
-
-    host.registerResource(
-      'synthetic.first',
-      resource('first', () => {
-        released.push('first');
-        return ok(undefined);
-      }),
-    );
-    host.registerResource(
-      'synthetic.second',
-      resource('second-fails', () => {
-        released.push('second-fails');
-        return err(
-          new RenderFeatureStageFailedError('synthetic.second', 1, 'dispose', 'renderer-recover'),
-        );
-      }),
-    );
-    host.registerResource(
-      'synthetic.second',
-      resource('second-after-failure', () => {
-        released.push('second-after-failure');
-        return ok(undefined);
-      }),
-    );
-
-    const disposed = host.dispose();
-
-    expect(released).toEqual(['first', 'second-fails', 'second-after-failure']);
-    expect(disposed.ok).toBe(false);
-    if (!disposed.ok && disposed.error.code === 'render-feature-stage-failed') {
-      expect(disposed.error.code).toBe('render-feature-stage-failed');
-      expect(disposed.error.detail.stage).toBe('dispose');
-      const cleanupFailures = disposed.error.detail.cleanupFailures;
-      expect(cleanupFailures).toHaveLength(1);
-      if (cleanupFailures !== undefined) {
-        expect(cleanupFailures[0]?.featureIdentity).toBe('synthetic.second');
-      }
-    }
-
-    expect(host.dispose()).toEqual(ok(undefined));
-    expect(released).toEqual(['first', 'second-fails', 'second-after-failure']);
-  });
-
-  it('uninstalls one feature without disposing its neighbors', () => {
-    const disposed: string[] = [];
-    const first = {
-      ...feature('synthetic.first'),
-      dispose: () => {
-        disposed.push('first');
-        return ok(undefined);
-      },
-    };
-    const second = {
-      ...feature('synthetic.second'),
-      dispose: () => {
-        disposed.push('second');
-        return ok(undefined);
-      },
-    };
-    const host = createRenderFeatureHost([first, second]).unwrap();
-    const released: string[] = [];
-    host.registerResource(
-      'synthetic.first',
-      resource('first', () => {
-        released.push('first');
-        return ok(undefined);
-      }),
-    );
-
-    expect(host.uninstall(first)).toEqual(ok(undefined));
-    expect(host.features).toEqual([second]);
-    expect(released).toEqual(['first']);
-    expect(disposed).toEqual(['first']);
-    expect(host.uninstall(first)).toEqual(ok(undefined));
-
-    expect(host.dispose()).toEqual(ok(undefined));
-    expect(disposed).toEqual(['first', 'second']);
-  });
-});

package/src/__tests__/render-feature-error-code-owner.test-d.ts

@@ -1,27 +0,0 @@
-import { expectTypeOf, it } from 'vitest';
-import type {
-  RenderFeatureErrorCode,
-  RenderFeatureErrorDescriptor,
-  RenderFeatureErrorDetailByCode,
-} from '../features/types';
-import type {
-  RenderFeatureErrorCode as PublicRenderFeatureErrorCode,
-  RenderFeatureErrorDescriptor as PublicRenderFeatureErrorDescriptor,
-} from '../index';
-
-type DescriptorDetailsByCode = {
-  [Code in keyof RenderFeatureErrorDetailByCode]: Extract<
-    RenderFeatureErrorDescriptor,
-    { readonly code: Code }
-  >['detail'];
-};
-
-it('derives the public feature error code projection from its detail map', () => {
-  expectTypeOf<RenderFeatureErrorCode>().toEqualTypeOf<keyof RenderFeatureErrorDetailByCode>();
-  expectTypeOf<keyof RenderFeatureErrorDetailByCode>().toEqualTypeOf<RenderFeatureErrorCode>();
-  expectTypeOf<PublicRenderFeatureErrorCode>().toEqualTypeOf<RenderFeatureErrorCode>();
-  expectTypeOf<PublicRenderFeatureErrorDescriptor>().toEqualTypeOf<RenderFeatureErrorDescriptor>();
-  expectTypeOf<DescriptorDetailsByCode>().toEqualTypeOf<RenderFeatureErrorDetailByCode>();
-  expectTypeOf<'render-feature-not-real'>().not.toExtend<RenderFeatureErrorCode>();
-  expectTypeOf<'render-feature-not-real'>().not.toExtend<PublicRenderFeatureErrorCode>();
-});

package/src/__tests__/render-feature-gpu-buffer-usage-owner.test-d.ts

@@ -1,46 +0,0 @@
-import { readFileSync } from 'node:fs';
-import { describe, expect, expectTypeOf, it } from 'vitest';
-import type {
-  RenderFeatureGpuBufferDescriptor,
-  RenderFeatureGpuBufferUsage,
-} from '../features/prepared-gpu-work';
-
-type ExpectedBufferUsage = 'storage' | 'uniform' | 'indirect' | 'vertex' | 'index' | 'copy-src';
-
-const preparedGpuWorkSource = readFileSync(
-  new URL('../features/prepared-gpu-work.ts', import.meta.url),
-  'utf8',
-);
-
-describe('render feature GPU buffer usage owner', () => {
-  it('keeps the public usage vocabulary bilateral and descriptor-assignable', () => {
-    expectTypeOf<RenderFeatureGpuBufferUsage>().toEqualTypeOf<ExpectedBufferUsage>();
-    expectTypeOf<ExpectedBufferUsage>().toEqualTypeOf<RenderFeatureGpuBufferUsage>();
-
-    const descriptor = {
-      size: 24,
-      usage: ['storage', 'uniform', 'indirect', 'vertex', 'index', 'copy-src'],
-    } as const satisfies RenderFeatureGpuBufferDescriptor;
-    expectTypeOf<(typeof descriptor.usage)[number]>().toEqualTypeOf<RenderFeatureGpuBufferUsage>();
-
-    const acceptsDescriptor = (_descriptor: RenderFeatureGpuBufferDescriptor): void => {};
-    acceptsDescriptor(descriptor);
-    // @ts-expect-error unknown usage keys remain outside the closed owner vocabulary.
-    acceptsDescriptor({ size: 4, usage: ['map-read'] });
-  });
-
-  it('keeps BUFFER_USAGE as the executable source of the public vocabulary', () => {
-    expect(preparedGpuWorkSource).toContain(
-      'export type RenderFeatureGpuBufferUsage = keyof typeof BUFFER_USAGE;',
-    );
-    expect(preparedGpuWorkSource).not.toContain(
-      "export type RenderFeatureGpuBufferUsage =\n  | 'storage'",
-    );
-    expect(preparedGpuWorkSource).toContain('storage: 0x0080');
-    expect(preparedGpuWorkSource).toContain('uniform: 0x0040');
-    expect(preparedGpuWorkSource).toContain('indirect: 0x0100');
-    expect(preparedGpuWorkSource).toContain('vertex: 0x0020');
-    expect(preparedGpuWorkSource).toContain('index: 0x0010');
-    expect(preparedGpuWorkSource).toContain("'copy-src': 0x0004");
-  });
-});

package/src/__tests__/render-feature-graph.integration.test.ts

@@ -1,205 +0,0 @@
-import { World } from '@forgeax/engine-ecs';
-import type { RhiCanvasContext } from '@forgeax/engine-rhi';
-import { RhiNullCanvasContext, type RhiNullDevice, rhi } from '@forgeax/engine-rhi-null';
-import { ok } from '@forgeax/engine-types';
-import { describe, expect, it } from 'vitest';
-import { constructRenderer } from '../construct-renderer';
-import type { RenderPipeline } from '../render-pipeline';
-
-const manifest = `data:application/json,${encodeURIComponent(
-  JSON.stringify({
-    schemaVersion: '1.0.0',
-    entries: [
-      { hash: 'pbr00000', wgsl: '/* pbr stub */', glsl: '', bindings: '' },
-      { hash: 'unlit000', wgsl: '/* unlit stub */', glsl: '', bindings: '' },
-      { hash: 'tonemap0', wgsl: '/* tonemap stub */', glsl: '', bindings: '' },
-    ],
-  }),
-)}`;
-
-function canvas(): HTMLCanvasElement {
-  return {
-    width: 1,
-    height: 1,
-    getContext: () => null,
-    addEventListener: () => undefined,
-    removeEventListener: () => undefined,
-  } as unknown as HTMLCanvasElement;
-}
-
-function pipeline(trace: string[], builds: { count: number }, passName: string): RenderPipeline {
-  return {
-    build: ({ graph, contributeFeatures }, topology) => {
-      builds.count += 1;
-      const surface = graph.importTexture(
-        `${passName}.surface`,
-        {
-          format: topology.surface.storageFormat,
-          size: 'surface',
-          usage: 0x10,
-          viewFormats:
-            topology.surface.storageFormat === topology.surface.viewFormat
-              ? []
-              : [topology.surface.viewFormat],
-        },
-        (frame) => frame.currentTexture,
-      );
-      if (!surface.ok) return surface;
-      const view = graph.importView(
-        surface.value,
-        { label: `${passName}.view`, format: topology.surface.viewFormat },
-        (frame) => frame.view,
-      );
-      if (!view.ok) return view;
-      const added = graph.addRasterPass(passName, {
-        accesses: [{ resource: view.value, usage: 'color-attachment' }],
-        colorAttachments: [
-          {
-            view: view.value,
-            loadOp: 'clear',
-            storeOp: 'store',
-            clearValue: { r: 0, g: 0, b: 0, a: 1 },
-          },
-        ],
-        encode: () => trace.push(passName),
-      });
-      if (!added.ok) return added;
-      return contributeFeatures([]);
-    },
-  };
-}
-
-describe('renderer-owned typed frame graph', () => {
-  it('removes pipeline installations by lease without reviving a disposed predecessor', async () => {
-    const renderer = await constructRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
-    expect((await renderer.ready).ok).toBe(true);
-    renderer.registerPipeline('synthetic::first', pipeline([], { count: 0 }, 'first'));
-    renderer.registerPipeline('synthetic::second', pipeline([], { count: 0 }, 'second'));
-    const first = renderer.installPipeline({
-      kind: 'render-pipeline',
-      pipelineId: 'synthetic::first',
-    });
-    const second = renderer.installPipeline({
-      kind: 'render-pipeline',
-      pipelineId: 'synthetic::second',
-    });
-    expect(first.ok && second.ok).toBe(true);
-    if (!first.ok || !second.ok) return;
-    const world = new World();
-    expect(renderer.attachWorld(world).ok).toBe(true);
-    world.update().unwrap();
-    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
-    expect(renderer.perFramePassNames).toEqual(['second']);
-
-    first.value();
-    world.update().unwrap();
-    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
-    expect(renderer.perFramePassNames).toEqual(['second']);
-
-    second.value();
-    world.update().unwrap();
-    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
-    expect(renderer.perFramePassNames).not.toContain('first');
-    expect(renderer.perFramePassNames).not.toContain('second');
-    renderer.dispose();
-  });
-
-  it('builds once and executes through one submit boundary', async () => {
-    const trace: string[] = [];
-    const builds = { count: 0 };
-    const renderer = await constructRenderer(canvas(), { rhi }, { shaderManifestUrl: manifest });
-    expect((await renderer.ready).ok).toBe(true);
-    renderer.registerPipeline('synthetic::pipeline', pipeline(trace, builds, 'base'));
-    expect(
-      renderer.installPipeline({ kind: 'render-pipeline', pipelineId: 'synthetic::pipeline' }).ok,
-    ).toBe(true);
-    const device = renderer.device as RhiNullDevice;
-    const submit = device.queue.submit.bind(device.queue);
-    let submitCount = 0;
-    device.queue.submit = (buffers) => {
-      submitCount += 1;
-      return submit(buffers);
-    };
-    const world = new World();
-    expect(renderer.attachWorld(world).ok).toBe(true);
-    world.update().unwrap();
-    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
-    expect(renderer.perFramePassNames).toEqual(['base']);
-    expect(trace).toEqual(['base']);
-    expect(builds.count).toBe(1);
-    expect(submitCount).toBe(1);
-
-    trace.length = 0;
-    submitCount = 0;
-    world.update().unwrap();
-    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
-    expect(trace).toEqual(['base']);
-    expect(builds.count).toBe(1);
-    expect(submitCount).toBe(1);
-  });
-
-  it('keeps the last known good graph when replacement compilation fails', async () => {
-    let currentTextureCalls = 0;
-    const countedRhi = {
-      ...rhi,
-      acquireCanvasContext: (): { ok: true; value: RhiCanvasContext } => {
-        const base = new RhiNullCanvasContext();
-        return {
-          ok: true,
-          value: {
-            configure: base.configure.bind(base),
-            unconfigure: base.unconfigure.bind(base),
-            getConfiguration: base.getConfiguration.bind(base),
-            getCurrentTexture: () => {
-              currentTextureCalls += 1;
-              return base.getCurrentTexture();
-            },
-          },
-        };
-      },
-    };
-    const renderer = await constructRenderer(
-      canvas(),
-      { rhi: countedRhi },
-      { shaderManifestUrl: manifest },
-    );
-    expect((await renderer.ready).ok).toBe(true);
-    const trace: string[] = [];
-    renderer.registerPipeline('synthetic::healthy', pipeline(trace, { count: 0 }, 'healthy'));
-    renderer.registerPipeline('synthetic::invalid', {
-      build: ({ graph }) => {
-        const texture = graph.createTexture('uninitialized', {
-          format: 'rgba8unorm',
-          size: 'surface',
-        });
-        if (!texture.ok) return texture;
-        const view = graph.view(texture.value);
-        if (!view.ok) return view;
-        const pass = graph.addRasterPass('future-read', {
-          accesses: [{ resource: view.value, usage: 'sampled-read' }],
-          colorAttachments: [],
-          encode: () => undefined,
-        });
-        return pass.ok ? ok(undefined) : pass;
-      },
-    });
-    expect(
-      renderer.installPipeline({ kind: 'render-pipeline', pipelineId: 'synthetic::healthy' }).ok,
-    ).toBe(true);
-    const world = new World();
-    expect(renderer.attachWorld(world).ok).toBe(true);
-    world.update().unwrap();
-    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
-    expect(renderer.perFramePassNames).toEqual(['healthy']);
-    expect(trace).toEqual(['healthy']);
-    currentTextureCalls = 0;
-    expect(
-      renderer.installPipeline({ kind: 'render-pipeline', pipelineId: 'synthetic::invalid' }).ok,
-    ).toBe(true);
-    world.update().unwrap();
-    expect(renderer.draw([world], { cameraOwner: 0, resourceOwner: 0 }).ok).toBe(true);
-    expect(renderer.perFramePassNames).toEqual(['healthy']);
-    expect(trace).toEqual(['healthy']);
-    expect(currentTextureCalls).toBe(0);
-  });
-});