@forgeax/engine-render 0.1.28 → 0.1.30

package/src/__tests__/standard-profile-oracle.unit.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, it } from 'vitest';
+import { freezeRenderProfile, validateRenderProfile } from '../assembly/renderer-facade';
+import { AUTO_EXPOSURE_PRESET_V1 } from '../pipeline/standard-output/auto-exposure/preset';
 import {
   DEFAULT_STANDARD_PROFILE,
   STANDARD_LIGHT_COUNTS,
@@ -54,4 +56,51 @@ describe('Standard profile oracle', () => {
       'present',
     ]);
   });
+  it('keeps current-main post-processing defaults in the Standard profile', () => {
+    expect(DEFAULT_STANDARD_PROFILE).toMatchObject({
+      renderPath: 'forward',
+      postStages: [
+        'transparent-blend',
+        'bloom',
+        'output-transform',
+        'fxaa',
+        'post-effect',
+        'present',
+      ],
+    });
+    expect(DEFAULT_STANDARD_PROFILE).not.toHaveProperty('tone');
+    expect(DEFAULT_STANDARD_PROFILE).not.toHaveProperty('antialias');
+    expect(DEFAULT_STANDARD_PROFILE).not.toHaveProperty('sky');
+  });
+
+  it('binds the Standard profile to the versioned auto-exposure oracle preset', () => {
+    expect(AUTO_EXPOSURE_PRESET_V1.version).toBe('auto-exposure-v1');
+    expect(AUTO_EXPOSURE_PRESET_V1.histogramBins).toBe(256);
+  });
+});
+
+describe('SSAO public profile', () => {
+  it('preserves immutable AO parameters through the public profile', () => {
+    const ssao = { radius: 0.8, bias: 0.01, intensity: 1.5, quality: 'low' as const };
+    const profile = { ...DEFAULT_STANDARD_PROFILE, renderPath: 'deferred' as const, ssao };
+    expect(validateRenderProfile(profile)).toBeUndefined();
+    const frozen = freezeRenderProfile(profile);
+    ssao.radius = 2;
+    expect(frozen.ssao).toEqual({ radius: 0.8, bias: 0.01, intensity: 1.5, quality: 'low' });
+    expect(Object.isFrozen(frozen.ssao)).toBe(true);
+  });
+  it('rejects unavailable normals and malformed parameter objects', () => {
+    expect(validateRenderProfile({ ...DEFAULT_STANDARD_PROFILE, ssao: true })).toContain(
+      'deferred',
+    );
+    for (const ssao of [[], null, { quality: 'ultra' }, { radius: Number.NaN }, { other: 1 }]) {
+      expect(
+        validateRenderProfile({
+          ...DEFAULT_STANDARD_PROFILE,
+          renderPath: 'deferred',
+          ssao,
+        } as unknown as StandardProfile),
+      ).toBeTypeOf('string');
+    }
+  });
 });

package/src/__tests__/standard-surface-lighting.unit.test.ts

@@ -0,0 +1,41 @@
+import type { BindGroupEntry, BindGroupLayout } from '@forgeax/engine-rhi';
+import { rhi } from '@forgeax/engine-rhi-null';
+import { expect, it, vi } from 'vitest';
+import {
+  createStandardSurfaceLightingBindGroup,
+  getOrCreateHdrpBuffers,
+  resetHdrpBuffers,
+} from '../hdrp-buffers';
+import type { RenderSystemRuntime } from '../record/render-context';
+
+it('binds the current Standard cluster allocation without a scene mesh or palette', async () => {
+  const adapter = (await rhi.requestAdapter()).unwrap();
+  const device = (await adapter.requestDevice()).unwrap();
+  const fire = vi.fn();
+  const runtime = { device, errorRegistry: { fire } } as unknown as RenderSystemRuntime;
+  const grid = { x: 32, y: 16, z: 32 };
+  const prepared = getOrCreateHdrpBuffers(runtime, grid);
+  if (prepared === null) throw new Error('Standard allocation failed');
+  const entries: BindGroupEntry[][] = [];
+  const create = device.createBindGroup.bind(device);
+  device.createBindGroup = (descriptor) => {
+    entries.push([...descriptor.entries]);
+    return create(descriptor);
+  };
+  expect(
+    createStandardSurfaceLightingBindGroup(runtime, {} as BindGroupLayout, grid),
+  ).not.toBeNull();
+  expect(entries).toHaveLength(1);
+  expect(entries[0]?.map((entry) => entry.binding)).toEqual([3, 4, 5, 6, 7, 8]);
+  expect(entries[0]?.slice(0, 4).map((entry) => entry.resource)).toEqual(
+    [
+      prepared.lightDataBuffer,
+      prepared.clusterGridBuffer,
+      prepared.lightIndexListBuffer,
+      prepared.clusterUniformBuffer,
+    ].map((buffer) => ({ kind: 'buffer', value: { buffer } })),
+  );
+  expect(getOrCreateHdrpBuffers(runtime, grid)).toBe(prepared);
+  expect(fire).not.toHaveBeenCalled();
+  resetHdrpBuffers(runtime);
+});

package/src/__tests__/standard-texture-specialization.dawn.test.ts

@@ -0,0 +1,141 @@
+import { createShaderModuleImmediate, rhi } from '@forgeax/engine-rhi-webgpu';
+import {
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+  STANDARD_TEXTURE_MASK_OVERRIDE,
+  standardTextureMask,
+} from '@forgeax/engine-shader';
+import { expect, it } from 'vitest';
+import { lowerStandardPhysicalBindings } from '../../../shader-compiler/src/material/lower-standard-contract';
+import { GPU_SHADER_STAGE_FRAGMENT } from '../gpu-stage';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_COPY_SRC,
+  GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../gpu-texture-usage';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_MAP_READ } from '../gpu-usage';
+import { buildPipelineForMaterialShader } from '../pipeline-builder';
+
+it('applies all schema-derived texture specialization bits through the real material PSO owner', async () => {
+  const fields = DEFAULT_STANDARD_PBR_PARAM_SCHEMA.filter((entry) => entry.type === 'texture2d');
+  const body = fields
+    .map((field, index) => {
+      const name = field.name[0]?.toUpperCase() + field.name.slice(1);
+      return `if (standardUses${name}()) { result += ${2 ** index}.0 * textureLoad(poison, vec2<i32>(0), 0).r; }`;
+    })
+    .join('\n');
+  // Use the compiler's real shared-entry projection and Render's real PSO
+  // builder. Omitting the fragment overrides turns every absent map on and
+  // makes the first (zero-map) readback fail, independent of image judgment.
+  const source = lowerStandardPhysicalBindings(
+    `
+@group(0) @binding(0) var poison: texture_2d<f32>;
+@vertex fn vs_main(@builtin(vertex_index) index: u32) -> @builtin(position) vec4<f32> {
+  let p = 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>(p[index], 0.0, 1.0);
+}
+@fragment fn fs_main() -> @location(0) vec4<f32> {
+  var result = 0.0;
+  ${body}
+  return vec4<f32>(result, 0.0, 0.0, 1.0);
+}`,
+    DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+    true,
+  );
+  const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+  const input = device
+    .createTexture({
+      size: { width: 1, height: 1 },
+      format: 'rgba8unorm',
+      textureBindingViewDimension: '2d',
+      usage: GPU_TEXTURE_USAGE_COPY_DST | GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+    })
+    .unwrap();
+  const output = device
+    .createTexture({
+      size: { width: 1, height: 1 },
+      format: 'rgba32float',
+      textureBindingViewDimension: '2d',
+      usage: GPU_TEXTURE_USAGE_COPY_SRC | GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+    })
+    .unwrap();
+  const readback = device
+    .createBuffer({ size: 256, usage: GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_MAP_READ })
+    .unwrap();
+  try {
+    device.queue
+      .writeTexture(
+        { texture: input },
+        new Uint8Array([255, 0, 0, 255]),
+        { bytesPerRow: 4 },
+        { width: 1, height: 1 },
+      )
+      .unwrap();
+    const inputView = device.createTextureView(input, {}).unwrap();
+    const outputView = device.createTextureView(output, {}).unwrap();
+    const groupLayout = device
+      .createBindGroupLayout({
+        entries: [
+          {
+            binding: 0,
+            visibility: GPU_SHADER_STAGE_FRAGMENT,
+            texture: { sampleType: 'float', viewDimension: '2d' },
+          },
+        ],
+      })
+      .unwrap();
+    const layout = device.createPipelineLayout({ bindGroupLayouts: [groupLayout] }).unwrap();
+    const group = device
+      .createBindGroup({
+        layout: groupLayout,
+        entries: [{ binding: 0, resource: { kind: 'textureView', value: inputView } }],
+      })
+      .unwrap();
+    for (const mask of [
+      0,
+      ...fields.map((field) => standardTextureMask([field])),
+      standardTextureMask(fields),
+    ]) {
+      const pipeline = buildPipelineForMaterialShader(
+        `texture-mask-${mask}`,
+        { source, paramSchema: [] },
+        {
+          device,
+          shaderModuleFactory: {
+            createShaderModule: (descriptor) => createShaderModuleImmediate(device, descriptor),
+          },
+          pipelineLayout: layout,
+          colorFormat: 'rgba32float',
+          depthFormat: undefined,
+          vertexBuffers: [],
+          fragmentConstants: { [STANDARD_TEXTURE_MASK_OVERRIDE]: mask },
+        },
+        { cullMode: 'none' },
+      ).unwrap();
+      const encoder = device.createCommandEncoder().unwrap();
+      const pass = encoder.beginRenderPass({
+        colorAttachments: [
+          { view: outputView, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
+        ],
+      });
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, group);
+      pass.draw(3);
+      pass.end();
+      encoder.copyTextureToBuffer(
+        { texture: output },
+        { buffer: readback, bytesPerRow: 256, rowsPerImage: 1 },
+        { width: 1, height: 1 },
+      );
+      device.queue.submit([encoder.finish().unwrap()]).unwrap();
+      const mapped = (await readback.mapAsync(GPU_BUFFER_USAGE_MAP_READ)).unwrap();
+      const values = Array.from(new Float32Array(mapped.getMappedRange().unwrap().slice(0, 16)));
+      mapped.unmap();
+      expect(values, `texture mask ${mask}`).toEqual([mask, 0, 0, 1]);
+    }
+  } finally {
+    device.destroyTexture(input).unwrap();
+    device.destroyTexture(output).unwrap();
+    device.destroyBuffer(readback).unwrap();
+  }
+});

package/src/__tests__/surface-adjacent-regressions.integration.test.ts

@@ -1,11 +1,11 @@
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { STANDARD_PBR_ARTIFACT_RECEIPT } from '@forgeax/engine-shader';
 import { describe, expect, it } from 'vitest';
 import {
   projectStandardSurfacePasses,
   type StandardSurfaceProjectionOptions,
 } from '../assembly/material/surface-projection';
-import { GPU_DRIVEN_RIGID_UNLIT_WGSL } from '../gpu-driven/production-raster';
 
 function shaderSource(name: string): string {
   return readFileSync(
@@ -54,7 +54,10 @@ describe('Surface adjacent regressions', () => {
     const skinned = shaderSource('default-standard-pbr-skin.wgsl');
     expect(skinned).toContain('skinIndex');
     expect(skinned).toContain('skinWeight');
-    expect(GPU_DRIVEN_RIGID_UNLIT_WGSL).toContain('@builtin(instance_index)');
-    expect(GPU_DRIVEN_RIGID_UNLIT_WGSL).not.toContain('surface_v1');
+    expect(STANDARD_PBR_ARTIFACT_RECEIPT.directEntry).toBe('vs_main');
+    expect(STANDARD_PBR_ARTIFACT_RECEIPT.sceneIndexEntry).toBe('vs_scene_index');
+    expect(STANDARD_PBR_ARTIFACT_RECEIPT.resourceSlots.every((slot) => slot.group === 1)).toBe(
+      true,
+    );
   });
 });

package/src/__tests__/taa-coverage-edge.dawn.test.ts

@@ -0,0 +1,199 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { Texture } from '@forgeax/engine-rhi';
+import { createShaderModuleImmediate, rhi } from '@forgeax/engine-rhi-webgpu';
+import { expect, it } from 'vitest';
+import { GPU_SHADER_STAGE_COMPUTE } from '../gpu-stage';
+import {
+  GPU_TEXTURE_USAGE_COPY_DST,
+  GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+} from '../gpu-texture-usage';
+import {
+  GPU_BUFFER_USAGE_COPY_DST,
+  GPU_BUFFER_USAGE_COPY_SRC,
+  GPU_BUFFER_USAGE_MAP_READ,
+  GPU_BUFFER_USAGE_STORAGE,
+  GPU_BUFFER_USAGE_UNIFORM,
+} from '../gpu-usage';
+
+// Invoke the complete production resolve on a real GPU. Its input contains
+// both colors of a subpixel edge, so the history remains inside color bounds.
+async function resolveCoverage(source: string, edge: boolean) {
+  const device = (await (await rhi.requestAdapter()).unwrap().requestDevice()).unwrap();
+  const textures: Texture[] = [];
+  const upload = (values: number[]) => {
+    const texture = device
+      .createTexture({
+        size: { width: 3, height: 3, depthOrArrayLayers: 1 },
+        format: 'rgba16float',
+        textureBindingViewDimension: '2d',
+        usage: GPU_TEXTURE_USAGE_COPY_DST | GPU_TEXTURE_USAGE_TEXTURE_BINDING,
+      })
+      .unwrap();
+    textures.push(texture);
+    device.queue
+      .writeTexture(
+        { texture },
+        new Uint16Array(values),
+        { bytesPerRow: 24, rowsPerImage: 3 },
+        { width: 3, height: 3, depthOrArrayLayers: 1 },
+      )
+      .unwrap();
+    return { texture, view: device.createTextureView(texture, {}).unwrap() };
+  };
+  const repeat = (value: number[]) => Array.from({ length: 9 }, () => value).flat();
+  const colorValues = repeat([0x3800, 0x3800, 0x3800, 0x3c00]);
+  colorValues.splice(0, 4, 0, 0, 0, 0x3c00);
+  colorValues.splice(32, 4, 0x3c00, 0x3c00, 0x3c00, 0x3c00);
+  const color = upload(colorValues);
+  const history = upload(repeat([0x3400, 0x3400, 0x3400, 0x3c00]));
+  const currentTemporal = upload(repeat([0, 0, 0x4000, 0]));
+  const historyTemporal = upload(repeat([0, 0, 0xbc00, 0x3c00]));
+  const age = upload(repeat([0, 0, 0, 0]));
+  const sampler = device.createSampler({ magFilter: 'nearest', minFilter: 'nearest' }).unwrap();
+  const params = device
+    .createBuffer({ size: 32, usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST })
+    .unwrap();
+  const output = device
+    .createBuffer({ size: 48, usage: GPU_BUFFER_USAGE_STORAGE | GPU_BUFFER_USAGE_COPY_SRC })
+    .unwrap();
+  const readback = device
+    .createBuffer({ size: 48, usage: GPU_BUFFER_USAGE_COPY_DST | GPU_BUFFER_USAGE_MAP_READ })
+    .unwrap();
+  try {
+    const module = createShaderModuleImmediate(device, {
+      code: `${source}
+@group(0) @binding(0) var<storage, read_write> probeResult : array<vec4<f32>>;
+@compute @workgroup_size(1) fn probe_coverage() {
+  let result = fs_taa_resolve(FullscreenOutput(vec4<f32>(1.5, 1.5, 0.0, 1.0), vec2<f32>(0.5)));
+  probeResult[0] = result.color;
+  probeResult[1] = result.temporal;
+  probeResult[2] = vec4<f32>(result.stability);
+}`,
+    }).unwrap();
+    const outputLayout = device
+      .createBindGroupLayout({
+        entries: [
+          { binding: 0, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'storage' } },
+        ],
+      })
+      .unwrap();
+    const inputLayout = device
+      .createBindGroupLayout({
+        entries: [
+          ...[0, 2, 4, 6, 9, 10].map((binding) => ({
+            binding,
+            visibility: GPU_SHADER_STAGE_COMPUTE,
+            texture: { sampleType: 'float' as const, viewDimension: '2d' as const },
+          })),
+          ...[1, 3, 5, 7].map((binding) => ({
+            binding,
+            visibility: GPU_SHADER_STAGE_COMPUTE,
+            sampler: { type: 'filtering' as const },
+          })),
+          { binding: 8, visibility: GPU_SHADER_STAGE_COMPUTE, buffer: { type: 'uniform' } },
+          {
+            binding: 11,
+            visibility: GPU_SHADER_STAGE_COMPUTE,
+            texture: { sampleType: 'unfilterable-float' as const, viewDimension: '2d' as const },
+          },
+        ],
+      })
+      .unwrap();
+    const pipeline = device
+      .createComputePipeline({
+        layout: device
+          .createPipelineLayout({ bindGroupLayouts: [outputLayout, inputLayout] })
+          .unwrap(),
+        compute: { module, entryPoint: 'probe_coverage' },
+      })
+      .unwrap();
+    const outputGroup = device
+      .createBindGroup({
+        layout: outputLayout,
+        entries: [{ binding: 0, resource: { kind: 'buffer', value: { buffer: output } } }],
+      })
+      .unwrap();
+    const inputGroup = device
+      .createBindGroup({
+        layout: inputLayout,
+        entries: [
+          ...[color, history, historyTemporal, currentTemporal].map((surface, i) => ({
+            binding: i * 2,
+            resource: { kind: 'textureView' as const, value: surface.view },
+          })),
+          ...[1, 3, 5, 7].map((binding) => ({
+            binding,
+            resource: { kind: 'sampler' as const, value: sampler },
+          })),
+          { binding: 8, resource: { kind: 'buffer', value: { buffer: params } } },
+          { binding: 9, resource: { kind: 'textureView', value: age.view } },
+          { binding: 10, resource: { kind: 'textureView', value: age.view } },
+          { binding: 11, resource: { kind: 'textureView', value: currentTemporal.view } },
+        ],
+      })
+      .unwrap();
+    const results = [];
+    for (const mode of ['stationary', 'reactive', 'moving', 'reset', 'absent'] as const) {
+      const temporal = repeat([
+        mode === 'moving' ? 0x3000 : 0,
+        0,
+        mode === 'absent' ? 0xbc00 : 0x4000,
+        mode === 'reactive' ? 0x3c00 : 0,
+      ]);
+      if (edge) temporal.splice(0, 4, 0, 0, 0xbc00, 0x3c00);
+      device.queue
+        .writeTexture(
+          { texture: currentTemporal.texture },
+          new Uint16Array(temporal),
+          { bytesPerRow: 24, rowsPerImage: 3 },
+          { width: 3, height: 3, depthOrArrayLayers: 1 },
+        )
+        .unwrap();
+      device.queue
+        .writeBuffer(params, 0, new Uint32Array([0, 0, mode === 'reset' ? 0 : 1, 200, 0, 0, 0, 0]))
+        .unwrap();
+      const encoder = device.createCommandEncoder().unwrap();
+      const pass = encoder.beginComputePass();
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, outputGroup);
+      pass.setBindGroup(1, inputGroup);
+      pass.dispatchWorkgroups(1, 1, 1);
+      pass.end();
+      encoder.copyBufferToBuffer(output, 0, readback, 0, 48);
+      device.queue.submit([encoder.finish().unwrap()]).unwrap();
+      const mapping = (await readback.mapAsync(GPU_BUFFER_USAGE_MAP_READ)).unwrap();
+      results.push([...new Float32Array(mapping.getMappedRange().unwrap().slice(0))]);
+      mapping.unmap();
+    }
+    return results;
+  } finally {
+    for (const texture of textures) device.destroyTexture(texture).unwrap();
+    for (const buffer of [params, output, readback]) device.destroyBuffer(buffer).unwrap();
+  }
+}
+
+it('accumulates mixed coverage while preserving uniform disocclusion and fast-motion/reactive/reset guards', async () => {
+  const source = readFileSync(resolve('packages/shader/src/taa-resolve.wgsl'), 'utf8').replace(
+    /^#define_import_path.*$/gm,
+    '',
+  );
+  const edge = await resolveCoverage(source, true);
+  const stationary = edge[0];
+  if (stationary === undefined) throw new Error('Missing stationary coverage sample');
+  // Karis blend of current 0.5 and history 0.25 with weight 0.95.
+  expect(stationary[0]).toBeCloseTo(
+    (0.5 * (0.05 / 1.5) + 0.25 * (0.95 / 1.25)) / (0.05 / 1.5 + 0.95 / 1.25),
+    3,
+  );
+  expect(stationary[8]).toBeCloseTo(1 / 255, 7);
+  for (const result of edge.slice(1)) {
+    expect(result[0]).toBe(0.5);
+    expect(result[8]).toBe(0);
+  }
+  const uniform = await resolveCoverage(source, false);
+  for (const result of uniform) {
+    expect(result[0]).toBe(0.5);
+    expect(result[8]).toBe(0);
+  }
+});