@forgeax/engine-render 0.1.6 → 0.1.19

package/src/__tests__/renderer-factory-material-contract.unit.test.ts

@@ -1,14 +1,434 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { describe, expect, it } from 'vitest';
+import { RhiError } from '@forgeax/engine-rhi';
+import { describe, expect, it, vi } from 'vitest';
 import {
   allowsUnlitPreparedFallback,
+  normalizeMaterialShaderVariantSet,
   resolveMaterialShaderBindingContract,
+  resolveMaterialShaderVariantSet,
   resolveMaterialShaderVertexInputContract,
+  selectNoColorPbrVariant,
+  selectPipelineLayoutForVariant,
   shouldDeferMissingPreparedMaterialShader,
 } from '../assembly/factory';
+import {
+  buildPipelineForMaterialShader,
+  type PipelineBuilderContext,
+  validateTemporalPipelineContract,
+} from '../pipeline-builder';
+import { userRegionTextureFieldOrder } from '../record/main-pass-material';
+
+const hdrpVariantKey =
+  'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false';
+const urpVariantKey =
+  'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false';
+
+function noColorVariant(definesKey: string, clusterForward: boolean) {
+  return {
+    definesKey,
+    defines: {
+      STORAGE_BUFFER_AVAILABLE: true,
+      VERTEX_COLOR_AVAILABLE: false,
+      CLUSTER_FORWARD_AVAILABLE: clusterForward,
+    },
+    composedWgsl: definesKey,
+  };
+}
+
+function noColorManifest() {
+  return {
+    identifier: 'forgeax::default-standard-pbr',
+    sourcePath: 'default-standard-pbr.wgsl',
+    composedWgsl: 'shader',
+    paramSchema: '{}',
+    variants: [noColorVariant(hdrpVariantKey, true), noColorVariant(urpVariantKey, false)],
+  };
+}
+
+describe('material shader variant identity', () => {
+  it('preserves the distinction between absent, canonical, and explicit requests', () => {
+    const manifest = noColorManifest();
+
+    expect(selectNoColorPbrVariant(manifest, true, undefined)?.definesKey).toBe(urpVariantKey);
+    expect(selectNoColorPbrVariant(manifest, true, '')?.definesKey).toBe(hdrpVariantKey);
+    expect(
+      selectNoColorPbrVariant(manifest, true, 'CLUSTER_FORWARD_AVAILABLE=true')?.definesKey,
+    ).toBe(hdrpVariantKey);
+    expect(
+      selectNoColorPbrVariant(manifest, true, 'CLUSTER_FORWARD_AVAILABLE=false')?.definesKey,
+    ).toBe(urpVariantKey);
+  });
+
+  it('closes the WebGL2 colored PBR axes on the URP variant and layout', () => {
+    const variants = [
+      {
+        defines: {
+          CLUSTER_FORWARD_AVAILABLE: false,
+          STORAGE_BUFFER_AVAILABLE: false,
+          VERTEX_COLOR_AVAILABLE: true,
+        },
+      },
+      {
+        defines: {
+          CLUSTER_FORWARD_AVAILABLE: true,
+          STORAGE_BUFFER_AVAILABLE: true,
+          VERTEX_COLOR_AVAILABLE: true,
+        },
+      },
+    ];
+    const resolved = resolveMaterialShaderVariantSet(
+      'CLUSTER_FORWARD_AVAILABLE=true+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=true',
+      variants,
+      'wgpu-webgl2',
+      false,
+    );
+
+    expect(resolved).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=true',
+    );
+    expect(
+      selectPipelineLayoutForVariant(
+        {
+          pbrPipelineLayout: 'urp' as never,
+          hdrpPbrPipelineLayout: 'hdrp' as never,
+          pbrSkinPipelineLayout: null,
+        },
+        resolved,
+      ),
+    ).toBe('urp');
+  });
+
+  it('does not promote an omitted semantic axis to true', () => {
+    const resolved = resolveMaterialShaderVariantSet(
+      'VERTEX_COLOR_AVAILABLE=true',
+      [
+        {
+          defines: {
+            CLUSTER_FORWARD_AVAILABLE: false,
+            STORAGE_BUFFER_AVAILABLE: false,
+            VERTEX_COLOR_AVAILABLE: true,
+          },
+        },
+      ],
+      'wgpu-webgl2',
+      false,
+    );
+
+    expect(resolved).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=true',
+    );
+  });
+
+  it('keeps the negative skinning axis disabled when a shadow request omits it', () => {
+    const variants = [
+      {
+        defines: {
+          SKINNING_DISABLED: true,
+          STORAGE_BUFFER_AVAILABLE: false,
+        },
+      },
+      {
+        defines: {
+          SKINNING_DISABLED: false,
+          STORAGE_BUFFER_AVAILABLE: false,
+        },
+      },
+    ];
+
+    expect(resolveMaterialShaderVariantSet(undefined, variants, 'wgpu-webgl2', false)).toBe(
+      'SKINNING_DISABLED=true+STORAGE_BUFFER_AVAILABLE=false',
+    );
+    expect(resolveMaterialShaderVariantSet('', variants, 'wgpu-webgl2', false)).toBe(
+      'SKINNING_DISABLED=true+STORAGE_BUFFER_AVAILABLE=false',
+    );
+    expect(
+      resolveMaterialShaderVariantSet(
+        'SKINNING_DISABLED=false+STORAGE_BUFFER_AVAILABLE=false',
+        variants,
+        'wgpu-webgl2',
+        false,
+      ),
+    ).toBe('SKINNING_DISABLED=false+STORAGE_BUFFER_AVAILABLE=false');
+  });
+
+  it('keeps sprite region variants on the explicit empty-key contract', () => {
+    const variants = [
+      {
+        defines: { PER_INSTANCE_REGION: true, STORAGE_BUFFER_AVAILABLE: true },
+      },
+      {
+        defines: { PER_INSTANCE_REGION: false, STORAGE_BUFFER_AVAILABLE: true },
+      },
+    ];
+
+    expect(resolveMaterialShaderVariantSet(undefined, variants, 'webgpu', true)).toBe(
+      'PER_INSTANCE_REGION=false+STORAGE_BUFFER_AVAILABLE=true',
+    );
+    expect(resolveMaterialShaderVariantSet('', variants, 'webgpu', true)).toBe('');
+  });
+
+  it('keeps an explicit empty key colored while omitted and explicit-false stay plain', () => {
+    const variants = [
+      {
+        defines: { STORAGE_BUFFER_AVAILABLE: true, VERTEX_COLOR_AVAILABLE: true },
+      },
+      {
+        defines: { STORAGE_BUFFER_AVAILABLE: true, VERTEX_COLOR_AVAILABLE: false },
+      },
+    ];
+
+    expect(resolveMaterialShaderVariantSet('', variants, 'webgpu', true)).toBe('');
+    expect(resolveMaterialShaderVariantSet(undefined, variants, 'webgpu', true)).toBe(
+      'STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+    );
+    expect(
+      resolveMaterialShaderVariantSet('VERTEX_COLOR_AVAILABLE=false', variants, 'webgpu', true),
+    ).toBe('STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false');
+  });
+
+  it('keeps single-source manifests on the canonical module key', () => {
+    const singleSourceManifest = {
+      identifier: 'forgeax::points-lines',
+      sourcePath: 'points-lines.wgsl',
+      composedWgsl: 'shader',
+      paramSchema: '{}',
+      variants: [],
+    };
+
+    expect(
+      normalizeMaterialShaderVariantSet('VERTEX_COLOR_AVAILABLE=false', singleSourceManifest),
+    ).toBeUndefined();
+  });
+
+  it('preserves variant requests for manifests that actually declare variants', () => {
+    const variantManifest = {
+      identifier: 'forgeax::default-standard-pbr',
+      sourcePath: 'standard-pbr.wgsl',
+      composedWgsl: 'shader',
+      paramSchema: '{}',
+      variants: [
+        {
+          definesKey: 'STORAGE_BUFFER_AVAILABLE=true',
+          defines: { STORAGE_BUFFER_AVAILABLE: true },
+          composedWgsl: 'shader',
+        },
+      ],
+    };
+
+    expect(
+      normalizeMaterialShaderVariantSet('STORAGE_BUFFER_AVAILABLE=true', variantManifest),
+    ).toBe('STORAGE_BUFFER_AVAILABLE=true');
+    expect(normalizeMaterialShaderVariantSet('CUSTOM=true', undefined)).toBe('CUSTOM=true');
+  });
+});
+
+describe('temporal material PSO creation contract', () => {
+  const source = `
+    struct VsIn { @location(0) position: vec3<f32> }
+    @vertex fn vs_temporal(input: VsIn) -> @builtin(position) vec4<f32> {
+      return vec4<f32>(input.position, 1.0);
+    }
+    @fragment fn fs_temporal() -> @location(0) vec4<f32> {
+      return vec4<f32>(1.0);
+    }
+  `;
+  const capabilities = { storageBuffer: false, rgba16floatRenderable: true };
+  const context = {
+    colorFormat: 'rgba16float' as GPUTextureFormat,
+    depthFormat: 'depth24plus-stencil8' as GPUTextureFormat,
+    capabilities,
+  } satisfies Pick<PipelineBuilderContext, 'colorFormat' | 'depthFormat' | 'capabilities'>;
+
+  it('accepts the WebGL2 temporal source/layout/attachment contract', () => {
+    expect(validateTemporalPipelineContract(source, context).ok).toBe(true);
+    const createRenderPipeline = vi.fn((_descriptor: unknown) => ({ ok: true, value: {} }));
+    const result = buildPipelineForMaterialShader(
+      'default-unlit-temporal',
+      { source, paramSchema: [] },
+      {
+        ...context,
+        device: {
+          createRenderPipeline,
+        },
+        shaderModuleFactory: {
+          createShaderModule: () => ({ ok: true, value: {} }),
+        },
+        pipelineLayout: {},
+        vertexBuffers: [],
+        label: 'pbr-pipeline-default-unlit-temporal',
+      } as unknown as PipelineBuilderContext,
+      { depthWriteEnabled: false, depthCompare: 'less-equal' },
+      undefined,
+      'vs_temporal',
+      'fs_temporal',
+      undefined,
+      'temporal',
+    );
+    expect(result.ok).toBe(true);
+    expect(createRenderPipeline).toHaveBeenCalledTimes(1);
+    expect(createRenderPipeline.mock.calls[0]?.[0]).toMatchObject({
+      vertex: { entryPoint: 'vs_temporal' },
+      fragment: { entryPoint: 'fs_temporal', targets: [{ format: 'rgba16float' }] },
+      depthStencil: {
+        format: 'depth24plus-stencil8',
+        depthWriteEnabled: false,
+        depthCompare: 'less-equal',
+      },
+    });
+  });
+
+  it('rejects a storage variant mismatch before caching or device creation', () => {
+    const createRenderPipeline = vi.fn((_descriptor: unknown) => ({ ok: true, value: {} }));
+    const result = buildPipelineForMaterialShader(
+      'default-unlit-temporal',
+      {
+        source: source.replace(
+          'struct VsIn',
+          `@group(2) var<storage> meshes: array<u32>;
+    struct VsIn`,
+        ),
+        paramSchema: [],
+      },
+      {
+        ...context,
+        device: { createRenderPipeline },
+        shaderModuleFactory: { createShaderModule: () => ({ ok: true, value: {} }) },
+        pipelineLayout: {},
+        vertexBuffers: [],
+      } as unknown as PipelineBuilderContext,
+      undefined,
+      undefined,
+      'vs_temporal',
+      'fs_temporal',
+      undefined,
+      'temporal',
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('shader-compile-failed');
+    expect(createRenderPipeline).not.toHaveBeenCalled();
+  });
+
+  it('preserves the underlying pipeline error hint and raw sentinel', () => {
+    const createRenderPipeline = vi.fn((_descriptor: unknown) => ({
+      ok: false,
+      error: new RhiError({
+        code: 'webgpu-runtime-error',
+        expected: 'pipeline validates at creation',
+        hint: 'raw shader validation sentinel',
+      }),
+    }));
+    const result = buildPipelineForMaterialShader(
+      'default-unlit-temporal',
+      { source, paramSchema: [] },
+      {
+        ...context,
+        device: { createRenderPipeline },
+        shaderModuleFactory: { createShaderModule: () => ({ ok: true, value: {} }) },
+        pipelineLayout: {},
+        vertexBuffers: [],
+      } as unknown as PipelineBuilderContext,
+      undefined,
+      undefined,
+      'vs_temporal',
+      'fs_temporal',
+      undefined,
+      'temporal',
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('shader-compile-failed');
+      expect(result.error.hint).toContain('raw shader validation sentinel');
+      expect(result.error.hint).toContain('[RhiError webgpu-runtime-error]');
+    }
+  });
+});
+
+describe('material shader capability variant resolution', () => {
+  it('keeps transmission disabled unless the record path opts in', () => {
+    const variants = [
+      {
+        defines: {
+          CLUSTER_FORWARD_AVAILABLE: false,
+          STORAGE_BUFFER_AVAILABLE: false,
+          TRANSMISSION_AVAILABLE: false,
+          VERTEX_COLOR_AVAILABLE: false,
+        },
+      },
+      {
+        defines: {
+          CLUSTER_FORWARD_AVAILABLE: false,
+          STORAGE_BUFFER_AVAILABLE: false,
+          TRANSMISSION_AVAILABLE: true,
+          VERTEX_COLOR_AVAILABLE: false,
+        },
+      },
+    ];
+    expect(
+      resolveMaterialShaderVariantSet(
+        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+        variants,
+        'wgpu-webgl2',
+        false,
+      ),
+    ).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false+TRANSMISSION_AVAILABLE=false+VERTEX_COLOR_AVAILABLE=false',
+    );
+    expect(
+      resolveMaterialShaderVariantSet(
+        'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+TRANSMISSION_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+        variants,
+        'wgpu-webgl2',
+        false,
+      ),
+    ).toBe(
+      'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=false+TRANSMISSION_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=false',
+    );
+  });
+
+  it('resolves a custom WebGL2 material to its capability-specific boot variant', () => {
+    const variants = [
+      {
+        defines: { STORAGE_BUFFER_AVAILABLE: true, WEBGL2_COMPAT: true },
+      },
+      {
+        defines: { STORAGE_BUFFER_AVAILABLE: false, WEBGL2_COMPAT: true },
+      },
+      {
+        defines: { STORAGE_BUFFER_AVAILABLE: true, WEBGL2_COMPAT: false },
+      },
+      {
+        defines: { STORAGE_BUFFER_AVAILABLE: false, WEBGL2_COMPAT: false },
+      },
+    ];
+    expect(resolveMaterialShaderVariantSet(undefined, variants, 'wgpu-webgl2', false)).toBe(
+      'STORAGE_BUFFER_AVAILABLE=false+WEBGL2_COMPAT=true',
+    );
+  });
+});
 
 describe('material shader binding contract', () => {
+  it('preserves compact authored texture order for custom material schemas', () => {
+    expect(
+      userRegionTextureFieldOrder([
+        { name: 'baseColor', type: 'color' },
+        { name: 'baseColorTexture', type: 'texture2d' },
+        { name: 'normalTexture', type: 'texture2d' },
+      ]),
+    ).toEqual(['baseColorTexture', 'normalTexture']);
+    expect(userRegionTextureFieldOrder([])).toEqual([]);
+    expect(userRegionTextureFieldOrder(undefined)).toEqual([
+      'baseColorTexture',
+      'metallicRoughnessTexture',
+      'normalTexture',
+      'specularTintTexture',
+      'emissiveTexture',
+      'occlusionTexture',
+      'transmissionTexture',
+      'thicknessTexture',
+    ]);
+  });
+
   it('keeps record binding on the cooked projection contract', () => {
     const recordSource = readFileSync(
       resolve(import.meta.dirname, '../record/main-pass-material.ts'),
@@ -77,6 +497,18 @@ describe('material shader binding contract', () => {
   });
 });
 
+describe('material shader color-domain contract', () => {
+  it('routes HDR sprite targets to fs_main_hdr while unorm targets use fs_main', () => {
+    const source = readFileSync(resolve(import.meta.dirname, '../assembly/factory.ts'), 'utf8');
+    expect(source).toContain(
+      "isHdr &&\n      (materialShaderId === 'forgeax::sprite' || materialShaderId === 'forgeax::sprite-lit')",
+    );
+    expect(source).toContain("? 'fs_main_hdr'");
+    expect(source).toContain('colorFormat: isHdr ? HDR_COLOR_ATTACHMENT_FORMAT : ldrColorFormat');
+    expect(source).toContain("entryPoint = 'fs_main_hdr'");
+  });
+});
+
 describe('material shader vertex input contract', () => {
   it('recognizes VsIn-style vertex input structs', () => {
     const source = `