@forgeax/engine-shader 0.1.2

package/src/ibl-shared.wgsl

@@ -0,0 +1,118 @@
+#define_import_path forgeax_pbr::ibl_shared
+
+// @forgeax/engine-shader - ibl-shared.wgsl (feat-20260520-skylight-ibl-cubemap M3 / t42).
+//
+// Pure-function math shared across the 6-module ibl-* family. Zero binding
+// declarations -- this module never touches @group/@binding so it composes
+// cleanly with any host that has its own @group(0)/@group(1) layout.
+//
+// Origin: round-1's monolithic ibl.wgsl collided @group(1) @binding(0)
+// across texture_2d (equirect) and texture_cube (irradiance, prefilter),
+// which the WGSL spec forbids inside a single module. round-2 splits the
+// math out into this file so the 4 precompute modules + 2 sampling helpers
+// can each declare their own (group, binding) namespace without overlap.
+//
+// Exports (no entry points):
+//   - PI, INV_ATAN constants
+//   - sampleSphericalMap(v)
+//   - radicalInverseVdC(bits)
+//   - hammersley(i, N)
+//   - iblDGGX(nDotH, roughness)
+//   - iblGeometrySchlickGGX(NdotV, roughness)   (IBL k = roughness^2 / 2)
+//   - iblGeometrySmith(NdotV, NdotL, roughness)
+//   - importanceSampleGGX(Xi, N, roughness)
+//   - fresnelSchlickRoughness(cosTheta, F0, roughness)
+//
+// References: LearnOpenGL §6.2 IBL pipeline; Karis 2013 split-sum.
+
+const INV_ATAN: vec2<f32> = vec2<f32>(0.1591, 0.3183);
+const PI: f32 = 3.14159265;
+
+// Map a direction vector to equirectangular UV.
+fn sampleSphericalMap(v: vec3<f32>) -> vec2<f32> {
+  let uv = vec2<f32>(atan2(v.z, v.x), asin(v.y));
+  return uv * INV_ATAN + 0.5;
+}
+
+// Rotate a sampling direction by the inverse of an environment quaternion.
+// This keeps the baked cubemap reusable while rotating the source map in
+// world space at the final sampling boundary.
+fn inverseRotateEnvironment(direction: vec3<f32>, rotation: vec4<f32>) -> vec3<f32> {
+  let q = normalize(rotation);
+  let t = 2.0 * cross(q.xyz, direction);
+  return direction - q.w * t + cross(q.xyz, t);
+}
+
+// Van der Corput radical inverse in base 2.
+fn radicalInverseVdC(bits: u32) -> f32 {
+  var b: u32 = bits;
+  b = (b << 16u) | (b >> 16u);
+  b = ((b & 0x55555555u) << 1u) | ((b & 0xAAAAAAAAu) >> 1u);
+  b = ((b & 0x33333333u) << 2u) | ((b & 0xCCCCCCCCu) >> 2u);
+  b = ((b & 0x0F0F0F0Fu) << 4u) | ((b & 0xF0F0F0F0u) >> 4u);
+  b = ((b & 0x00FF00FFu) << 8u) | ((b & 0xFF00FF00u) >> 8u);
+  return f32(b) * 2.3283064365386963e-10;
+}
+
+// Hammersley low-discrepancy 2D sequence: (i/N, radicalInverseVdC(i)).
+fn hammersley(i: u32, N: u32) -> vec2<f32> {
+  return vec2<f32>(f32(i) / f32(N), radicalInverseVdC(i));
+}
+
+// GGX NDF.
+fn iblDGGX(nDotH: f32, roughness: f32) -> f32 {
+  let a = roughness * roughness;
+  let a2 = a * a;
+  let f = (nDotH * a2 - nDotH) * nDotH + 1.0;
+  return a2 / (max(PI * f * f, 1e-7));
+}
+
+// Smith-GGX G1 for IBL: k = roughness^2 / 2.
+// DIFFERENT from direct-light's k = ((roughness+1)^2)/8 (in brdf.wgsl).
+fn iblGeometrySchlickGGX(NdotV: f32, roughness: f32) -> f32 {
+  let k = (roughness * roughness) / 2.0;
+  return NdotV / max(NdotV * (1.0 - k) + k, 1e-5);
+}
+
+// Smith-GGX height-correlated geometry for IBL.
+fn iblGeometrySmith(NdotV: f32, NdotL: f32, roughness: f32) -> f32 {
+  let ggxV = iblGeometrySchlickGGX(NdotV, roughness);
+  let ggxL = iblGeometrySchlickGGX(NdotL, roughness);
+  return ggxV * ggxL;
+}
+
+// GGX importance sampling: maps uniform 2D sample Xi to a half-vector H
+// in the local frame around N.
+fn importanceSampleGGX(Xi: vec2<f32>, N: vec3<f32>, roughness: f32) -> vec3<f32> {
+  let a = roughness * roughness;
+
+  let phi = 2.0 * PI * Xi.x;
+  let cosTheta = sqrt(max((1.0 - Xi.y) / (1.0 + (a * a - 1.0) * Xi.y), 0.0));
+  let sinTheta = sqrt(max(1.0 - cosTheta * cosTheta, 0.0));
+
+  // GGX half-vector in tangent space.
+  let Ht = vec3<f32>(cos(phi) * sinTheta, sin(phi) * sinTheta, cosTheta);
+
+  // Tangent frame construction (avoids singularity at N parallel to z).
+  // WGSL `select(falseVal, trueVal, cond)` returns trueVal when cond is
+  // true; the LearnOpenGL reference is `cond ? vec3(0,0,1) : vec3(1,0,0)`.
+  // When N is (near-)parallel to z (e.g. the BRDF-LUT canonical frame
+  // N = (0,0,1)) we need up = (1,0,0); otherwise up = (0,0,1). Swapping the
+  // operands here fixes the brdf-lut bake silently producing all-zero output
+  // (cross(up, N) = 0 when up == N, normalize(0) = NaN, GPU flushes to 0).
+  let up = select(
+    vec3<f32>(1.0, 0.0, 0.0),
+    vec3<f32>(0.0, 0.0, 1.0),
+    abs(N.z) < 0.999,
+  );
+  let tangent = normalize(cross(up, N));
+  let bitangent = cross(N, tangent);
+
+  return normalize(tangent * Ht.x + bitangent * Ht.y + N * Ht.z);
+}
+
+// Fresnel-Schlick with roughness dampening for IBL specular.
+fn fresnelSchlickRoughness(cosTheta: f32, F0: vec3<f32>, roughness: f32) -> vec3<f32> {
+  let oneMinusRough = max(vec3<f32>(1.0 - roughness), F0);
+  return F0 + (oneMinusRough - F0) * pow(clamp(1.0 - cosTheta, 0.0, 1.0), 5.0);
+}

package/src/index.ts

@@ -0,0 +1,166 @@
+// @forgeax/engine-shader — runtime shader registry public surface.
+//
+// Shape rules (plan-strategy §S-10 / D-R10 / OQ-5 close):
+// - instance-per-engine — exposed through the lazy `engine.shader:
+//   ShaderRegistry` property; module-level singletons / static methods are
+//   forbidden (aligned with `Engine.create({ rhi })`'s instance-based style).
+// - Physical isolation — this package's deps only contain `@forgeax/engine-rhi` +
+//   `@forgeax/engine-types`; importing `@forgeax/engine-shader-compiler` / `@forgeax/engine-naga`
+//   / `@forgeax/engine-wgpu-wasm` directly or transitively is **forbidden**
+//   (guarded by the AC-06 triple-grep gate; feat-20260511-naga-rhi-wgpu-merge
+//   M4 replaced the legacy single-shim ban with the merged ban triple above).
+// - Result model — expected failures go through
+//   `Result.err(RhiError | ShaderError)` and **never throw** (AGENTS.md
+//   "Errors are structured" / charter proposition 4: explicit failure).
+//
+// Top-level surface (charter proposition 1: progressive disclosure):
+// - ShaderRegistry / ShaderRegistryOptions / ShaderRegistryDevice — main class
+//   + injection interface
+// - ShaderError / ShaderErrorCode / 2 factories — runtime error types
+// - Result<T, E> + ok / err — binary result type and constructors
+// - ManifestEntry — re-exported from `@forgeax/engine-types` (manifest schema SSOT)
+
+export type { ManifestEntry, ParamSchemaEntry } from '@forgeax/engine-types';
+
+import type { MaterialAsset, MaterialParameter, MaterialValue } from '@forgeax/engine-types';
+import { STANDARD_PBR_ALPHA_CUTOFF_DEFAULT } from './material-schemas.js';
+
+export { MATERIAL_PARAM_TYPES } from '@forgeax/engine-types';
+export {
+  err,
+  manifestMalformed,
+  materialShaderNotFound,
+  ok,
+  type Result,
+  type ResultErr,
+  type ResultOk,
+  ShaderError,
+  type ShaderErrorCode,
+  type ShaderErrorDetail,
+  shaderNotFound,
+} from './errors.js';
+export {
+  type MaterialArtifactConflictError,
+  type MaterialArtifactInspection,
+  MaterialArtifactRegistry,
+  type MaterialRuntimeArtifact,
+  registerMaterialArtifact,
+} from './material/artifact-registry.js';
+export {
+  isMaterialShaderArtifact,
+  type MaterialShaderArtifact,
+} from './material/artifact-types.js';
+export {
+  DEFAULT_MSDF_TEXT_PARAM_SCHEMA,
+  DEFAULT_SPRITE_PARAM_SCHEMA,
+  DEFAULT_STANDARD_PBR_PARAM_SCHEMA,
+  DEFAULT_UNLIT_PARAM_SCHEMA,
+  STANDARD_PBR_ALPHA_CUTOFF_DEFAULT,
+} from './material-schemas.js';
+export {
+  registerDefaultSpriteLit,
+  type SpriteLitCaps,
+} from './register-default-sprite-lit.js';
+export { registerDefaultStandardPbrSkin } from './register-default-standard-pbr-skin.js';
+export {
+  FORGEAX_RESERVED_PATH_PREFIX,
+  type MaterialShaderEntry,
+  type RegisteredMaterialShaderEntry,
+  ShaderRegistry,
+  type ShaderRegistryDevice,
+  type ShaderRegistryOptions,
+} from './ShaderRegistry.js';
+export {
+  findVariantByKey,
+  type MaterialShaderManifestEntry,
+  type MaterialShaderManifestVariant,
+} from './types.js';
+
+export const BUILTIN_MATERIAL_MODULES = {
+  standard: 'forgeax_material::standard',
+  unlit: 'forgeax_material::unlit',
+  sprite: 'forgeax_material::sprite',
+} as const;
+
+/**
+ * Material modules whose shader source and parameter contract are owned by
+ * the Engine. They live in the runtime ShaderRegistry, so a Pack containing
+ * one of these materials carries authored values only and does not require a
+ * project material-cook artifact.
+ */
+export const ENGINE_MATERIAL_MODULES = [
+  'forgeax::default-standard-pbr',
+  'forgeax::pbr-skin',
+  'forgeax::default-standard-pbr-skin',
+  'forgeax::default-unlit',
+  'forgeax::default-shadow-caster',
+  'forgeax::sprite',
+  'forgeax::sprite-lit',
+  'forgeax::msdf-text',
+  BUILTIN_MATERIAL_MODULES.standard,
+  BUILTIN_MATERIAL_MODULES.unlit,
+  BUILTIN_MATERIAL_MODULES.sprite,
+  'forgeax_material::sprite-lit',
+] as const;
+
+export function isEngineMaterialModule(module: string): boolean {
+  return (ENGINE_MATERIAL_MODULES as readonly string[]).includes(module);
+}
+
+export function isEngineMaterial(material: Pick<MaterialAsset, 'passes'>): boolean {
+  const passes = material.passes ?? [];
+  return passes.length > 0 && passes.every((pass) => isEngineMaterialModule(pass.program.module));
+}
+
+export type BuiltinMaterialKind = keyof typeof BUILTIN_MATERIAL_MODULES;
+
+const BUILTIN_PARAMETERS: Readonly<Record<BuiltinMaterialKind, readonly MaterialParameter[]>> = {
+  standard: [
+    { name: 'baseColor', type: 'color' },
+    { name: 'metallic', type: 'f32' },
+    { name: 'roughness', type: 'f32' },
+    { name: 'alphaCutoff', type: 'f32', optional: true },
+  ],
+  unlit: [{ name: 'baseColor', type: 'color' }],
+  sprite: [{ name: 'colorTint', type: 'vec4', colorSpace: 'srgb' }],
+};
+
+const BUILTIN_VALUES: Readonly<
+  Record<BuiltinMaterialKind, Readonly<Record<string, MaterialValue>>>
+> = {
+  standard: {
+    baseColor: [1, 1, 1, 1],
+    metallic: 0,
+    roughness: 0.5,
+    alphaCutoff: STANDARD_PBR_ALPHA_CUTOFF_DEFAULT,
+  },
+  unlit: { baseColor: [1, 1, 1, 1] },
+  sprite: { colorTint: [1, 1, 1, 1] },
+};
+
+export function createBuiltinMaterialAsset(kind: BuiltinMaterialKind): MaterialAsset {
+  return {
+    kind: 'material',
+    passes: [{ name: 'forward', program: { module: BUILTIN_MATERIAL_MODULES[kind] } }],
+    parameters: BUILTIN_PARAMETERS[kind],
+    values: BUILTIN_VALUES[kind],
+  };
+}
+
+/**
+ * Shared luminance epsilon floor for the extended Reinhard tone-map
+ * (feat-20260519-tonemap-reinhard-mvp / D-O3).
+ *
+ * Both the TS port at `packages/runtime/src/systems/tonemap.ts` and the WGSL
+ * fragment stage in `packages/shader/src/tonemap.wgsl` apply
+ * `max(Y, TONEMAP_LUMINANCE_EPSILON)` before dividing the luminance ratio.
+ * The floor keeps the divisor finite at degenerate inputs (`Y = 0` from black
+ * pixels, `Y < 0` from rare numerical artefacts). Single SSOT here so a
+ * single `import { TONEMAP_LUMINANCE_EPSILON } from '@forgeax/engine-shader'`
+ * keeps TS / WGSL byte-equivalent.
+ *
+ * Value: `1e-5` — small enough to not perturb any plausible HDR luminance.
+ */
+export const TONEMAP_LUMINANCE_EPSILON = 1e-5;
+
+export { TONEMAP_SHADER_MODE, type TonemapShaderMode } from './tonemap.js';