@forgeax/engine-render 0.1.28 → 0.1.30

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

@@ -0,0 +1,228 @@
+import { type GraphBufferAccess, RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type { Buffer } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-types';
+import { expect, it, vi } from 'vitest';
+import type { RenderFeaturePlanExecutionPass } from '../features/host';
+import type { RenderFeatureGpuBufferRef } from '../features/prepared-gpu-work';
+import {
+  createRenderFeatureProjectionState,
+  projectRenderFeaturePlans,
+  projectRenderFeatureShadows,
+} from '../features/render-graph-contribution';
+import { RenderFeatureRasterGraphProjection } from '../features/render-graph-raster';
+import { createRenderFeatureTarget } from '../features/targets';
+
+it('projects early compute once and preserves scene-dependent work after the opaque boundary', () => {
+  const builder = new RenderGraphBuilder();
+  const added = vi.spyOn(builder, 'addComputePass');
+  const prepareDraws = vi
+    .spyOn(RenderFeatureRasterGraphProjection.prototype, 'prepareShadowDraws')
+    .mockReturnValue(ok({ accesses: [], encode() {} }));
+  try {
+    const target = createRenderFeatureTarget({
+      kind: 'scene-depth',
+      format: 'depth24plus-stencil8',
+      sampleCount: 1,
+    });
+    const shared = {} as Buffer;
+    const independentBuffer = {} as Buffer;
+    const compute = (
+      name: string,
+      buffer: Buffer,
+      sampled = false,
+    ): RenderFeaturePlanExecutionPass => ({
+      featureIdentity: 'ordered',
+      order: 0,
+      name,
+      resolvedGpuCompute: {
+        buffers: [{ name, buffer, size: 16, physicalUsage: 128, access: 'storage-read-write' }],
+        dispatches: [],
+        ...(sampled ? { sampledTargets: [target] } : {}),
+      },
+    });
+    const early = compute('early', shared);
+    const late = compute('late-depth', shared, true);
+    const dependent = compute('late-projection', shared);
+    const independent = compute('independent-emitter', independentBuffer);
+    const shadow: RenderFeaturePlanExecutionPass = {
+      featureIdentity: 'ordered',
+      order: 0,
+      name: 'shadow',
+      shadowCaster: true,
+      graphics: { attachments: { colors: [] }, draws: [] },
+      graphicsState: {} as never,
+      resolvedGraphics: {} as never,
+    };
+    const executions = [
+      {
+        featureIdentity: 'ordered',
+        order: 0,
+        passes: [early, late, dependent, independent, shadow],
+      },
+    ];
+    const state = createRenderFeatureProjectionState();
+    expect(projectRenderFeatureShadows(builder, executions, state).ok).toBe(true);
+    expect(added.mock.calls.map(([name]) => name)).toEqual(['early', 'independent-emitter']);
+    expect([...state.projected]).toEqual([early, independent, shadow]);
+    const texture = builder
+      .createTexture('depth', {
+        format: 'depth24plus-stencil8',
+        size: { width: 16, height: 16 },
+        usage: 20,
+      })
+      .unwrap();
+    const view = builder.view(texture).unwrap();
+    expect(
+      projectRenderFeaturePlans(builder, executions, {
+        state,
+        resolveTarget: () => ({ texture, view }),
+      }).ok,
+    ).toBe(true);
+    expect(added.mock.calls.map(([name]) => name)).toEqual([
+      'early',
+      'independent-emitter',
+      'late-depth',
+      'late-projection',
+    ]);
+    expect(prepareDraws).toHaveBeenCalledOnce();
+  } finally {
+    prepareDraws.mockRestore();
+    added.mockRestore();
+  }
+});
+
+it.each([
+  ['storage-write', 'storage-read', false],
+  ['storage-read', 'storage-write', false],
+  ['storage-write', 'storage-write', false],
+  ['storage-read', 'storage-read', true],
+] as const)('preserves cross-feature %s -> %s hazards', (first, second, early) => {
+  const builder = new RenderGraphBuilder();
+  const buffer = {} as Buffer;
+  const added = vi.spyOn(builder, 'addComputePass');
+  const prepare = vi
+    .spyOn(RenderFeatureRasterGraphProjection.prototype, 'prepareShadowDraws')
+    .mockReturnValue(ok({ accesses: [], encode() {} }));
+  const target = createRenderFeatureTarget({
+    kind: 'scene-depth',
+    format: 'depth24plus-stencil8',
+    sampleCount: 1,
+  });
+  const compute = (
+    name: string,
+    access: GraphBufferAccess,
+    sampled: boolean,
+  ): RenderFeaturePlanExecutionPass => ({
+    featureIdentity: name,
+    order: 0,
+    name,
+    resolvedGpuCompute: {
+      buffers: [{ name, buffer, size: 16, physicalUsage: 128, access }],
+      dispatches: [],
+      sampledTargets: sampled ? [target] : [],
+    },
+  });
+  const shadow: RenderFeaturePlanExecutionPass = {
+    featureIdentity: 'second',
+    order: 0,
+    name: 'shadow',
+    shadowCaster: true,
+    graphics: { attachments: { colors: [] }, draws: [] },
+    graphicsState: {} as never,
+    resolvedGraphics: {} as never,
+  };
+  try {
+    const result = projectRenderFeatureShadows(
+      builder,
+      [
+        { featureIdentity: 'first', order: 0, passes: [compute('first', first, true)] },
+        { featureIdentity: 'second', order: 1, passes: [compute('second', second, false), shadow] },
+      ],
+      createRenderFeatureProjectionState(),
+    );
+    expect(result.ok).toBe(true);
+    expect(added.mock.calls.map(([name]) => name)).toEqual(early ? ['second'] : []);
+  } finally {
+    prepare.mockRestore();
+    added.mockRestore();
+  }
+});
+
+it('does not move writes ahead of prior raster vertex, index or indirect reads', () => {
+  const builder = new RenderGraphBuilder();
+  const added = vi.spyOn(builder, 'addComputePass');
+  const prepare = vi
+    .spyOn(RenderFeatureRasterGraphProjection.prototype, 'prepareShadowDraws')
+    .mockReturnValue(ok({ accesses: [], encode() {} }));
+  const vertex = { kind: 'vertex-data' as const, generation: 1 };
+  const index = { kind: 'index-data' as const, generation: 1 };
+  const indirect = {} as RenderFeatureGpuBufferRef;
+  const buffers = [{} as Buffer, {} as Buffer, {} as Buffer];
+  const raster: RenderFeaturePlanExecutionPass = {
+    featureIdentity: 'raster',
+    order: 0,
+    name: 'raster',
+    graphics: {
+      attachments: { colors: [] },
+      draws: [
+        {
+          kind: 'draw-indexed-indirect',
+          pipeline: { kind: 'pipeline', generation: 1 },
+          bindings: [],
+          vertexData: [{ slot: 0, resource: vertex }],
+          indexData: { resource: index, format: 'uint32' },
+          command: { buffer: indirect },
+        },
+      ],
+    },
+    resolvedGraphics: {
+      generation: 1,
+      resolve: (reference) =>
+        reference === vertex || reference === index
+          ? {
+              kind: reference.kind as 'vertex-data' | 'index-data',
+              reference,
+              handle: buffers[reference === vertex ? 0 : 1] as Buffer,
+              size: 16,
+              physicalUsage: 368,
+            }
+          : undefined,
+      resolveGpuBuffer: () => ({ buffer: buffers[2] as Buffer, size: 16, physicalUsage: 368 }),
+    },
+  };
+  const writes = [...buffers, {} as Buffer].map(
+    (buffer, i): RenderFeaturePlanExecutionPass => ({
+      featureIdentity: 'compute',
+      order: 1,
+      name: `write-${i}`,
+      resolvedGpuCompute: {
+        buffers: [
+          { name: `alias-${i}`, buffer, size: 16, physicalUsage: 368, access: 'storage-write' },
+        ],
+        dispatches: [],
+      },
+    }),
+  );
+  const shadow: RenderFeaturePlanExecutionPass = {
+    featureIdentity: 'shadow',
+    order: 2,
+    name: 'shadow',
+    shadowCaster: true,
+    graphics: { attachments: { colors: [] }, draws: [] },
+    graphicsState: {} as never,
+    resolvedGraphics: {} as never,
+  };
+  try {
+    expect(
+      projectRenderFeatureShadows(
+        builder,
+        [{ featureIdentity: 'mixed', order: 0, passes: [raster, ...writes, shadow] }],
+        createRenderFeatureProjectionState(),
+      ).ok,
+    ).toBe(true);
+    expect(added.mock.calls.map(([name]) => name)).toEqual(['write-3']);
+  } finally {
+    prepare.mockRestore();
+    added.mockRestore();
+  }
+});

package/src/__tests__/render-feature-zero-work.unit.test.ts

@@ -1,7 +1,12 @@
 import { err, ok } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { RenderFeatureStageFailedError } from '../errors/render';
-import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import {
+  acknowledgeRenderFeatureSubmission,
+  createRenderFeatureHost,
+  hasSubmissionSensitiveFeatures,
+  runRenderFeatureFrame,
+} from '../features/host';
 import type { RenderFeature } from '../features/types';
 
 function noWorkFeature(identity: string): RenderFeature<{ readonly empty: true }> {
@@ -21,6 +26,35 @@ function failedFeature(identity: string): RenderFeature<{ readonly empty: true }
 }
 
 describe('render feature zero-work boundaries', () => {
+  it('acknowledges only submitted plans and never repeats an acknowledgment', () => {
+    const submitted: number[] = [];
+    const host = createRenderFeatureHost([
+      {
+        identity: 'synthetic.receipt',
+        extract: (context) => ok(context.frameNumber),
+        plan: () => ok({ resources: [], passes: [] }),
+        onFrameSubmitted: (frame: number) => {
+          submitted.push(frame);
+        },
+      },
+    ]).unwrap();
+    const frame = (frameNumber: number) =>
+      runRenderFeatureFrame(host, {
+        worlds: [],
+        owner: 0,
+        frameNumber,
+        caps: {} as never,
+      });
+    const rejected = frame(1);
+    const accepted = frame(2);
+    expect(submitted).toEqual([]);
+    acknowledgeRenderFeatureSubmission(accepted.plans);
+    acknowledgeRenderFeatureSubmission(accepted.plans);
+    expect(submitted).toEqual([2]);
+    expect(hasSubmissionSensitiveFeatures(accepted.plans)).toBe(true);
+    expect(rejected.plans).toHaveLength(1);
+    host.dispose();
+  });
   it('keeps an empty registry free of work, errors, and proxy noise', () => {
     const host = createRenderFeatureHost([]).unwrap();
     const result = runRenderFeatureFrame(host, {

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

@@ -5,7 +5,7 @@ import { describe, expect, it } from 'vitest';
 describe('Standard PBR fallback graph integration contract', () => {
   it('keeps the fallback output at the canonical BRDF callsite', () => {
     const source = readFileSync(
-      resolve(import.meta.dirname, '../../../shader/src/default-standard-pbr.wgsl'),
+      resolve(import.meta.dirname, '../../../shader/src/standard-surface.wgsl'),
       'utf8',
     );
     expect(source).toContain('sampleIblDiffuse');
@@ -16,7 +16,7 @@ describe('Standard PBR fallback graph integration contract', () => {
 
   it('does not introduce SSR history, trace, or Hi-Z work', () => {
     const source = readFileSync(
-      resolve(import.meta.dirname, '../../../shader/src/default-standard-pbr.wgsl'),
+      resolve(import.meta.dirname, '../../../shader/src/standard-surface.wgsl'),
       'utf8',
     );
     expect(source).not.toMatch(/ssrHistory|rayMarch|hiz|hi-z/i);

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

@@ -0,0 +1,55 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+
+const read = (path: string): string => readFileSync(new URL(path, import.meta.url), 'utf8');
+const count = (source: string, pattern: RegExp): number => source.match(pattern)?.length ?? 0;
+
+const extractRoot = read('../render-system-extract.ts');
+const extractTail = read('../render-system-extract-tail.ts');
+const rendererSystem = read('../render-system.ts');
+const rendererFactory = read('../assembly/factory.ts');
+const webgpuReady = read('../assembly/webgpu-ready.ts');
+const webgpuPbrReady = read('../assembly/webgpu-pbr-ready.ts');
+const gpuDrivenOwner = read('../assembly/gpu-driven-owner.ts');
+const skinPaletteOwner = read('../assembly/skin-palette-owner.ts');
+const productionRaster = read('../gpu-driven/production-raster.ts');
+
+describe('render owner cohesion', () => {
+  it('keeps the MeshRenderer query singular at the extract boundary', () => {
+    expect(count(extractTail, /read: \[MeshRenderer\]/g)).toBe(1);
+    expect(extractTail).toContain('MeshRenderer');
+    expect(extractTail).not.toMatch(/renderableQuery(?:NoMaterial|NoTransform|Full)/);
+  });
+
+  it('keeps GPU-driven frame construction in one assembly owner', () => {
+    expect(count(gpuDrivenOwner, /new GpuDrivenProduction\(/g)).toBe(1);
+    expect(rendererSystem).not.toContain('new GpuDrivenProduction(');
+    expect(rendererSystem).toContain('createGpuDrivenOwner(');
+    expect(count(skinPaletteOwner, /createSkinPaletteAllocator\(/g)).toBe(1);
+    expect(rendererFactory).not.toContain('createSkinPaletteAllocator(');
+  });
+
+  it('keeps production raster free of World and AssetRegistry reads', () => {
+    expect(productionRaster).not.toMatch(/^import[^\n]*\bWorld\b/m);
+    expect(productionRaster).not.toMatch(
+      /AssetRegistry|resolveAssetHandle|assets\.(?:get|lookup|load)/,
+    );
+    expect(productionRaster).toContain('RenderableSnapshot');
+  });
+
+  it('keeps the root seams attached to their single owners', () => {
+    expect(extractRoot).toContain(
+      "export { defaultMaterialSnapshot, extractFrame, extractFrames } from './render-system-extract-tail';",
+    );
+    expect(extractTail).toContain('export function extractFrame');
+    expect(webgpuPbrReady).toContain('buildGpuDrivenPbrReadyModules');
+    expect(webgpuPbrReady).toContain('buildGpuDrivenPbrReadyLayouts');
+    expect(webgpuReady).toContain('buildGpuDrivenPbrReadyModules({');
+    expect(webgpuReady).toContain('buildGpuDrivenPbrReadyLayouts(rhiDevice');
+    expect(webgpuReady).toContain('gpuDrivenPbrPrograms:');
+    expect(webgpuReady).toContain('gpuDrivenPbrPipelineLayout:');
+    expect(rendererSystem).toContain('createGpuDrivenOwner(');
+    expect(productionRaster).not.toContain('ownsAllRenderables');
+    expect(productionRaster).not.toContain('gpuOwnedEntityKeys');
+  });
+});