@forgeax/engine-shader 0.1.6 → 0.1.19

package/src/__tests__/shader.unit.test.ts

@@ -16,6 +16,7 @@
 // Paradigm: each block-scoped describe('<source-filename>.test.ts', ...) preserves
 // source as ancestorTitles[0]. Top-level imports merged + deduped.
 
+import { readFileSync } from 'node:fs';
 import type { Result, RhiError, ShaderModule } from '@forgeax/engine-rhi';
 import { beforeAll, describe, expect, it } from 'vitest';
 import type { ShaderError } from '../errors.js';
@@ -31,6 +32,19 @@ import {
   ShaderRegistry,
 } from '../ShaderRegistry.js';
 
+{
+  const sceneTemporalSource = readFileSync(
+    new URL('../scene-temporal.wgsl', import.meta.url),
+    'utf8',
+  );
+  describe('scene-temporal accessor ABI', () => {
+    it('keeps the public shader module free of compiler and backend policy imports', () => {
+      expect(sceneTemporalSource).toContain('forgeax_scene_temporal');
+      expect(sceneTemporalSource).not.toMatch(/naga|shader-compiler|engine-rhi/i);
+    });
+  });
+}
+
 {
   // --- from fullscreen-triangle.test.ts ---
   // @forgeax/engine-shader/__tests__/fullscreen-triangle.test.ts -
@@ -179,7 +193,7 @@ import {
     });
   });
 
-  describe('fxaa.wgsl SSOT gate (AC-05)', () => {
+  describe('fxaa.wgsl display-encoded SSOT gate (AC-05)', () => {
     it('does NOT define fullscreen_triangle (SSOT is in common.wgsl)', () => {
       expect(fxaaSource).not.toMatch(/fn fullscreen_triangle/);
     });
@@ -191,6 +205,17 @@ import {
     it('imports forgeax_view::common::FullscreenOutput', () => {
       expect(fxaaSource).toContain('#import forgeax_view::common::FullscreenOutput');
     });
+
+    it('declares display-encoded input/output without an OETF owner', () => {
+      expect(fxaaSource).toContain('display-encoded');
+      expect(fxaaSource).not.toContain('linearLdrColorDomain');
+      expect(fxaaSource).not.toContain('linearToSrgbOetf');
+    });
+
+    it('returns encoded colors directly from early and final paths', () => {
+      expect(fxaaSource).toMatch(/return vec4<f32>\(centerColor, 1\.0\);/);
+      expect(fxaaSource).toMatch(/return vec4<f32>\(finalColor, 1\.0\);/);
+    });
   });
 
   describe('fxaa.wgsl bindings', () => {
@@ -779,6 +804,7 @@ import {
         '#pragma variant_axis STORAGE_BUFFER_AVAILABLE',
         '#pragma variant_axis CLUSTER_FORWARD_AVAILABLE',
         '#pragma variant_axis VERTEX_COLOR_AVAILABLE',
+        '#pragma variant_axis TRANSMISSION_AVAILABLE',
       ]);
     });
 
@@ -923,12 +949,19 @@ import {
     'clearcoatRoughness',
     'specularTint',
     'normalScale',
+    'transmission',
+    'ior',
+    'thickness',
+    'attenuationColor',
+    'attenuationDistance',
     'baseColorTexture',
     'metallicRoughnessTexture',
     'normalTexture',
     'specularTintTexture',
     'emissiveTexture',
     'occlusionTexture',
+    'transmissionTexture',
+    'thicknessTexture',
   ] as const;
 
   const STUB_WGSL = '// stub composed pbr-skin wgsl\n';
@@ -987,7 +1020,7 @@ import {
       const registry = makeMockRegistry();
       registerDefaultStandardPbrSkin(registry, STUB_WGSL, STORAGE_CAPS);
       const entry = lookup(registry);
-      expect(entry.paramSchema).toHaveLength(21);
+      expect(entry.paramSchema).toHaveLength(28);
     });
 
     it('paramSchema names match default-standard-pbr schema field-for-field', () => {
@@ -1020,7 +1053,12 @@ import {
         'f32',
         'f32',
         'f32',
-        // specular tint and its texture map.
+        // specular tint, transmission, and attenuation controls.
+        'vec3',
+        'f32',
+        'f32',
+        'f32',
+        'f32',
         'vec3',
         'f32',
         'texture2d',
@@ -1029,6 +1067,8 @@ import {
         'texture2d',
         'texture2d',
         'texture2d',
+        'texture2d',
+        'texture2d',
       ]);
     });
   });

package/src/__tests__/sprite-variants.unit.test.ts

@@ -117,6 +117,7 @@ describe('w6 (b) -- pbr / unlit / sprite-adjacent shaders DO NOT pick up PER_INS
       '#pragma variant_axis STORAGE_BUFFER_AVAILABLE',
       '#pragma variant_axis CLUSTER_FORWARD_AVAILABLE',
       '#pragma variant_axis VERTEX_COLOR_AVAILABLE',
+      '#pragma variant_axis TRANSMISSION_AVAILABLE',
     ]);
   });
 
@@ -207,3 +208,21 @@ describe('w6 (d) -- MAX_UNIFORM_INSTANCES=128 stays unchanged under the new axis
     expect(src).toMatch(/MAX_UNIFORM_INSTANCES\s*=\s*128/);
   });
 });
+
+describe('HDR/display fragment contract', () => {
+  for (const file of ['sprite.wgsl', 'sprite-lit.wgsl'] as const) {
+    it(`${file} keeps LDR OETF in fs_main and HDR output linear`, () => {
+      const src = stripComments(readWgsl(file));
+      const ldrStart = src.indexOf('fn fs_main(');
+      const hdrStart = src.indexOf('fn fs_main_hdr(');
+      expect(ldrStart).toBeGreaterThanOrEqual(0);
+      expect(hdrStart).toBeGreaterThan(ldrStart);
+
+      const ldrBody = src.slice(ldrStart, hdrStart);
+      const hdrBody = src.slice(hdrStart);
+      expect(ldrBody).toContain('linear_to_srgb(');
+      expect(hdrBody).not.toContain('linear_to_srgb(');
+      expect(hdrBody).toContain('return vec4<f32>');
+    });
+  }
+});

package/src/__tests__/taa-resolve.unit.test.ts

@@ -3,24 +3,29 @@ import { resolve } from 'node:path';
 import { describe, expect, it } from 'vitest';
 
 const source = readFileSync(resolve(import.meta.dirname, '../taa-resolve.wgsl'), 'utf8');
+const pbrTemporal = readFileSync(resolve(import.meta.dirname, '../pbr-temporal.wgsl'), 'utf8');
+const sceneTemporal = readFileSync(resolve(import.meta.dirname, '../scene-temporal.wgsl'), 'utf8');
 
 describe('taa-resolve.wgsl', () => {
   it('keeps the fixed packed temporal and two-attachment ABI', () => {
     expect(source).toContain('struct TaaResolveParams');
     expect(source).toContain('@location(0) color');
     expect(source).toContain('@location(1) temporal');
-    expect(source).toContain('output.temporal = temporal');
+    expect(source).toContain('return TaaResolveOutput(');
+    expect(source).toContain('temporal,');
     expect(source).toContain('current.a');
+    expect(source).toContain('1.0 - clamp(temporal.w');
+    expect(source).not.toContain('1.0 - clamp(current.a');
   });
 
   it('contains every v1 rejection and adaptive weighting term', () => {
-    expect(source).toContain('uv + params.currentJitterUv');
+    expect(source).toContain('in.uv + params.currentJitterUv');
     expect(source).toContain('in.uv - temporal.xy');
     expect(source).toContain('closestCurrentTemporal(pixel, dimensions)');
     expect(source).toContain('historyInBounds');
     expect(source).toContain('depthDelta > depthThreshold');
     expect(source).toContain('neighborhoodSquareMean');
-    expect(source).toContain('clamp(rgbToYCoCg(sampledHistory.rgb), clipMin, clipMax)');
+    expect(source).toContain('clamp(rgbToYCoCg(history.rgb), clipMin, clipMax)');
     expect(source).toContain('reactiveFactor');
     expect(source).toContain('velocityFactor');
     expect(source).toContain('depthFactor');
@@ -28,5 +33,72 @@ describe('taa-resolve.wgsl', () => {
     expect(source).toContain('mix(0.88, 0.97, lumaFactor)');
     expect(source).toContain('params.temporalFrameIndex < 8u');
     expect(source).toContain('progressiveWeight');
+    expect(source).toContain('let dimensions = vec2<i32>(textureDimensions(currentColor, 0));');
+    expect(source).toContain('closestCurrentTemporal(pixel, dimensions)');
+    expect(source).toContain('vec2<f32>(dimensions)');
+  });
+
+  it('compiles the PBR temporal seam with coverage-aware reactive output', async () => {
+    const compilerPath = resolve(import.meta.dirname, '../../../shader-compiler/dist/index.mjs');
+    const { compileShader } = await import(/* @vite-ignore */ compilerPath);
+    const common = `
+fn sampleMaterialTexture(
+  texture : texture_2d<f32>,
+  textureSampler : sampler,
+  uv : vec2<f32>,
+  uvScale : vec2<f32>,
+) -> vec4<f32> {
+  return textureSample(texture, textureSampler, uv * uvScale);
+}
+
+`;
+    const sceneTemporalBody = sceneTemporal
+      .replace(/^#define_import_path.*$/gm, '')
+      .replace(/^#import.*$/gm, '');
+    const entry = `${common}
+${sceneTemporalBody}
+${pbrTemporal.replace(/^#define_import_path.*$/gm, '').replace(/^#import.*$/gm, '')}
+@group(0) @binding(0) var colorTexture : texture_2d<f32>;
+@group(0) @binding(1) var colorSampler : sampler;
+@fragment
+fn fs_temporal_probe() -> @location(0) vec4<f32> {
+  return projectPbrSceneTemporal(
+    0.75, 0.5, colorTexture, colorSampler,
+    vec4<f32>(0.0, 0.0, 1.0, 1.0), vec4<f32>(0.0),
+    vec4<f32>(0.0, 0.0, 1.0, 1.0), vec4<f32>(0.0),
+    vec4<f32>(0.0, 0.0, 0.0, 0.0), 0.0,
+    vec2<f32>(0.5), vec2<f32>(0.5), vec2<f32>(0.5), vec2<f32>(0.5),
+    vec2<f32>(0.5), vec2<f32>(0.5), vec2<f32>(0.5), vec2<f32>(0.5),
+  );
+}
+`;
+    const compiled = await compileShader(entry, {
+      id: 'test::pbr-temporal-reactive',
+      defines: { PER_INSTANCE_REGION: false, STORAGE_BUFFER_AVAILABLE: true },
+    });
+    expect(compiled.ok, compiled.ok ? undefined : String(compiled.error)).toBe(true);
+    if (!compiled.ok) return;
+    expect(compiled.value.wgsl).toContain('resolvePbrTemporalReactive');
+    expect(compiled.value.wgsl).toContain('max(clamp(reactive');
+    const discardIndex = pbrTemporal.indexOf('discard;');
+    const reactiveIndex = pbrTemporal.indexOf('let reactiveCoverage');
+    expect(discardIndex).toBeGreaterThanOrEqual(0);
+    expect(discardIndex).toBeLessThan(reactiveIndex);
+  });
+
+  it('rejects a dev-only forced-reactive-zero falsifier', () => {
+    const reactiveCoverageLine =
+      'let reactiveCoverage = resolvePbrTemporalReactive(reactive, baseColorAlpha, baseSample.a);';
+    const falsified = pbrTemporal.replace(reactiveCoverageLine, 'let reactiveCoverage = 0.0;');
+    expect(() => {
+      expect(falsified).toContain(reactiveCoverageLine);
+      expect(falsified).toContain('let reactiveCoverage = 0.0;');
+    }).toThrow();
+  });
+
+  it('keeps the reactive coverage contract explicit', () => {
+    expect(pbrTemporal).toContain('resolvePbrTemporalReactive');
+    expect(pbrTemporal).toContain('coverageReactive');
+    expect(pbrTemporal).not.toContain('return packSceneTemporal(currentClip, previousClip, 0.0)');
   });
 });

package/src/__tests__/transmission-thickness-scale.unit.test.ts

@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const shader = readFileSync(resolve(import.meta.dirname, '../default-standard-pbr.wgsl'), 'utf8');
+
+describe('standard transmission thickness scale contract', () => {
+  it('converts local authored thickness through the combined local-to-world basis', () => {
+    expect(shader).toContain('let localToWorld = entityWorld * instanceLocal;');
+    expect(shader).toContain(
+      'let localToWorld = meshes[0].worldFromLocal * instances[in.instanceIdx].localFromInstance;',
+    );
+    expect(shader).toContain('let worldToLocal0 = vec3<f32>(');
+    expect(shader).toContain('let worldRefractedDirection =');
+    expect(shader).toMatch(
+      /finiteScalar\(material\.thickness, 0\.0\) \* length\(worldRefractedDirection\) \*\s+finiteScalar\(thicknessSample, 1\.0\)/,
+    );
+  });
+});

package/src/common.wgsl

@@ -24,6 +24,9 @@ fn sampleMaterialTexture(
 }
 
 // Shared linear-LDR -> display-sRGB OETF for raw swap-chain storage writes.
+// The high branch deliberately locks Three.js r184's reference literal
+// (`0.41666`) instead of spelling the mathematically exact `1.0 / 2.4`.
+// That literal is part of the byte-level parity contract at 8-bit boundaries.
 // sRGB texture views perform this conversion on attachment writes, but the
 // native output and FXAA passes intentionally target the non-sRGB storage view.
 fn linearToSrgbOetf(color : vec3<f32>) -> vec3<f32> {
@@ -278,6 +281,33 @@ struct SpotLightsArray {
 };
 
 @group(0) @binding(0) var<uniform> view : View;
+
+// Shared screen-space ray reconstruction for scene Fog producers. Keeping the
+// inverse-view and projection branch here prevents each producer from growing
+// a second Fog formula or drifting from the View ABI.
+fn fogWorldPoint(ndc : vec3<f32>) -> vec3<f32> {
+  let homogeneous = view.inverseViewProj * vec4<f32>(ndc, 1.0);
+  let divisor = select(1.0, homogeneous.w, abs(homogeneous.w) > 0.000001);
+  return homogeneous.xyz / divisor;
+}
+
+fn fogRayFromNdc(ndc : vec3<f32>) -> FogRay {
+  let worldPosition = fogWorldPoint(ndc);
+  let nearPosition = fogWorldPoint(vec3<f32>(ndc.xy, 0.0));
+  let farPosition = fogWorldPoint(vec3<f32>(ndc.xy, 1.0));
+  let perspective = view.temporalProjection.z < 0.5;
+  let perspectiveVector = worldPosition - view.cameraPos;
+  let orthographicVector = farPosition - nearPosition;
+  let direction = normalize(select(orthographicVector, perspectiveVector, perspective));
+  let origin = select(nearPosition, view.cameraPos, perspective);
+  let rayDistance = select(
+    max(dot(worldPosition - nearPosition, direction), 0.0),
+    length(perspectiveVector),
+    perspective,
+  );
+  return FogRay(origin, direction, rayDistance);
+}
+
 #if STORAGE_BUFFER_AVAILABLE == true
 @group(0) @binding(1) var<storage, read> pointLightsBuffer : PointLightsArray;
 @group(0) @binding(2) var<storage, read> spotLightsBuffer  : SpotLightsArray;
@@ -445,36 +475,6 @@ struct InstanceData {
 #endif
 };
 
-fn sceneTemporalUv(clip : vec4<f32>) -> vec2<f32> {
-  let safeW = select(1e-6, clip.w, abs(clip.w) >= 1e-6);
-  let ndc = clip.xy / safeW;
-  return vec2<f32>(ndc.x * 0.5 + 0.5, 0.5 - ndc.y * 0.5);
-}
-
-fn sceneTemporalViewDepth(clip : vec4<f32>) -> f32 {
-  let perspectiveDepth = max(clip.w, 0.0);
-  let ndcDepth = clip.z / max(abs(clip.w), 1e-6);
-  let orthographicDepth = view.temporalProjection.x +
-    ndcDepth * (view.temporalProjection.y - view.temporalProjection.x);
-  let viewDepth = select(
-    perspectiveDepth,
-    max(orthographicDepth, 0.0),
-    view.temporalProjection.z >= 0.5,
-  );
-  return log2(1.0 + viewDepth);
-}
-
-fn packSceneTemporal(
-  currentClip : vec4<f32>,
-  previousClip : vec4<f32>,
-  reactive : f32,
-) -> vec4<f32> {
-  return vec4<f32>(
-    sceneTemporalUv(currentClip) - sceneTemporalUv(previousClip),
-    sceneTemporalViewDepth(currentClip),
-    clamp(reactive, 0.0, 1.0),
-  );
-}
 #if STORAGE_BUFFER_AVAILABLE == true
 @group(3) @binding(0) var<storage, read> instances : array<InstanceData>;
 #else

package/src/default-standard-pbr-skin.wgsl

@@ -88,6 +88,11 @@ struct Material {
   clearcoatRoughness : f32,
   specularTint       : vec3<f32>,
   normalScale                   : f32,
+  transmission                  : f32,
+  ior                           : f32,
+  thickness                     : f32,
+  attenuationColor              : vec3<f32>,
+  attenuationDistance           : f32,
   baseColorTextureCoordinatesTransform : vec4<f32>,
   baseColorTextureCoordinatesMetadata : vec4<f32>,
   metallicRoughnessTextureCoordinatesTransform : vec4<f32>,
@@ -100,6 +105,10 @@ struct Material {
   emissiveTextureCoordinatesMetadata : vec4<f32>,
   occlusionTextureCoordinatesTransform : vec4<f32>,
   occlusionTextureCoordinatesMetadata : vec4<f32>,
+  transmissionTextureCoordinatesTransform : vec4<f32>,
+  transmissionTextureCoordinatesMetadata : vec4<f32>,
+  thicknessTextureCoordinatesTransform : vec4<f32>,
+  thicknessTextureCoordinatesMetadata : vec4<f32>,
 };
 
 @group(1) @binding(0) var<uniform> material : Material;
@@ -115,6 +124,10 @@ struct Material {
 @group(1) @binding(10) var emissiveTexture : texture_2d<f32>;
 @group(1) @binding(11) var occlusionSampler : sampler;
 @group(1) @binding(12) var occlusionTexture : texture_2d<f32>;
+@group(1) @binding(13) var transmissionSampler : sampler;
+@group(1) @binding(14) var transmissionTexture : texture_2d<f32>;
+@group(1) @binding(15) var thicknessSampler : sampler;
+@group(1) @binding(16) var thicknessTexture : texture_2d<f32>;
 
 // Preserve filtering reflection for resources passed to the shared sampler.
 fn materialTextureFilteringWitness() {
@@ -124,12 +137,16 @@ fn materialTextureFilteringWitness() {
   let specularTint = specularTintTexture;
   let emissive = emissiveTexture;
   let occlusion = occlusionTexture;
+  let transmission = transmissionTexture;
+  let thickness = thicknessTexture;
   let baseWitness = textureSample(base, baseColorSampler, vec2<f32>(0.0));
   let metallicRoughnessWitness = textureSample(metallicRoughness, metallicRoughnessSampler, vec2<f32>(0.0));
   let normalWitness = textureSample(normal, normalSampler, vec2<f32>(0.0));
   let specularTintWitness = textureSample(specularTint, specularTintSampler, vec2<f32>(0.0));
   let emissiveWitness = textureSample(emissive, emissiveSampler, vec2<f32>(0.0));
   let occlusionWitness = textureSample(occlusion, occlusionSampler, vec2<f32>(0.0));
+  let transmissionWitness = textureSample(transmission, transmissionSampler, vec2<f32>(0.0));
+  let thicknessWitness = textureSample(thickness, thicknessSampler, vec2<f32>(0.0));
 }
 
 struct SkylightUniforms {
@@ -146,13 +163,13 @@ struct SkylightUniforms {
   colorB : f32,
   rotation : vec4<f32>,
 };
-@group(1) @binding(13) var irradianceMap        : texture_cube<f32>;
-@group(1) @binding(14) var irradianceSampler    : sampler;
-@group(1) @binding(15) var prefilterMap         : texture_cube<f32>;
-@group(1) @binding(16) var prefilterSampler     : sampler;
-@group(1) @binding(17) var brdfLut              : texture_2d<f32>;
-@group(1) @binding(18) var brdfLutSampler       : sampler;
-@group(1) @binding(19) var<uniform> skylight    : SkylightUniforms;
+@group(1) @binding(17) var irradianceMap        : texture_cube<f32>;
+@group(1) @binding(18) var irradianceSampler    : sampler;
+@group(1) @binding(19) var prefilterMap         : texture_cube<f32>;
+@group(1) @binding(20) var prefilterSampler     : sampler;
+@group(1) @binding(21) var brdfLut              : texture_2d<f32>;
+@group(1) @binding(22) var brdfLutSampler       : sampler;
+@group(1) @binding(23) var<uniform> skylight    : SkylightUniforms;
 
 #if STORAGE_BUFFER_AVAILABLE == true
 @group(2) @binding(1) var<storage, read> palette : array<mat4x4<f32>>;
@@ -469,8 +486,8 @@ struct TemporalVsOut {
   @location(5) uv5 : vec2<f32>,
   @location(6) uv6 : vec2<f32>,
   @location(7) uv7 : vec2<f32>,
-  @location(8) @interpolate(linear) currentClip : vec4<f32>,
-  @location(9) @interpolate(linear) previousClip : vec4<f32>,
+  @location(8) @interpolate(perspective) currentClip : vec4<f32>,
+  @location(9) @interpolate(perspective) previousClip : vec4<f32>,
 #ifdef VERTEX_COLOR_AVAILABLE
   @location(14) color : vec4<f32>,
 #endif
@@ -531,6 +548,7 @@ fn fs_temporal(in : TemporalVsOut) -> @location(0) vec4<f32> {
     material.baseColorTextureCoordinatesMetadata,
     in.currentClip,
     in.previousClip,
+    view.temporalProjection,
     reactive,
     in.uv, in.uv1, in.uv2, in.uv3,
     in.uv4, in.uv5, in.uv6, in.uv7,