@forgeax/engine-render 0.0.0-dev.8d955ade1c79

package/src/__tests__/gpu-scene.dawn.test.ts

@@ -0,0 +1,205 @@
+import { rhi } from '@forgeax/engine-rhi-webgpu';
+import { describe, expect, it } from 'vitest';
+import { GpuScene } from '../gpu-scene';
+import { GPU_SCENE_LAYOUTS, gpuSceneFieldOffset } from '../gpu-scene-schema';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_MAP_READ } from '../gpu-usage';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
+
+const material = {
+  baseColor: new Float32Array([0.25, 0.5, 0.75]),
+  metallic: 0.2,
+  roughness: 0.8,
+  baseColorTexture: 23,
+  materialHandle: 17,
+} as MaterialSnapshot;
+const GPU_MAP_MODE_READ = 0x0001;
+
+function snapshot(entityKey: number, translationX: number): RenderableSnapshot {
+  const world = new Float32Array(16);
+  world[0] = 1;
+  world[5] = 1;
+  world[10] = 1;
+  world[15] = 1;
+  world[12] = translationX;
+  return {
+    assetHandle: 41 + entityKey,
+    transform: { world },
+    localAabb: new Float32Array([-1, -2, -3, 1, 2, 3]),
+    gpuDrivenDraws: [
+      {
+        kind: 'indexed',
+        first: 3,
+        count: 36,
+        baseVertex: -2,
+        materialSlot: 0,
+        topology: 'triangle-list',
+        pipelineClass: 'forgeax::default-unlit',
+        materialResourceClass: 'base-color-texture',
+      },
+    ],
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+  };
+}
+
+describe('GpuScene Dawn residency', () => {
+  it('uploads all five schema-derived tables to real GPU buffers', async () => {
+    const adapter = (await rhi.requestAdapter()).unwrap();
+    const device = (await adapter.requestDevice()).unwrap();
+    const availability = GpuScene.create(device, 2).unwrap();
+    expect(availability.status).toBe('available');
+    if (availability.status !== 'available') return;
+    const projection = new RenderScene();
+    const first = snapshot(7, 3);
+    const firstDraw = first.gpuDrivenDraws?.[0];
+    const secondMaterial = {
+      ...material,
+      baseColor: new Float32Array([0.9, 0.1, 0.2]),
+      materialHandle: 18,
+    } as MaterialSnapshot;
+    if (firstDraw === undefined) throw new Error('GPU draw fixture unavailable');
+    availability.scene
+      .sync(
+        projection.apply([
+          {
+            kind: 'create',
+            snapshot: {
+              ...first,
+              materials: [material, secondMaterial],
+              gpuDrivenDraws: [firstDraw, { ...firstDraw, first: 39, materialSlot: 1 }],
+            },
+          },
+          { kind: 'create', snapshot: snapshot(8, 9) },
+        ]),
+      )
+      .unwrap();
+
+    const sources = {
+      primitive: availability.scene.primitiveBuffer,
+      instance: availability.scene.instanceBuffer,
+      transform: availability.scene.transformBuffer,
+      drawTemplate: availability.scene.drawTemplateBuffer,
+      material: availability.scene.materialBuffer,
+    } as const;
+    const readbacks = Object.fromEntries(
+      Object.entries(sources).map(([name]) => {
+        const layout = GPU_SCENE_LAYOUTS[name as keyof typeof GPU_SCENE_LAYOUTS];
+        return [
+          name,
+          device
+            .createBuffer({
+              label: `gpu-scene-${name}-readback`,
+              size:
+                layout.stride *
+                (name === 'transform' ? 4 : name === 'drawTemplate' || name === 'material' ? 3 : 2),
+              usage: GPU_BUFFER_USAGE_MAP_READ | GPU_BUFFER_USAGE_COPY_DST,
+            })
+            .unwrap(),
+        ];
+      }),
+    ) as Record<keyof typeof sources, import('@forgeax/engine-rhi').Buffer>;
+    const encoder = device.createCommandEncoder({ label: 'gpu-scene-readback' }).unwrap();
+    for (const [name, source] of Object.entries(sources) as Array<
+      [keyof typeof sources, import('@forgeax/engine-rhi').Buffer]
+    >) {
+      encoder.copyBufferToBuffer(
+        source,
+        0,
+        readbacks[name],
+        0,
+        GPU_SCENE_LAYOUTS[name].stride *
+          (name === 'transform' ? 4 : name === 'drawTemplate' || name === 'material' ? 3 : 2),
+      );
+    }
+    device.queue.submit([encoder.finish().unwrap()]).unwrap();
+    await device.queue.onSubmittedWorkDone();
+
+    const views = {} as Record<keyof typeof sources, DataView>;
+    for (const [name, readback] of Object.entries(readbacks) as Array<
+      [keyof typeof sources, import('@forgeax/engine-rhi').Buffer]
+    >) {
+      const mapped = (await readback.mapAsync(GPU_MAP_MODE_READ)).unwrap();
+      views[name] = new DataView(mapped.getMappedRange().unwrap().slice(0));
+      mapped.unmap();
+    }
+
+    expect(
+      views.primitive.getUint32(
+        gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.primitive, 'assetHandle'),
+        true,
+      ),
+    ).toBe(48);
+    expect(
+      views.primitive.getUint32(
+        GPU_SCENE_LAYOUTS.primitive.stride +
+          gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.primitive, 'materialIndex'),
+        true,
+      ),
+    ).toBe(2);
+    expect(
+      views.instance.getUint32(
+        gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.instance, 'primitiveIndex'),
+        true,
+      ),
+    ).toBe(0);
+    expect(
+      views.transform.getFloat32(
+        gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'currentWorld') + 12 * 4,
+        true,
+      ),
+    ).toBe(3);
+    const secondTransformIndex = views.primitive.getUint32(
+      GPU_SCENE_LAYOUTS.primitive.stride +
+        gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.primitive, 'transformIndex'),
+      true,
+    );
+    expect(secondTransformIndex).toBe(2);
+    expect(
+      views.transform.getFloat32(
+        secondTransformIndex * GPU_SCENE_LAYOUTS.transform.stride +
+          gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'previousWorld') +
+          12 * 4,
+        true,
+      ),
+    ).toBe(9);
+    expect(
+      views.drawTemplate.getUint32(
+        gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.drawTemplate, 'indexCount'),
+        true,
+      ),
+    ).toBe(36);
+    expect(
+      views.drawTemplate.getInt32(
+        gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.drawTemplate, 'baseVertex'),
+        true,
+      ),
+    ).toBe(-2);
+    expect(
+      views.drawTemplate.getUint32(
+        GPU_SCENE_LAYOUTS.drawTemplate.stride +
+          gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.drawTemplate, 'materialIndex'),
+        true,
+      ),
+    ).toBe(1);
+    expect(
+      views.material.getFloat32(
+        GPU_SCENE_LAYOUTS.material.stride +
+          gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.material, 'params0'),
+        true,
+      ),
+    ).toBeCloseTo(0.9);
+    expect(
+      views.material.getFloat32(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.material, 'params0'), true),
+    ).toBeCloseTo(0.25);
+    expect(
+      views.material.getUint32(gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.material, 'resource0'), true),
+    ).toBe(23);
+
+    availability.scene.dispose();
+    for (const readback of Object.values(readbacks)) device.destroyBuffer(readback);
+  });
+});

package/src/__tests__/gpu-scene.unit.test.ts

@@ -0,0 +1,147 @@
+import type { Buffer, Result, RhiError } from '@forgeax/engine-rhi';
+import { RhiNullCommandEncoder, RhiNullDevice, RhiNullQueue } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import { GpuScene } from '../gpu-scene';
+import { GPU_SCENE_LAYOUTS, gpuSceneFieldOffset } from '../gpu-scene-schema';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
+
+interface WriteRecord {
+  readonly offset: number;
+  readonly bytes: Uint8Array;
+}
+
+class RecordingQueue extends RhiNullQueue {
+  readonly writes: WriteRecord[] = [];
+
+  override writeBuffer(
+    buffer: Buffer,
+    bufferOffset: number,
+    data: ArrayBufferView | ArrayBuffer,
+    dataOffset?: number,
+    size?: number,
+  ): Result<void, RhiError> {
+    const source =
+      data instanceof ArrayBuffer
+        ? new Uint8Array(data)
+        : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+    const start = dataOffset ?? 0;
+    const length = size ?? source.byteLength - start;
+    this.writes.push({ offset: bufferOffset, bytes: source.slice(start, start + length) });
+    return super.writeBuffer(buffer, bufferOffset, data, dataOffset, size);
+  }
+}
+
+const material = {
+  baseColor: new Float32Array([0.25, 0.5, 0.75]),
+  metallic: 0.2,
+  roughness: 0.8,
+  materialHandle: 17,
+} as MaterialSnapshot;
+
+function snapshot(entityKey: number, translationX = 0): RenderableSnapshot {
+  const world = new Float32Array(16);
+  world[0] = 1;
+  world[5] = 1;
+  world[10] = 1;
+  world[15] = 1;
+  world[12] = translationX;
+  return {
+    assetHandle: 9,
+    transform: { world },
+    localAabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    material,
+    materials: [material],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+  };
+}
+
+function createDevice(queue: RecordingQueue): RhiNullDevice {
+  return new RhiNullDevice(
+    queue,
+    (bookkeeper, device) => new RhiNullCommandEncoder(bookkeeper, device),
+  );
+}
+
+describe('GpuScene', () => {
+  it('uploads only coalesced dirty ranges and performs no upload on no-change', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 4).unwrap();
+    expect(created.status).toBe('available');
+    if (created.status !== 'available') return;
+    const projection = new RenderScene();
+
+    const initial = projection.apply([
+      { kind: 'create', snapshot: snapshot(0) },
+      { kind: 'create', snapshot: snapshot(1) },
+      { kind: 'create', snapshot: snapshot(2) },
+    ]);
+    expect(created.scene.sync(initial).unwrap()).toMatchObject({ ranges: 5, bytes: 1344 });
+    const writesAfterInitial = queue.writes.length;
+
+    created.scene.sync(projection.apply([])).unwrap();
+    expect(queue.writes).toHaveLength(writesAfterInitial);
+
+    const dirty = projection.apply([
+      { kind: 'update-transform', worldId: 0, entityKey: 0, world: snapshot(0, 4).transform.world },
+      { kind: 'update-transform', worldId: 0, entityKey: 2, world: snapshot(2, 8).transform.world },
+    ]);
+    expect(created.scene.sync(dirty).unwrap()).toMatchObject({ ranges: 10 });
+    expect(queue.writes.length).toBeGreaterThan(writesAfterInitial);
+    expect(created.scene.inspect()).toMatchObject({ noChangeFrames: 1 });
+  });
+
+  it('clears removed slots, grows without losing the CPU mirror, and rebuilds a fresh table', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 2).unwrap();
+    if (created.status !== 'available') return;
+    const projection = new RenderScene();
+    created.scene
+      .sync(
+        projection.apply([
+          { kind: 'create', snapshot: snapshot(0) },
+          { kind: 'create', snapshot: snapshot(1) },
+          { kind: 'create', snapshot: snapshot(2) },
+        ]),
+      )
+      .unwrap();
+    expect(created.scene.inspect()).toMatchObject({ capacity: 8, capacityGrows: 1 });
+
+    const beforeRemove = queue.writes.length;
+    created.scene.sync(projection.apply([{ kind: 'remove', worldId: 0, entityKey: 1 }])).unwrap();
+    expect(queue.writes.slice(beforeRemove)).toHaveLength(5);
+    expect(queue.writes.at(-1)?.bytes.every((value) => value === 0)).toBe(true);
+    expect(created.scene.inspect().clearedSlots).toBe(1);
+
+    const rebuilt = GpuScene.create(createDevice(new RecordingQueue()), 1).unwrap();
+    if (rebuilt.status !== 'available') return;
+    expect(rebuilt.scene.rebuild(projection.slotsSnapshot()).unwrap()).toMatchObject({ ranges: 5 });
+    expect(rebuilt.scene.inspect()).toMatchObject({ capacity: 4, fullRebuilds: 1 });
+  });
+
+  it('resets previous transform when a slot generation is recreated', () => {
+    const queue = new RecordingQueue();
+    const created = GpuScene.create(createDevice(queue), 1).unwrap();
+    if (created.status !== 'available') return;
+    const projection = new RenderScene();
+    created.scene.sync(projection.apply([{ kind: 'create', snapshot: snapshot(1, 2) }])).unwrap();
+
+    created.scene
+      .sync(
+        projection.apply([
+          { kind: 'remove', worldId: 0, entityKey: 1 },
+          { kind: 'create', snapshot: snapshot(1, 9) },
+        ]),
+      )
+      .unwrap();
+
+    const transformWrite = queue.writes.at(-3);
+    expect(transformWrite).toBeDefined();
+    if (transformWrite === undefined) return;
+    const previousTranslation =
+      gpuSceneFieldOffset(GPU_SCENE_LAYOUTS.transform, 'previousWorld') + 12 * 4;
+    expect(new DataView(transformWrite.bytes.buffer).getFloat32(previousTranslation, true)).toBe(9);
+  });
+});

package/src/__tests__/ibl/face-uniforms.unit.test.ts

@@ -0,0 +1,46 @@
+import { RhiNullAdapter } from '@forgeax/engine-rhi-null';
+import { describe, expect, it } from 'vitest';
+import {
+  createFaceUniformsBuffer,
+  createPrefilterUniformsBuffer,
+  writeAllFaceUniforms,
+  writeAllPrefilterUniforms,
+  writeFaceUniforms,
+  writePrefilterUniforms,
+} from '../../device/gpu-residency';
+
+async function createDevice() {
+  const adapterResult = await new RhiNullAdapter().requestDevice();
+  if (!adapterResult.ok) throw adapterResult.error;
+  return adapterResult.value;
+}
+
+describe('IBL face uniform RHI contract', () => {
+  it('allocates opaque buffers and writes all dynamic uniform slots', async () => {
+    const device = await createDevice();
+    const faceBuffer = createFaceUniformsBuffer(device);
+    const prefilterBuffer = createPrefilterUniformsBuffer(device);
+
+    expect(faceBuffer.ok).toBe(true);
+    expect(prefilterBuffer.ok).toBe(true);
+    if (!faceBuffer.ok || !prefilterBuffer.ok) return;
+
+    expect(writeAllFaceUniforms(device, faceBuffer.value).ok).toBe(true);
+    expect(writeAllPrefilterUniforms(device, prefilterBuffer.value).ok).toBe(true);
+  });
+
+  it('returns structured RHI errors for invalid uniform coordinates', async () => {
+    const device = await createDevice();
+    const bufferResult = createFaceUniformsBuffer(device);
+    expect(bufferResult.ok).toBe(true);
+    if (!bufferResult.ok) return;
+
+    const badFace = writeFaceUniforms(device, bufferResult.value, 6, new Float32Array(16));
+    const badMatrix = writeFaceUniforms(device, bufferResult.value, 0, new Float32Array(15));
+    const badSubPass = writePrefilterUniforms(device, bufferResult.value, 30, 0.5, 128);
+
+    expect(badFace).toMatchObject({ ok: false, error: { code: 'webgpu-runtime-error' } });
+    expect(badMatrix).toMatchObject({ ok: false, error: { code: 'webgpu-runtime-error' } });
+    expect(badSubPass).toMatchObject({ ok: false, error: { code: 'webgpu-runtime-error' } });
+  });
+});

package/src/__tests__/infinite-grid-no-vertex-probe.unit.test.ts

@@ -0,0 +1,92 @@
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import type { RenderFeaturePlan } from '../features/plan';
+import type { RenderFeature } from '../features/types';
+
+const caps = {
+  backendKind: 'null',
+  compute: true,
+  timestampQuery: false,
+  timestampPeriodNanoseconds: null,
+  indirectDrawing: false,
+  textureCompressionBc: false,
+  textureCompressionEtc2: false,
+  textureCompressionAstc: false,
+  multiDrawIndirect: false,
+  pushConstants: false,
+  textureBindingArray: false,
+  samplerAliasing: true,
+  firstInstanceIndirect: false,
+  storageBuffer: true,
+  storageTexture: true,
+  rgba16floatRenderable: true,
+  rg11b10ufloatRenderable: true,
+  float32Filterable: true,
+  maxColorAttachments: 8,
+} as const;
+
+function noVertexFeature(): RenderFeature<{ readonly drawCount: number }> {
+  return {
+    identity: 'editor.infinite-grid.probe',
+    extract: () => ok({ drawCount: 1 }),
+    plan: () => {
+      const value: RenderFeaturePlan = {
+        resources: [
+          {
+            kind: 'graphics-program',
+            name: 'fullscreen',
+            program: {
+              shader: 'editor.infinite-grid.probe',
+              vertexLayout: 'none',
+              colorFormats: ['rgba8unorm'],
+            },
+          },
+          { kind: 'graphics-bindings', name: 'view', program: 'fullscreen', values: {} },
+        ],
+        passes: [
+          {
+            kind: 'raster',
+            name: 'infinite-grid',
+            colorAttachments: [{ target: 'swapchain', loadOp: 'load', storeOp: 'store' }],
+            draws: [
+              {
+                program: 'fullscreen',
+                bindings: ['view'],
+                vertexData: [],
+                vertexLayout: 'none',
+                draw: { kind: 'draw', vertexCount: 3, instanceCount: 1 },
+              },
+            ],
+          },
+        ],
+      };
+      return ok(value);
+    },
+  };
+}
+
+describe('public no-vertex RenderFeature seam probe', () => {
+  it('accepts the explicit public no-vertex producer contract', () => {
+    const host = createRenderFeatureHost([noVertexFeature()]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [],
+      owner: 0,
+      frameNumber: 1,
+      caps,
+    });
+
+    expect(result.errors).toEqual([]);
+    expect(result.plans).toHaveLength(1);
+    expect(result.plans[0]?.plan.passes[0]).toMatchObject({
+      kind: 'raster',
+      draws: [{ vertexLayout: 'none', vertexData: [], draw: { kind: 'draw' } }],
+    });
+    expect(host.diagnostics()[0]).toMatchObject({
+      identity: 'editor.infinite-grid.probe',
+      status: 'active',
+      latestError: undefined,
+    });
+    expect(result.stageEvents.map((event) => event.stage)).toEqual(['extract', 'plan']);
+  });
+});

package/src/__tests__/injection-kind-owner.test-d.ts

@@ -0,0 +1,14 @@
+import { expectTypeOf, it } from 'vitest';
+
+import { appendInjection, INJECTION_KIND_LENGTHS, type InjectionKind } from '../pbr-pipeline';
+
+it('derives InjectionKind from the public length-map keys', () => {
+  expectTypeOf<InjectionKind>().toEqualTypeOf<keyof typeof INJECTION_KIND_LENGTHS>();
+  expectTypeOf<InjectionKind>().toEqualTypeOf<'shadow' | 'ibl' | 'lightmap'>();
+  expectTypeOf<'unknown'>().not.toExtend<InjectionKind>();
+});
+
+it('keeps the public map assignability and appendInjection narrowing', () => {
+  expectTypeOf(INJECTION_KIND_LENGTHS).toMatchTypeOf<Readonly<Record<InjectionKind, number>>>();
+  expectTypeOf(appendInjection).parameter(1).toEqualTypeOf<InjectionKind>();
+});