@forgeax/engine-render 0.1.2

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

@@ -0,0 +1,94 @@
+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__/render-feature-visibility-context.test-d.ts

@@ -0,0 +1,38 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { ok } from '@forgeax/engine-types';
+import type {
+  RenderFeature,
+  RenderFeatureExtractContext,
+  RenderFeatureHiddenEntityReport,
+  RenderFeatureWorldVisibilitySnapshot,
+} from '../features/types';
+
+type Frame = { readonly count: number };
+
+function consumeContext(context: RenderFeatureExtractContext): void {
+  const snapshots: readonly RenderFeatureWorldVisibilitySnapshot[] =
+    context.visibilitySnapshots ?? [];
+  const report = context.reportHiddenEntity;
+  const world: World | undefined = snapshots[0]?.world;
+  const entity: EntityHandle = 0 as EntityHandle;
+  if (world !== undefined && report !== undefined) {
+    const hidden: RenderFeatureHiddenEntityReport = { world, entity };
+    report(hidden);
+  }
+}
+
+const feature = {
+  identity: 'synthetic.visibility-context',
+  extract(context) {
+    consumeContext(context);
+    return ok<Frame>({ count: context.worlds.length });
+  },
+  prepare() {
+    return ok(undefined);
+  },
+  contribute() {
+    return ok(undefined);
+  },
+} satisfies RenderFeature<Frame>;
+
+void feature;

package/src/__tests__/render-feature-visibility-context.unit.test.ts

@@ -0,0 +1,38 @@
+import { World } from '@forgeax/engine-ecs';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import type { RenderFeature, RenderFeatureHiddenEntityReport } from '../features/types';
+
+describe('render feature visibility context', () => {
+  it('passes the same batch visibility context to every feature', () => {
+    const world = new World();
+    let receivedSnapshots: unknown;
+    const feature: RenderFeature<{ readonly count: number }> = {
+      identity: 'synthetic.visibility-context',
+      extract: (context) => {
+        receivedSnapshots = context.visibilitySnapshots;
+        context.reportHiddenEntity?.({ world, entity: 7 as never });
+        return ok({ count: context.worlds.length });
+      },
+      prepare: () => ok(undefined),
+      contribute: () => ok(undefined),
+    };
+    const host = createRenderFeatureHost([feature]).unwrap();
+    const snapshots = [{ world, snapshot: {} as never }];
+    const builtIn: RenderFeatureHiddenEntityReport = { world, entity: 7 as never };
+
+    const result = runRenderFeatureFrame(host, {
+      worlds: [world],
+      owner: 0,
+      frameNumber: 1,
+      caps: {} as never,
+      visibilitySnapshots: snapshots,
+      hiddenEntityReports: [builtIn],
+    });
+
+    expect(receivedSnapshots).toBe(snapshots);
+    expect(result.hiddenEntityReports).toHaveLength(1);
+    expect(result.hiddenEntityReports[0]).toEqual(builtIn);
+  });
+});

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

@@ -0,0 +1,82 @@
+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 type { RenderFeature } from '../features/types';
+
+function noWorkFeature(identity: string): RenderFeature<{ readonly empty: true }> {
+  return {
+    identity,
+    extract: () => ok({ empty: true }),
+    prepare: () => ok(undefined),
+    contribute: () => ok(undefined),
+  };
+}
+
+function failedFeature(identity: string): RenderFeature<{ readonly empty: true }> {
+  return {
+    identity,
+    extract: () => err(new RenderFeatureStageFailedError(identity, 0, 'extract', 'next-frame')),
+    prepare: () => ok(undefined),
+    contribute: () => ok(undefined),
+  };
+}
+
+describe('render feature zero-work boundaries', () => {
+  it('keeps an empty registry free of work, errors, and proxy noise', () => {
+    const host = createRenderFeatureHost([]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 11,
+      caps: {} as never,
+    });
+
+    expect(result.events).toEqual([]);
+    expect(result.errors).toEqual([]);
+    expect(result.contributions).toEqual([]);
+  });
+
+  it('keeps empty data and zero-pass features out of the contribution list', () => {
+    const host = createRenderFeatureHost([noWorkFeature('synthetic.empty')]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 12,
+      caps: {} as never,
+    });
+
+    expect(result.errors).toEqual([]);
+    expect(result.contributions).toEqual([]);
+    expect(result.events).toEqual([
+      'synthetic.empty:extract',
+      'synthetic.empty:prepare',
+      'synthetic.empty:contribute',
+    ]);
+  });
+
+  it('does not remove healthy work when one feature fails or is disabled', () => {
+    const host = createRenderFeatureHost([
+      failedFeature('synthetic.failed'),
+      noWorkFeature('synthetic.healthy'),
+      noWorkFeature('synthetic.disabled'),
+    ]).unwrap();
+    host.setStatus('synthetic.disabled', 'disabled');
+
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 13,
+      caps: {} as never,
+    });
+
+    expect(result.errors).toHaveLength(1);
+    expect(result.events).toEqual([
+      'synthetic.failed:extract',
+      'synthetic.healthy:extract',
+      'synthetic.healthy:prepare',
+      'synthetic.healthy:contribute',
+    ]);
+    expect(result.contributions).toEqual([]);
+  });
+});

package/src/__tests__/render-graph-compute-raster-gpu.ts

@@ -0,0 +1,342 @@
+import { type CompiledRenderGraphInfo, RenderGraphBuilder } from '@forgeax/engine-render-graph';
+import type {
+  BindGroupLayout,
+  Buffer,
+  ComputePipeline,
+  RenderPipeline,
+  RhiCommandEncoder,
+  RhiDevice,
+} from '@forgeax/engine-rhi';
+import { createShaderModule, rhi } from '@forgeax/engine-rhi-webgpu';
+
+const BUFFER_USAGE_MAP_READ = 0x0001;
+const BUFFER_USAGE_COPY_DST = 0x0008;
+
+const PREPARE_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<storage, read_write> args: array<u32>;
+@group(0) @binding(1) var<storage, read_write> pingA: array<u32>;
+
+@compute @workgroup_size(1)
+fn prepare() {
+  args[0] = 1u;
+  args[1] = 1u;
+  args[2] = 1u;
+  args[4] = 3u;
+  args[5] = 1u;
+  args[6] = 0u;
+  args[7] = 0u;
+  pingA[0] = 32u;
+}
+`;
+
+const PING_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<storage, read> pingA: array<u32>;
+@group(0) @binding(1) var<storage, read_write> pingB: array<u32>;
+
+@compute @workgroup_size(1)
+fn ping() {
+  pingB[0] = pingA[0] * 2u;
+}
+`;
+
+const SHADE_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<storage, read> pingB: array<u32>;
+@group(0) @binding(1) var outputTexture: texture_storage_2d<rgba8unorm, write>;
+
+@compute @workgroup_size(1)
+fn shade() {
+  textureStore(
+    outputTexture,
+    vec2<i32>(0, 0),
+    vec4<f32>(f32(pingB[0]) / 255.0, 0.5, 0.75, 1.0),
+  );
+}
+`;
+
+const RASTER_WGSL = /* wgsl */ `
+@group(0) @binding(0) var sourceTexture: texture_2d<f32>;
+
+@vertex
+fn vs(@builtin(vertex_index) vertex: u32) -> @builtin(position) vec4<f32> {
+  var positions = array<vec2<f32>, 3>(
+    vec2<f32>(-1.0, -1.0),
+    vec2<f32>(3.0, -1.0),
+    vec2<f32>(-1.0, 3.0),
+  );
+  return vec4<f32>(positions[vertex], 0.0, 1.0);
+}
+
+@fragment
+fn fs() -> @location(0) vec4<f32> {
+  return textureLoad(sourceTexture, vec2<i32>(0, 0), 0);
+}
+`;
+
+interface ComputeResources {
+  readonly layout: BindGroupLayout;
+  readonly pipeline: ComputePipeline;
+}
+
+function bufferBinding(buffer: Buffer) {
+  return { kind: 'buffer' as const, value: { buffer } };
+}
+
+async function computeResources(
+  device: RhiDevice,
+  code: string,
+  entries: Parameters<RhiDevice['createBindGroupLayout']>[0]['entries'],
+  entryPoint: string,
+): Promise<ComputeResources> {
+  const module = (await createShaderModule(device, { code })).unwrap();
+  const layout = device.createBindGroupLayout({ entries }).unwrap();
+  const pipelineLayout = device.createPipelineLayout({ bindGroupLayouts: [layout] }).unwrap();
+  const pipeline = device
+    .createComputePipeline({ layout: pipelineLayout, compute: { module, entryPoint } })
+    .unwrap();
+  return { layout, pipeline };
+}
+
+export interface ComputeRasterEvidence {
+  readonly graph: CompiledRenderGraphInfo;
+  readonly pixel: readonly number[];
+}
+
+export async function runComputeRasterGraph(): Promise<ComputeRasterEvidence> {
+  const adapter = (await rhi.requestAdapter()).unwrap();
+  const device = (await adapter.requestDevice()).unwrap();
+  if (
+    !device.caps.compute ||
+    !device.caps.storageBuffer ||
+    !device.caps.storageTexture ||
+    !device.caps.indirectDrawing
+  ) {
+    throw new Error(`required graph capabilities unavailable: ${JSON.stringify(device.caps)}`);
+  }
+
+  const prepare = await computeResources(
+    device,
+    PREPARE_WGSL,
+    [
+      { binding: 0, visibility: 0x4, buffer: { type: 'storage' } },
+      { binding: 1, visibility: 0x4, buffer: { type: 'storage' } },
+    ],
+    'prepare',
+  );
+  const ping = await computeResources(
+    device,
+    PING_WGSL,
+    [
+      { binding: 0, visibility: 0x4, buffer: { type: 'read-only-storage' } },
+      { binding: 1, visibility: 0x4, buffer: { type: 'storage' } },
+    ],
+    'ping',
+  );
+  const shade = await computeResources(
+    device,
+    SHADE_WGSL,
+    [
+      { binding: 0, visibility: 0x4, buffer: { type: 'read-only-storage' } },
+      {
+        binding: 1,
+        visibility: 0x4,
+        storageTexture: { access: 'write-only', format: 'rgba8unorm', viewDimension: '2d' },
+      },
+    ],
+    'shade',
+  );
+  const rasterModule = (await createShaderModule(device, { code: RASTER_WGSL })).unwrap();
+  const rasterLayout = device
+    .createBindGroupLayout({
+      entries: [
+        { binding: 0, visibility: 0x2, texture: { sampleType: 'float', viewDimension: '2d' } },
+      ],
+    })
+    .unwrap();
+  const rasterPipelineLayout = device
+    .createPipelineLayout({ bindGroupLayouts: [rasterLayout] })
+    .unwrap();
+  const rasterPipeline: RenderPipeline = device
+    .createRenderPipeline({
+      layout: rasterPipelineLayout as never,
+      vertex: { module: rasterModule as never, entryPoint: 'vs', buffers: [] },
+      fragment: {
+        module: rasterModule as never,
+        entryPoint: 'fs',
+        targets: [{ format: 'rgba8unorm' }],
+      },
+      primitive: { topology: 'triangle-list' },
+    })
+    .unwrap();
+
+  const readbackBuffer = device
+    .createBuffer({
+      label: 'compute-raster-readback',
+      size: 256,
+      usage: BUFFER_USAGE_MAP_READ | BUFFER_USAGE_COPY_DST,
+    })
+    .unwrap();
+
+  const graph = new RenderGraphBuilder<{ readonly encoder: RhiCommandEncoder }>();
+  const args = graph.createBuffer('gpu-args', { size: 32 }).unwrap();
+  const pingA = graph.createBuffer('ping-a', { size: 16 }).unwrap();
+  const pingB = graph.createBuffer('ping-b', { size: 16 }).unwrap();
+  const storageTexture = graph
+    .createTexture('storage-texture', { format: 'rgba8unorm', size: { width: 1, height: 1 } })
+    .unwrap();
+  const storageView = graph.view(storageTexture, { label: 'storage-texture.view' }).unwrap();
+  const outputTexture = graph
+    .createTexture('raster-output', { format: 'rgba8unorm', size: { width: 1, height: 1 } })
+    .unwrap();
+  const outputView = graph.view(outputTexture, { label: 'raster-output.view' }).unwrap();
+  const readback = graph
+    .importBuffer(
+      'readback',
+      { size: 256, usage: BUFFER_USAGE_MAP_READ | BUFFER_USAGE_COPY_DST },
+      () => readbackBuffer,
+    )
+    .unwrap();
+
+  graph
+    .addComputePass('prepare-args-and-ping', {
+      accesses: [
+        { resource: args, usage: 'storage-write' },
+        { resource: pingA, usage: 'storage-write' },
+      ],
+      encode: ({ pass, resources }) => {
+        const bindings = device
+          .createBindGroup({
+            layout: prepare.layout,
+            entries: [
+              { binding: 0, resource: bufferBinding(resources.buffer(args).unwrap()) },
+              { binding: 1, resource: bufferBinding(resources.buffer(pingA).unwrap()) },
+            ],
+          })
+          .unwrap();
+        pass.setPipeline(prepare.pipeline);
+        pass.setBindGroup(0, bindings);
+        pass.dispatchWorkgroups(1);
+      },
+    })
+    .unwrap();
+  graph
+    .addComputePass('ping-pong', {
+      accesses: [
+        { resource: args, usage: 'indirect-read' },
+        { resource: pingA, usage: 'storage-read' },
+        { resource: pingB, usage: 'storage-write' },
+      ],
+      encode: ({ pass, resources }) => {
+        const bindings = device
+          .createBindGroup({
+            layout: ping.layout,
+            entries: [
+              { binding: 0, resource: bufferBinding(resources.buffer(pingA).unwrap()) },
+              { binding: 1, resource: bufferBinding(resources.buffer(pingB).unwrap()) },
+            ],
+          })
+          .unwrap();
+        pass.setPipeline(ping.pipeline);
+        pass.setBindGroup(0, bindings);
+        pass.dispatchWorkgroupsIndirect(resources.buffer(args).unwrap(), 0);
+      },
+    })
+    .unwrap();
+  graph
+    .addComputePass('storage-texture', {
+      accesses: [
+        { resource: pingB, usage: 'storage-read' },
+        { resource: storageView, usage: 'storage-write' },
+      ],
+      encode: ({ pass, resources }) => {
+        const bindings = device
+          .createBindGroup({
+            layout: shade.layout,
+            entries: [
+              { binding: 0, resource: bufferBinding(resources.buffer(pingB).unwrap()) },
+              {
+                binding: 1,
+                resource: {
+                  kind: 'textureView',
+                  value: resources.textureView(storageView).unwrap(),
+                },
+              },
+            ],
+          })
+          .unwrap();
+        pass.setPipeline(shade.pipeline);
+        pass.setBindGroup(0, bindings);
+        pass.dispatchWorkgroups(1);
+      },
+    })
+    .unwrap();
+  graph
+    .addRasterPass('indirect-raster', {
+      accesses: [
+        { resource: storageView, usage: 'sampled-read' },
+        { resource: args, usage: 'indirect-read' },
+        { resource: outputView, usage: 'color-attachment' },
+      ],
+      colorAttachments: [
+        {
+          view: outputView,
+          clearValue: { r: 0, g: 0, b: 0, a: 0 },
+          loadOp: 'clear',
+          storeOp: 'store',
+        },
+      ],
+      encode: ({ pass, resources }) => {
+        const bindings = device
+          .createBindGroup({
+            layout: rasterLayout,
+            entries: [
+              {
+                binding: 0,
+                resource: {
+                  kind: 'textureView',
+                  value: resources.textureView(storageView).unwrap(),
+                },
+              },
+            ],
+          })
+          .unwrap();
+        pass.setPipeline(rasterPipeline);
+        pass.setBindGroup(0, bindings);
+        pass.drawIndirect(resources.buffer(args).unwrap(), 16);
+      },
+    })
+    .unwrap();
+  graph
+    .addCopyPass('readback', {
+      accesses: [
+        { resource: outputView, usage: 'copy-src' },
+        { resource: readback, usage: 'copy-dst' },
+      ],
+      encode: ({ encoder, resources }) => {
+        encoder.copyTextureToBuffer(
+          { texture: resources.texture(outputTexture).unwrap() as unknown as GPUTexture },
+          {
+            buffer: resources.buffer(readback).unwrap() as unknown as GPUBuffer,
+            bytesPerRow: 256,
+            rowsPerImage: 1,
+          },
+          { width: 1, height: 1, depthOrArrayLayers: 1 },
+        );
+      },
+    })
+    .unwrap();
+
+  const compiled = graph.compile({ device, surfaceSize: { width: 1, height: 1 } }).unwrap();
+  const encoder = device.createCommandEncoder({ label: 'compute-raster-frame' }).unwrap();
+  compiled.execute({ encoder }).unwrap();
+  device.queue.submit([encoder.finish().unwrap()]).unwrap();
+  await device.queue.onSubmittedWorkDone();
+
+  const mapped = (await readbackBuffer.mapAsync(BUFFER_USAGE_MAP_READ)).unwrap();
+  const range = mapped.getMappedRange().unwrap();
+  const pixel = [...new Uint8Array(range.slice(0, 4))];
+  mapped.unmap();
+  const inspected = compiled.inspect();
+  (await compiled.retire()).unwrap();
+  device.destroyBuffer(readbackBuffer).unwrap();
+  return { graph: inspected, pixel };
+}

package/src/__tests__/render-graph-compute-raster.browser.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { runComputeRasterGraph } from './render-graph-compute-raster-gpu';
+
+describe('RenderGraph compute to indirect raster in Chromium WebGPU', () => {
+  it('preserves the same graph hazards and pixel through the browser path', async () => {
+    const evidence = await runComputeRasterGraph();
+    expect(evidence.graph.passes.map((pass) => pass.name)).toEqual([
+      'prepare-args-and-ping',
+      'ping-pong',
+      'storage-texture',
+      'indirect-raster',
+      'readback',
+    ]);
+    expect(evidence.pixel).toEqual([64, 128, 191, 255]);
+  });
+});

package/src/__tests__/render-graph-compute-raster.dawn.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { runComputeRasterGraph } from './render-graph-compute-raster-gpu';
+
+describe('RenderGraph compute to indirect raster on Dawn', () => {
+  it('consumes compute-generated dispatch and draw args after buffer ping-pong', async () => {
+    const evidence = await runComputeRasterGraph();
+    expect(evidence.graph.passes.map((pass) => pass.kind)).toEqual([
+      'compute',
+      'compute',
+      'compute',
+      'raster',
+      'copy',
+    ]);
+    expect(evidence.graph.passes[1]?.dependencies).toEqual(['prepare-args-and-ping']);
+    expect(evidence.graph.passes[2]?.dependencies).toEqual(['ping-pong']);
+    expect(evidence.graph.passes[3]?.dependencies).toEqual([
+      'prepare-args-and-ping',
+      'storage-texture',
+    ]);
+    expect(evidence.pixel).toEqual([64, 128, 191, 255]);
+  });
+});