@luma.gl/shaders 0.0.0-stage → 10.0.0-alpha.11

package/src/modules/lighting/prefiltered-environment/prefiltered-environment.ts

@@ -0,0 +1,370 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ShaderModule} from '../../../lib/shader-module/shader-module';
+
+export type PBREnvironmentFilterUniforms = {
+  face: number;
+  roughness: number;
+  mode: number;
+  sampleCount: number;
+  sourceEncoding: number;
+};
+
+export type PBREnvironmentFilterBindings<TextureT = unknown> = {
+  pbrEnvironmentSource: TextureT;
+};
+
+export type PBREnvironmentFilterProps<TextureT = unknown> = PBREnvironmentFilterUniforms &
+  PBREnvironmentFilterBindings<TextureT>;
+
+const GLSL_UNIFORMS = /* glsl */ `\
+layout(std140) uniform pbrEnvironmentFilterUniforms {
+  int face;
+  float roughness;
+  int mode;
+  int sampleCount;
+  int sourceEncoding;
+} pbrEnvironmentFilter;
+
+uniform sampler2D pbrEnvironmentSource;
+`;
+
+const WGSL_UNIFORMS = /* wgsl */ `\
+struct PBREnvironmentFilterUniforms {
+  face: i32,
+  roughness: f32,
+  mode: i32,
+  sampleCount: i32,
+  sourceEncoding: i32,
+};
+
+@group(0) @binding(auto) var<uniform> pbrEnvironmentFilter: PBREnvironmentFilterUniforms;
+@group(0) @binding(auto) var pbrEnvironmentSource: texture_2d<f32>;
+@group(0) @binding(auto) var pbrEnvironmentSourceSampler: sampler;
+`;
+
+export const pbrEnvironmentFilter = {
+  name: 'pbrEnvironmentFilter',
+  bindingLayout: [
+    {name: 'pbrEnvironmentFilter', group: 0},
+    {name: 'pbrEnvironmentSource', group: 0}
+  ],
+  fs: GLSL_UNIFORMS,
+  source: WGSL_UNIFORMS,
+  getUniforms: (properties: Partial<PBREnvironmentFilterProps>) => properties,
+  uniformTypes: {
+    face: 'i32',
+    roughness: 'f32',
+    mode: 'i32',
+    sampleCount: 'i32',
+    sourceEncoding: 'i32'
+  },
+  defaultUniforms: {
+    face: 0,
+    roughness: 0,
+    mode: 0,
+    sampleCount: 64,
+    sourceEncoding: 0
+  }
+} as const satisfies ShaderModule<
+  PBREnvironmentFilterProps,
+  PBREnvironmentFilterUniforms,
+  PBREnvironmentFilterBindings
+>;
+
+export const PBR_ENVIRONMENT_FRAGMENT_GLSL = /* glsl */ `\
+#version 300 es
+precision highp float;
+precision highp int;
+
+in vec2 uv;
+out vec4 fragmentColor;
+
+const float ENVIRONMENT_PI = 3.141592653589793;
+
+vec2 getEnvironmentHammersley(uint index, uint sampleCount)
+{
+  uint reversedBits = (index << 16u) | (index >> 16u);
+  reversedBits = ((reversedBits & 0x55555555u) << 1u) |
+    ((reversedBits & 0xAAAAAAAAu) >> 1u);
+  reversedBits = ((reversedBits & 0x33333333u) << 2u) |
+    ((reversedBits & 0xCCCCCCCCu) >> 2u);
+  reversedBits = ((reversedBits & 0x0F0F0F0Fu) << 4u) |
+    ((reversedBits & 0xF0F0F0F0u) >> 4u);
+  reversedBits = ((reversedBits & 0x00FF00FFu) << 8u) |
+    ((reversedBits & 0xFF00FF00u) >> 8u);
+  return vec2(
+    float(index) / float(sampleCount),
+    float(reversedBits) * 2.3283064365386963e-10
+  );
+}
+
+vec3 getEnvironmentFaceDirection(int face, vec2 textureCoordinate)
+{
+  vec2 coordinate = textureCoordinate * 2.0 - 1.0;
+  if (face == 0) return normalize(vec3(1.0, -coordinate.y, -coordinate.x));
+  if (face == 1) return normalize(vec3(-1.0, -coordinate.y, coordinate.x));
+  if (face == 2) return normalize(vec3(coordinate.x, 1.0, coordinate.y));
+  if (face == 3) return normalize(vec3(coordinate.x, -1.0, -coordinate.y));
+  if (face == 4) return normalize(vec3(coordinate.x, -coordinate.y, 1.0));
+  return normalize(vec3(-coordinate.x, -coordinate.y, -1.0));
+}
+
+mat3 getEnvironmentTangentBasis(vec3 normal)
+{
+  vec3 up = abs(normal.z) < 0.999 ? vec3(0.0, 0.0, 1.0) : vec3(1.0, 0.0, 0.0);
+  vec3 tangent = normalize(cross(up, normal));
+  return mat3(tangent, cross(normal, tangent), normal);
+}
+
+vec3 sampleEnvironmentDirection(vec3 direction)
+{
+  vec3 normalizedDirection = normalize(direction);
+  vec2 textureCoordinate = vec2(
+    atan(normalizedDirection.z, normalizedDirection.x) / (2.0 * ENVIRONMENT_PI) + 0.5,
+    acos(clamp(normalizedDirection.y, -1.0, 1.0)) / ENVIRONMENT_PI
+  );
+  vec3 color = texture(pbrEnvironmentSource, textureCoordinate).rgb;
+  if (pbrEnvironmentFilter.sourceEncoding == 1) {
+    vec3 lower = color / 12.92;
+    vec3 upper = pow((color + 0.055) / 1.055, vec3(2.4));
+    color = mix(lower, upper, step(vec3(0.04045), color));
+  }
+  return color;
+}
+
+vec3 importanceSampleEnvironment(vec2 sequence, vec3 normal, float roughness)
+{
+  float alpha = max(roughness * roughness, 0.0001);
+  float azimuth = 2.0 * ENVIRONMENT_PI * sequence.x;
+  float cosine = sqrt(
+    (1.0 - sequence.y) / max(1.0 + (alpha * alpha - 1.0) * sequence.y, 0.0001)
+  );
+  float sine = sqrt(max(1.0 - cosine * cosine, 0.0));
+  vec3 halfVector = vec3(cos(azimuth) * sine, sin(azimuth) * sine, cosine);
+  return normalize(getEnvironmentTangentBasis(normal) * halfVector);
+}
+
+float getEnvironmentGeometry(float normalDotDirection, float roughness)
+{
+  float alpha = roughness * roughness;
+  float factor = alpha * 0.5;
+  return normalDotDirection / max(normalDotDirection * (1.0 - factor) + factor, 0.0001);
+}
+
+vec2 integrateEnvironmentBRDF(vec2 textureCoordinate, int sampleCount)
+{
+  float normalDotView = max(textureCoordinate.x, 0.001);
+  float roughness = 1.0 - textureCoordinate.y;
+  vec3 viewDirection = vec3(sqrt(max(1.0 - normalDotView * normalDotView, 0.0)), 0.0, normalDotView);
+  vec2 integration = vec2(0.0);
+
+  for (int sampleIndex = 0; sampleIndex < 1024; sampleIndex++) {
+    if (sampleIndex >= sampleCount) break;
+    vec3 halfVector = importanceSampleEnvironment(
+      getEnvironmentHammersley(uint(sampleIndex), uint(sampleCount)),
+      vec3(0.0, 0.0, 1.0),
+      roughness
+    );
+    vec3 lightDirection = normalize(2.0 * dot(viewDirection, halfVector) * halfVector - viewDirection);
+    float normalDotLight = max(lightDirection.z, 0.0);
+    float normalDotHalf = max(halfVector.z, 0.0);
+    float viewDotHalf = max(dot(viewDirection, halfVector), 0.0);
+    if (normalDotLight > 0.0) {
+      float visibility = getEnvironmentGeometry(normalDotView, roughness) *
+        getEnvironmentGeometry(normalDotLight, roughness) * viewDotHalf /
+        max(normalDotHalf * normalDotView, 0.0001);
+      float fresnel = pow(1.0 - viewDotHalf, 5.0);
+      integration += vec2(1.0 - fresnel, fresnel) * visibility;
+    }
+  }
+  return integration / float(sampleCount);
+}
+
+vec3 integrateEnvironmentDirection(vec3 normal, int sampleCount)
+{
+  vec3 accumulatedColor = vec3(0.0);
+  float accumulatedWeight = 0.0;
+
+  for (int sampleIndex = 0; sampleIndex < 1024; sampleIndex++) {
+    if (sampleIndex >= sampleCount) break;
+    vec2 sequence = getEnvironmentHammersley(uint(sampleIndex), uint(sampleCount));
+    vec3 direction;
+    float sampleWeight;
+
+    if (pbrEnvironmentFilter.mode == 1) {
+      float azimuth = 2.0 * ENVIRONMENT_PI * sequence.x;
+      float cosine = sqrt(1.0 - sequence.y);
+      float sine = sqrt(sequence.y);
+      direction = normalize(
+        getEnvironmentTangentBasis(normal) *
+        vec3(cos(azimuth) * sine, sin(azimuth) * sine, cosine)
+      );
+      sampleWeight = 1.0;
+    } else {
+      vec3 halfVector = importanceSampleEnvironment(sequence, normal, pbrEnvironmentFilter.roughness);
+      direction = normalize(2.0 * dot(normal, halfVector) * halfVector - normal);
+      sampleWeight = max(dot(normal, direction), 0.0);
+    }
+
+    accumulatedColor += sampleEnvironmentDirection(direction) * sampleWeight;
+    accumulatedWeight += sampleWeight;
+  }
+
+  return accumulatedColor / max(accumulatedWeight, 0.0001);
+}
+
+void main(void)
+{
+  int sampleCount = max(pbrEnvironmentFilter.sampleCount, 1);
+  if (pbrEnvironmentFilter.mode == 2) {
+    fragmentColor = vec4(integrateEnvironmentBRDF(uv, sampleCount), 0.0, 1.0);
+    return;
+  }
+
+  vec3 direction = getEnvironmentFaceDirection(pbrEnvironmentFilter.face, uv);
+  fragmentColor = vec4(integrateEnvironmentDirection(direction, sampleCount), 1.0);
+}
+`;
+
+export const PBR_ENVIRONMENT_FRAGMENT_WGSL = /* wgsl */ `\
+const ENVIRONMENT_PI: f32 = 3.141592653589793;
+
+fn getEnvironmentHammersley(index: u32, sampleCount: u32) -> vec2f {
+  return vec2f(f32(index) / f32(sampleCount), f32(reverseBits(index)) * 2.3283064365386963e-10);
+}
+
+fn getEnvironmentFaceDirection(face: i32, textureCoordinate: vec2f) -> vec3f {
+  let coordinate = textureCoordinate * 2.0 - 1.0;
+  if (face == 0) { return normalize(vec3f(1.0, -coordinate.y, -coordinate.x)); }
+  if (face == 1) { return normalize(vec3f(-1.0, -coordinate.y, coordinate.x)); }
+  if (face == 2) { return normalize(vec3f(coordinate.x, 1.0, coordinate.y)); }
+  if (face == 3) { return normalize(vec3f(coordinate.x, -1.0, -coordinate.y)); }
+  if (face == 4) { return normalize(vec3f(coordinate.x, -coordinate.y, 1.0)); }
+  return normalize(vec3f(-coordinate.x, -coordinate.y, -1.0));
+}
+
+fn getEnvironmentTangentBasis(normal: vec3f) -> mat3x3f {
+  var up = vec3f(1.0, 0.0, 0.0);
+  if (abs(normal.z) < 0.999) {
+    up = vec3f(0.0, 0.0, 1.0);
+  }
+  let tangent = normalize(cross(up, normal));
+  return mat3x3f(tangent, cross(normal, tangent), normal);
+}
+
+fn sampleEnvironmentDirection(direction: vec3f) -> vec3f {
+  let normalizedDirection = normalize(direction);
+  let textureCoordinate = vec2f(
+    atan2(normalizedDirection.z, normalizedDirection.x) / (2.0 * ENVIRONMENT_PI) + 0.5,
+    acos(clamp(normalizedDirection.y, -1.0, 1.0)) / ENVIRONMENT_PI
+  );
+  var color = textureSampleLevel(
+    pbrEnvironmentSource,
+    pbrEnvironmentSourceSampler,
+    textureCoordinate,
+    0.0
+  ).rgb;
+  if (pbrEnvironmentFilter.sourceEncoding == 1) {
+    let lower = color / 12.92;
+    let upper = pow((color + 0.055) / 1.055, vec3f(2.4));
+    color = mix(lower, upper, step(vec3f(0.04045), color));
+  }
+  return color;
+}
+
+fn importanceSampleEnvironment(sequence: vec2f, normal: vec3f, roughness: f32) -> vec3f {
+  let alpha = max(roughness * roughness, 0.0001);
+  let azimuth = 2.0 * ENVIRONMENT_PI * sequence.x;
+  let cosine = sqrt(
+    (1.0 - sequence.y) / max(1.0 + (alpha * alpha - 1.0) * sequence.y, 0.0001)
+  );
+  let sine = sqrt(max(1.0 - cosine * cosine, 0.0));
+  let halfVector = vec3f(cos(azimuth) * sine, sin(azimuth) * sine, cosine);
+  return normalize(getEnvironmentTangentBasis(normal) * halfVector);
+}
+
+fn getEnvironmentGeometry(normalDotDirection: f32, roughness: f32) -> f32 {
+  let alpha = roughness * roughness;
+  let factor = alpha * 0.5;
+  return normalDotDirection / max(normalDotDirection * (1.0 - factor) + factor, 0.0001);
+}
+
+fn integrateEnvironmentBRDF(textureCoordinate: vec2f, sampleCount: u32) -> vec2f {
+  let normalDotView = max(textureCoordinate.x, 0.001);
+  let roughness = 1.0 - textureCoordinate.y;
+  let viewDirection = vec3f(
+    sqrt(max(1.0 - normalDotView * normalDotView, 0.0)),
+    0.0,
+    normalDotView
+  );
+  var integration = vec2f(0.0);
+
+  for (var sampleIndex = 0u; sampleIndex < sampleCount; sampleIndex++) {
+    let halfVector = importanceSampleEnvironment(
+      getEnvironmentHammersley(sampleIndex, sampleCount),
+      vec3f(0.0, 0.0, 1.0),
+      roughness
+    );
+    let lightDirection = normalize(
+      2.0 * dot(viewDirection, halfVector) * halfVector - viewDirection
+    );
+    let normalDotLight = max(lightDirection.z, 0.0);
+    let normalDotHalf = max(halfVector.z, 0.0);
+    let viewDotHalf = max(dot(viewDirection, halfVector), 0.0);
+    if (normalDotLight > 0.0) {
+      let visibility = getEnvironmentGeometry(normalDotView, roughness) *
+        getEnvironmentGeometry(normalDotLight, roughness) * viewDotHalf /
+        max(normalDotHalf * normalDotView, 0.0001);
+      let fresnel = pow(1.0 - viewDotHalf, 5.0);
+      integration += vec2f(1.0 - fresnel, fresnel) * visibility;
+    }
+  }
+  return integration / f32(sampleCount);
+}
+
+fn integrateEnvironmentDirection(normal: vec3f, sampleCount: u32) -> vec3f {
+  var accumulatedColor = vec3f(0.0);
+  var accumulatedWeight = 0.0;
+
+  for (var sampleIndex = 0u; sampleIndex < sampleCount; sampleIndex++) {
+    let sequence = getEnvironmentHammersley(sampleIndex, sampleCount);
+    var direction: vec3f;
+    var sampleWeight: f32;
+
+    if (pbrEnvironmentFilter.mode == 1) {
+      let azimuth = 2.0 * ENVIRONMENT_PI * sequence.x;
+      let cosine = sqrt(1.0 - sequence.y);
+      let sine = sqrt(sequence.y);
+      direction = normalize(
+        getEnvironmentTangentBasis(normal) *
+        vec3f(cos(azimuth) * sine, sin(azimuth) * sine, cosine)
+      );
+      sampleWeight = 1.0;
+    } else {
+      let halfVector = importanceSampleEnvironment(sequence, normal, pbrEnvironmentFilter.roughness);
+      direction = normalize(2.0 * dot(normal, halfVector) * halfVector - normal);
+      sampleWeight = max(dot(normal, direction), 0.0);
+    }
+
+    accumulatedColor += sampleEnvironmentDirection(direction) * sampleWeight;
+    accumulatedWeight += sampleWeight;
+  }
+  return accumulatedColor / max(accumulatedWeight, 0.0001);
+}
+
+@fragment
+fn fragmentMain(inputs: FragmentInputs) -> @location(0) vec4f {
+  // ClipSpace UVs increase upward; WebGPU texture rows increase downward.
+  let textureCoordinate = vec2f(inputs.uv.x, 1.0 - inputs.uv.y);
+  let sampleCount = u32(max(pbrEnvironmentFilter.sampleCount, 1));
+  if (pbrEnvironmentFilter.mode == 2) {
+    return vec4f(integrateEnvironmentBRDF(textureCoordinate, sampleCount), 0.0, 1.0);
+  }
+
+  let direction = getEnvironmentFaceDirection(pbrEnvironmentFilter.face, textureCoordinate);
+  return vec4f(integrateEnvironmentDirection(direction, sampleCount), 1.0);
+}
+`;

package/src/modules/lighting/shadow/shadow-glsl.ts

@@ -0,0 +1,204 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+/** WebGL2 sampling uses raw depth arrays and explicit comparisons; cube arrays are face arrays. */
+export const SHADOW_GLSL = /* glsl */ `
+precision highp sampler2DArray;
+struct DirectionalShadowLightUniform {
+  vec3 direction;
+  float strength;
+  float normalBias;
+  float sourceAngularRadius;
+  float cascadeBlendFraction;
+  float farFadeFraction;
+  float shadowDistance;
+};
+struct SpotShadowLightUniform {
+  vec3 position;
+  float range;
+  vec3 direction;
+  float outerConeCos;
+  float sourceRadius;
+  float normalBias;
+  float strength;
+  float nearPlane;
+};
+struct PointShadowLightUniform {
+  vec3 position;
+  float range;
+  float sourceRadius;
+  float normalBias;
+  float strength;
+  float nearPlane;
+};
+layout(std140) uniform shadowUniforms {
+  int directionalLightCount;
+  int spotLightCount;
+  int pointLightCount;
+  int cascadeCount;
+  int blockerSampleCount;
+  int filterSampleCount;
+  vec4 cascadeSplits;
+  mat4 directionalViewProjectionMatrices[4];
+  mat4 spotViewProjectionMatrices[4];
+  mat4 pointViewProjectionMatrices[24];
+  DirectionalShadowLightUniform directionalLights[1];
+  SpotShadowLightUniform spotLights[4];
+  PointShadowLightUniform pointLights[4];
+} shadow;
+uniform sampler2DArray directionalShadowTexture;
+uniform sampler2DArray spotShadowTexture;
+uniform sampler2DArray pointShadowTexture;
+const float SHADOW_PI = 3.141592653589793;
+float shadow_hash(vec3 position) {
+  return fract(sin(dot(position, vec3(12.9898, 78.233, 37.719))) * 43758.5453);
+}
+vec2 shadow_diskSample(int index, int count, float rotation) {
+  float fraction = (float(index) + 0.5) / max(float(count), 1.0);
+  float angle = float(index) * 2.39996323 + rotation;
+  return sqrt(fraction) * vec2(cos(angle), sin(angle));
+}
+vec3 shadow_project(mat4 matrix, vec3 worldPosition) {
+  vec4 clip = matrix * vec4(worldPosition, 1.0);
+  vec3 projected = clip.xyz / max(abs(clip.w), 0.00001);
+  // Shared matrices retain [0,1] depth; WebGL texture rows start at the bottom.
+  return vec3(projected.xy * 0.5 + 0.5, projected.z);
+}
+bool shadow_validProjection(vec3 projected) {
+  return all(greaterThanEqual(projected, vec3(0.0))) && all(lessThanEqual(projected, vec3(1.0)));
+}
+// Bilinear interpolation of four depth comparisons matches a hardware 2x2 PCF lookup.
+float shadow_compare(sampler2DArray shadowMap, vec2 coordinate, int layer, float reference) {
+  ivec2 dimensions = textureSize(shadowMap, 0).xy;
+  vec2 position = coordinate * vec2(dimensions) - 0.5;
+  ivec2 base = ivec2(floor(position));
+  vec2 fraction = fract(position);
+  ivec2 maximum = dimensions - 1;
+  float lowerLeft = step(reference, texelFetch(shadowMap, ivec3(clamp(base, ivec2(0), maximum), layer), 0).r);
+  float lowerRight = step(reference, texelFetch(shadowMap, ivec3(clamp(base + ivec2(1,0), ivec2(0), maximum), layer), 0).r);
+  float upperLeft = step(reference, texelFetch(shadowMap, ivec3(clamp(base + ivec2(0,1), ivec2(0), maximum), layer), 0).r);
+  float upperRight = step(reference, texelFetch(shadowMap, ivec3(clamp(base + ivec2(1,1), ivec2(0), maximum), layer), 0).r);
+  return mix(mix(lowerLeft, lowerRight, fraction.x), mix(upperLeft, upperRight, fraction.x), fraction.y);
+}
+float shadow_arrayPCSS(sampler2DArray shadowMap, int layer, vec3 projected, float searchRadius, float rotation, float penumbraScale) {
+  if (!shadow_validProjection(projected)) return 1.0;
+  float texel = 1.0 / float(textureSize(shadowMap, 0).x);
+  searchRadius = max(texel, searchRadius);
+  float blockerDepth = 0.0;
+  float blockerCount = 0.0;
+  for (int index = 0; index < 24; index++) {
+    if (index >= shadow.blockerSampleCount) break;
+    vec2 coordinate = clamp(projected.xy + shadow_diskSample(index, shadow.blockerSampleCount, rotation) * searchRadius, vec2(0.0), vec2(1.0));
+    float depth = textureLod(shadowMap, vec3(coordinate, float(layer)), 0.0).r;
+    if (depth < projected.z) { blockerDepth += depth; blockerCount += 1.0; }
+  }
+  if (blockerCount == 0.0) return 1.0;
+  float averageBlocker = blockerDepth / blockerCount;
+  float penumbra = clamp((projected.z - averageBlocker) / max(abs(averageBlocker), 0.001), 0.0, 1.0);
+  float radius = max(texel, searchRadius * (1.0 + penumbra * penumbraScale));
+  float visibility = 0.0;
+  for (int index = 0; index < 48; index++) {
+    if (index >= shadow.filterSampleCount) break;
+    vec2 coordinate = clamp(projected.xy + shadow_diskSample(index, shadow.filterSampleCount, rotation) * radius, vec2(0.0), vec2(1.0));
+    visibility += shadow_compare(shadowMap, coordinate, layer, projected.z);
+  }
+  return visibility / max(float(shadow.filterSampleCount), 1.0);
+}
+int shadow_directionalCascadeIndex(float viewDepth) {
+  int cascadeIndex = 0;
+  for (int index = 0; index < 4; index++) {
+    if (index >= shadow.cascadeCount) break;
+    cascadeIndex = index;
+    if (viewDepth <= shadow.cascadeSplits[index]) break;
+  }
+  return cascadeIndex;
+}
+int shadow_getDirectionalCascadeIndex(float viewDepth) {
+  return shadow.directionalLightCount == 0 ? -1 : shadow_directionalCascadeIndex(viewDepth);
+}
+float shadow_directionalPCSS(int cascadeIndex, vec3 worldPosition, float viewDepth) {
+  DirectionalShadowLightUniform light = shadow.directionalLights[0];
+  return shadow_arrayPCSS(directionalShadowTexture, cascadeIndex,
+    shadow_project(shadow.directionalViewProjectionMatrices[cascadeIndex], worldPosition),
+    light.sourceAngularRadius * viewDepth / max(light.shadowDistance, 0.001),
+    shadow_hash(worldPosition) * 2.0 * SHADOW_PI, 18.0);
+}
+float shadow_getDirectionalFactor(vec3 worldPosition, vec3 worldNormal, float viewDepth) {
+  if (shadow.directionalLightCount == 0 || viewDepth <= 0.0) return 1.0;
+  DirectionalShadowLightUniform light = shadow.directionalLights[0];
+  if (viewDepth >= light.shadowDistance) return 1.0;
+  vec3 position = worldPosition + normalize(worldNormal) * light.normalBias;
+  int cascadeIndex = shadow_directionalCascadeIndex(viewDepth);
+  float visibility = shadow_directionalPCSS(cascadeIndex, position, viewDepth);
+  if (cascadeIndex + 1 < shadow.cascadeCount) {
+    float cascadeStart = cascadeIndex > 0 ? shadow.cascadeSplits[cascadeIndex - 1] : 0.0;
+    float cascadeEnd = shadow.cascadeSplits[cascadeIndex];
+    float blendWidth = max((cascadeEnd - cascadeStart) * light.cascadeBlendFraction, 0.0001);
+    float blend = smoothstep(cascadeEnd - blendWidth, cascadeEnd, viewDepth);
+    if (blend > 0.0) visibility = mix(visibility, shadow_directionalPCSS(cascadeIndex + 1, position, viewDepth), blend);
+  }
+  float fadeWidth = max(light.shadowDistance * light.farFadeFraction, 0.0001);
+  visibility = mix(visibility, 1.0, smoothstep(light.shadowDistance - fadeWidth, light.shadowDistance, viewDepth));
+  return mix(1.0, visibility, light.strength);
+}
+float shadow_getSpotFactor(int lightIndex, vec3 worldPosition, vec3 worldNormal) {
+  if (lightIndex < 0 || lightIndex >= shadow.spotLightCount) return 1.0;
+  SpotShadowLightUniform light = shadow.spotLights[lightIndex];
+  vec3 fromLight = worldPosition - light.position;
+  float distanceToLight = length(fromLight);
+  if (distanceToLight >= light.range || dot(normalize(fromLight), normalize(light.direction)) < light.outerConeCos) return 1.0;
+  vec3 position = worldPosition + normalize(worldNormal) * light.normalBias;
+  float visibility = shadow_arrayPCSS(spotShadowTexture, lightIndex,
+    shadow_project(shadow.spotViewProjectionMatrices[lightIndex], position),
+    light.sourceRadius / max(distanceToLight, 0.001) * 0.5,
+    shadow_hash(worldPosition) * 2.0 * SHADOW_PI, 16.0);
+  return mix(1.0, visibility, light.strength);
+}
+float shadow_pointReferenceDepth(float majorDistance, float nearPlane, float farPlane) {
+  return farPlane / (farPlane - nearPlane) - (farPlane * nearPlane) / ((farPlane - nearPlane) * majorDistance);
+}
+vec3 shadow_pointCoordinate(int lightIndex, vec3 direction) {
+  vec3 magnitude = abs(direction);
+  int face = magnitude.x >= magnitude.y && magnitude.x >= magnitude.z ? (direction.x >= 0.0 ? 0 : 1)
+    : magnitude.y >= magnitude.z ? (direction.y >= 0.0 ? 2 : 3) : (direction.z >= 0.0 ? 4 : 5);
+  PointShadowLightUniform light = shadow.pointLights[lightIndex];
+  vec3 projected = shadow_project(shadow.pointViewProjectionMatrices[lightIndex * 6 + face], light.position + direction * light.range * 0.5);
+  return vec3(projected.xy, float(lightIndex * 6 + face));
+}
+float shadow_getPointFactor(int lightIndex, vec3 worldPosition, vec3 worldNormal) {
+  if (lightIndex < 0 || lightIndex >= shadow.pointLightCount) return 1.0;
+  PointShadowLightUniform light = shadow.pointLights[lightIndex];
+  vec3 fromLight = worldPosition + normalize(worldNormal) * light.normalBias - light.position;
+  float distanceToLight = length(fromLight);
+  if (distanceToLight >= light.range || distanceToLight <= light.nearPlane) return 1.0;
+  vec3 direction = normalize(fromLight);
+  float referenceDepth = shadow_pointReferenceDepth(max(max(abs(fromLight.x), abs(fromLight.y)), abs(fromLight.z)), light.nearPlane, light.range);
+  vec3 reference = abs(direction.y) > 0.99 ? vec3(0,0,1) : vec3(0,1,0);
+  vec3 tangent = normalize(cross(direction, reference));
+  vec3 bitangent = normalize(cross(direction, tangent));
+  float searchRadius = light.sourceRadius / max(distanceToLight, 0.001);
+  float rotation = shadow_hash(worldPosition) * 2.0 * SHADOW_PI;
+  float blockerDepth = 0.0;
+  float blockerCount = 0.0;
+  for (int index = 0; index < 24; index++) {
+    if (index >= shadow.blockerSampleCount) break;
+    vec2 disk = shadow_diskSample(index, shadow.blockerSampleCount, rotation) * searchRadius;
+    vec3 coordinate = shadow_pointCoordinate(lightIndex, normalize(direction + tangent * disk.x + bitangent * disk.y));
+    float depth = textureLod(pointShadowTexture, coordinate, 0.0).r;
+    if (depth < referenceDepth) { blockerDepth += depth; blockerCount += 1.0; }
+  }
+  if (blockerCount == 0.0) return 1.0;
+  float averageBlocker = blockerDepth / blockerCount;
+  float penumbra = clamp((referenceDepth - averageBlocker) / max(abs(averageBlocker), 0.001), 0.0, 1.0);
+  float radius = searchRadius * (1.0 + penumbra * 12.0);
+  float visibility = 0.0;
+  for (int index = 0; index < 48; index++) {
+    if (index >= shadow.filterSampleCount) break;
+    vec2 disk = shadow_diskSample(index, shadow.filterSampleCount, rotation) * radius;
+    vec3 coordinate = shadow_pointCoordinate(lightIndex, normalize(direction + tangent * disk.x + bitangent * disk.y));
+    visibility += shadow_compare(pointShadowTexture, coordinate.xy, int(coordinate.z), referenceDepth);
+  }
+  return mix(1.0, visibility / max(float(shadow.filterSampleCount), 1.0), light.strength);
+}
+`;

package/src/modules/lighting/shadow/shadow-types.ts

@@ -0,0 +1,68 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {Matrix4, NumberArray3, NumberArray16} from '@math.gl/core';
+
+/** Minimal texture metadata used to select backend-specific sampler bindings. */
+export type ShadowTexture = {readonly device: {readonly type: string}};
+
+export type ShadowBiasProps = {
+  /** Receiver displacement along the world-space normal. */
+  normalBias?: number;
+  /** Constant raster depth bias applied by the caster pipeline. */
+  depthBias?: number;
+  /** Slope-scaled raster depth bias applied by the caster pipeline. */
+  depthBiasSlopeScale?: number;
+  /** Fraction of the direct-light contribution affected by the shadow. */
+  strength?: number;
+};
+
+/** Directional light shadow configuration. `direction` points from a surface toward the light. */
+export type DirectionalShadowLight = ShadowBiasProps & {
+  direction: Readonly<NumberArray3>;
+  shadowDistance?: number;
+  casterDistance?: number;
+  sourceAngularRadius?: number;
+  cascadeSplitLambda?: number;
+  cascadeBlendFraction?: number;
+  farFadeFraction?: number;
+};
+
+/** Perspective shadow configuration for a spot light. */
+export type SpotShadowLight = ShadowBiasProps & {
+  position: Readonly<NumberArray3>;
+  direction: Readonly<NumberArray3>;
+  range: number;
+  outerConeAngle: number;
+  nearPlane?: number;
+  sourceRadius?: number;
+};
+
+/** Cube-array shadow configuration for an omnidirectional point light. */
+export type PointShadowLight = ShadowBiasProps & {
+  position: Readonly<NumberArray3>;
+  range: number;
+  nearPlane?: number;
+  sourceRadius?: number;
+};
+
+/** Fully resolved props returned by the renderer and consumed by the `shadow` shader module. */
+export type ShadowProps<TextureT extends ShadowTexture = ShadowTexture, SamplerT = unknown> = {
+  quality: 'low' | 'balanced' | 'cinematic';
+  cascadeCount: number;
+  cascadeSplits: readonly number[];
+  blockerSampleCount: number;
+  filterSampleCount: number;
+  directionalLights: readonly DirectionalShadowLight[];
+  spotLights: readonly SpotShadowLight[];
+  pointLights: readonly PointShadowLight[];
+  directionalViewProjectionMatrices: readonly Readonly<Matrix4 | NumberArray16>[];
+  spotViewProjectionMatrices: readonly Readonly<Matrix4 | NumberArray16>[];
+  pointViewProjectionMatrices: readonly Readonly<Matrix4 | NumberArray16>[];
+  directionalShadowTexture: TextureT;
+  spotShadowTexture: TextureT;
+  pointShadowTexture: TextureT;
+  comparisonSampler: SamplerT;
+  nonFilteringSampler: SamplerT;
+};