@luma.gl/shadertools 9.2.5 → 9.3.0-alpha.10

package/src/modules/lighting/lights/lighting.ts

@@ -6,7 +6,7 @@ import {log} from '@luma.gl/core';
 import {ShaderModule} from '../../../lib/shader-module/shader-module';
 import {lightingUniformsGLSL} from './lighting-glsl';
 import {lightingUniformsWGSL} from './lighting-wgsl';
-import type {NumberArray3} from '@math.gl/core';
+import type {NumberArray2, NumberArray3} from '@math.gl/core';
 
 /** Max number of supported lights (in addition to ambient light */
 const MAX_LIGHTS = 5;
@@ -14,70 +14,137 @@ const MAX_LIGHTS = 5;
 /** Whether to divide */
 const COLOR_FACTOR = 255.0;
 
-/** Shader type field for lights */
-// eslint-disable-next-line no-shadow
-export enum LIGHT_TYPE {
-  POINT = 0,
-  DIRECTIONAL = 1
-}
-
-/** Lighting helper types */
-
-export type Light = AmbientLight | PointLight | DirectionalLight;
+/** Supported light source descriptions accepted by the lighting shader module. */
+export type Light = AmbientLight | PointLight | SpotLight | DirectionalLight;
 
+/** Ambient light contribution shared across the entire scene. */
 export type AmbientLight = {
+  /** Discriminator used to identify ambient lights in `lights: Light[]`. */
   type: 'ambient';
+  /** RGB light color in the existing `0..255` convention used by luma.gl materials. */
   color?: Readonly<NumberArray3>;
+  /** Scalar intensity multiplier applied to the light color. */
   intensity?: number;
 };
 
+/** Omnidirectional point light emitted from a world-space position. */
 export type PointLight = {
+  /** Discriminator used to identify point lights in `lights: Light[]`. */
   type: 'point';
+  /** World-space light position. */
   position: Readonly<NumberArray3>;
+  /** RGB light color in the existing `0..255` convention used by luma.gl materials. */
   color?: Readonly<NumberArray3>;
+  /** Scalar intensity multiplier applied to the light color. */
   intensity?: number;
+  /** Constant, linear, and quadratic attenuation coefficients. */
   attenuation?: Readonly<NumberArray3>;
 };
 
+/** Directional light defined only by its incoming world-space direction. */
 export type DirectionalLight = {
+  /** Discriminator used to identify directional lights in `lights: Light[]`. */
   type: 'directional';
+  /** World-space light direction. */
   direction: Readonly<NumberArray3>;
+  /** RGB light color in the existing `0..255` convention used by luma.gl materials. */
   color?: Readonly<NumberArray3>;
+  /** Scalar intensity multiplier applied to the light color. */
   intensity?: number;
 };
 
+/** Cone-shaped light emitted from a position and focused along a direction. */
+export type SpotLight = {
+  /** Discriminator used to identify spot lights in `lights: Light[]`. */
+  type: 'spot';
+  /** World-space light position. */
+  position: Readonly<NumberArray3>;
+  /** World-space light direction. */
+  direction: Readonly<NumberArray3>;
+  /** RGB light color in the existing `0..255` convention used by luma.gl materials. */
+  color?: Readonly<NumberArray3>;
+  /** Scalar intensity multiplier applied to the light color. */
+  intensity?: number;
+  /** Constant, linear, and quadratic attenuation coefficients. */
+  attenuation?: Readonly<NumberArray3>;
+  /** Inner spotlight cone angle in radians. */
+  innerConeAngle?: number;
+  /** Outer spotlight cone angle in radians. */
+  outerConeAngle?: number;
+};
+
+/** Public JavaScript props accepted by the `lighting` shader module. */
 export type LightingProps = {
+  /** Enables or disables lighting calculations for the module. */
   enabled?: boolean;
+  /** Preferred API for supplying mixed ambient, point, spot, and directional lights. */
   lights?: Light[];
-  /** @deprecated */
+  /**
+   * Legacy ambient-light prop.
+   * @deprecated Use `lights` with `{type: 'ambient', ...}` entries instead.
+   */
   ambientLight?: AmbientLight;
-  /** @deprecated */
+  /**
+   * Legacy point-light prop.
+   * @deprecated Use `lights` with `{type: 'point', ...}` entries instead.
+   */
   pointLights?: PointLight[];
-  /** @deprecated */
+  /**
+   * Legacy spot-light prop.
+   * @deprecated Use `lights` with `{type: 'spot', ...}` entries instead.
+   */
+  spotLights?: SpotLight[];
+  /**
+   * Legacy directional-light prop.
+   * @deprecated Use `lights` with `{type: 'directional', ...}` entries instead.
+   */
   directionalLights?: DirectionalLight[];
 };
 
+/** Packed per-light data written into the module's fixed-size uniform array. */
+export type LightingLightUniform = {
+  /** Light color converted to normalized shader-space RGB. */
+  color: Readonly<NumberArray3>;
+  /** World-space light position or a default placeholder for non-positional lights. */
+  position: Readonly<NumberArray3>;
+  /** World-space light direction or a default placeholder for positional lights. */
+  direction: Readonly<NumberArray3>;
+  /** Constant, linear, and quadratic attenuation coefficients. */
+  attenuation: Readonly<NumberArray3>;
+  /** Cosines of the inner and outer spotlight cone angles. */
+  coneCos: Readonly<NumberArray2>;
+};
+
+/** Fully normalized uniform values produced by the `lighting` shader module. */
 export type LightingUniforms = {
+  /** `1` when lighting is enabled, otherwise `0`. */
   enabled: number;
-  ambientColor: Readonly<NumberArray3>;
+  /** Number of packed directional lights in the `lights` array. */
   directionalLightCount: number;
+  /** Number of packed point lights in the `lights` array. */
   pointLightCount: number;
-  lightType: number; // [];
-  lightColor0: Readonly<NumberArray3>;
-  lightPosition0: Readonly<NumberArray3>;
-  lightDirection0: Readonly<NumberArray3>;
-  lightAttenuation0: Readonly<NumberArray3>;
-  lightColor1: Readonly<NumberArray3>;
-  lightPosition1: Readonly<NumberArray3>;
-  lightDirection1: Readonly<NumberArray3>;
-  lightAttenuation1: Readonly<NumberArray3>;
-  lightColor2: Readonly<NumberArray3>;
-  lightPosition2: Readonly<NumberArray3>;
-  lightDirection2: Readonly<NumberArray3>;
-  lightAttenuation2: Readonly<NumberArray3>;
+  /** Number of packed spot lights in the `lights` array. */
+  spotLightCount: number;
+  /** Accumulated ambient color converted to normalized shader-space RGB. */
+  ambientColor: Readonly<NumberArray3>;
+  /** Packed trailing array of non-ambient light structs. */
+  lights: ReadonlyArray<LightingLightUniform>;
 };
 
-/** UBO ready lighting module */
+const LIGHT_UNIFORM_TYPE = {
+  color: 'vec3<f32>',
+  position: 'vec3<f32>',
+  direction: 'vec3<f32>',
+  attenuation: 'vec3<f32>',
+  coneCos: 'vec2<f32>'
+} as const;
+
+/**
+ * Portable lighting shader module shared by the Phong, Gouraud, and PBR material modules.
+ *
+ * The public JavaScript API accepts `lights: Light[]`, while the uniform buffer packs
+ * non-ambient lights into a fixed-size trailing array for portability across WebGL2 and WebGPU.
+ */
 export const lighting = {
   props: {} as LightingProps,
   uniforms: {} as LightingUniforms,
@@ -90,53 +157,16 @@ export const lighting = {
 
   uniformTypes: {
     enabled: 'i32',
-    lightType: 'i32',
-
     directionalLightCount: 'i32',
     pointLightCount: 'i32',
-
+    spotLightCount: 'i32',
     ambientColor: 'vec3<f32>',
-
-    // TODO define as arrays once we have appropriate uniformTypes
-    lightColor0: 'vec3<f32>',
-    lightPosition0: 'vec3<f32>',
-    // TODO - could combine direction and attenuation
-    lightDirection0: 'vec3<f32>',
-    lightAttenuation0: 'vec3<f32>',
-
-    lightColor1: 'vec3<f32>',
-    lightPosition1: 'vec3<f32>',
-    lightDirection1: 'vec3<f32>',
-    lightAttenuation1: 'vec3<f32>',
-    lightColor2: 'vec3<f32>',
-    lightPosition2: 'vec3<f32>',
-    lightDirection2: 'vec3<f32>',
-    lightAttenuation2: 'vec3<f32>'
+    lights: [LIGHT_UNIFORM_TYPE, MAX_LIGHTS]
   },
 
-  defaultUniforms: {
-    enabled: 1,
-    lightType: LIGHT_TYPE.POINT,
-
-    directionalLightCount: 0,
-    pointLightCount: 0,
-
-    ambientColor: [0.1, 0.1, 0.1],
-    lightColor0: [1, 1, 1],
-    lightPosition0: [1, 1, 2],
-    // TODO - could combine direction and attenuation
-    lightDirection0: [1, 1, 1],
-    lightAttenuation0: [1, 0, 0],
-
-    lightColor1: [1, 1, 1],
-    lightPosition1: [1, 1, 2],
-    lightDirection1: [1, 1, 1],
-    lightAttenuation1: [1, 0, 0],
-    lightColor2: [1, 1, 1],
-    lightPosition2: [1, 1, 2],
-    lightDirection2: [1, 1, 1],
-    lightAttenuation2: [1, 0, 0]
-  },
+  defaultUniforms: createDefaultLightingUniforms(),
+  bindingLayout: [{name: 'lighting', group: 2}],
+  firstBindingSlot: 0,
   source: lightingUniformsWGSL,
   vs: lightingUniformsGLSL,
   fs: lightingUniformsGLSL,
@@ -146,14 +176,14 @@ export const lighting = {
 
 function getUniforms(
   props?: LightingProps,
-  prevUniforms: Partial<LightingUniforms> = {}
+  _prevUniforms: Partial<LightingUniforms> = {}
 ): LightingUniforms {
   // Copy props so we can modify
   props = props ? {...props} : props;
 
   // TODO legacy
   if (!props) {
-    return {...lighting.defaultUniforms};
+    return createDefaultLightingUniforms();
   }
   // Support for array of lights. Type of light is detected by type field
   if (props.lights) {
@@ -161,21 +191,24 @@ function getUniforms(
   }
 
   // Specify lights separately
-  const {ambientLight, pointLights, directionalLights} = props || {};
+  const {ambientLight, pointLights, spotLights, directionalLights} = props || {};
   const hasLights =
     ambientLight ||
     (pointLights && pointLights.length > 0) ||
+    (spotLights && spotLights.length > 0) ||
     (directionalLights && directionalLights.length > 0);
 
   // TODO - this may not be the correct decision
   if (!hasLights) {
-    return {...lighting.defaultUniforms, enabled: 0};
+    return {
+      ...createDefaultLightingUniforms(),
+      enabled: 0
+    };
   }
 
   const uniforms = {
-    ...lighting.defaultUniforms,
-    ...prevUniforms,
-    ...getLightSourceUniforms({ambientLight, pointLights, directionalLights})
+    ...createDefaultLightingUniforms(),
+    ...getLightSourceUniforms({ambientLight, pointLights, spotLights, directionalLights})
   };
 
   if (props.enabled !== undefined) {
@@ -188,45 +221,77 @@ function getUniforms(
 function getLightSourceUniforms({
   ambientLight,
   pointLights = [],
+  spotLights = [],
   directionalLights = []
-}: LightingProps): Partial<LightingUniforms> {
-  const lightSourceUniforms: Partial<LightingUniforms> = {};
+}: LightingProps): Omit<LightingUniforms, 'enabled'> {
+  const lights = createDefaultLightUniforms();
 
-  lightSourceUniforms.ambientColor = convertColor(ambientLight);
-
-  let currentLight: 0 | 1 | 2 = 0;
+  let currentLight = 0;
+  let pointLightCount = 0;
+  let spotLightCount = 0;
+  let directionalLightCount = 0;
 
   for (const pointLight of pointLights) {
-    lightSourceUniforms.lightType = LIGHT_TYPE.POINT;
+    if (currentLight >= MAX_LIGHTS) {
+      break;
+    }
 
-    const i = currentLight as 0 | 1 | 2;
-    lightSourceUniforms[`lightColor${i}`] = convertColor(pointLight);
-    lightSourceUniforms[`lightPosition${i}`] = pointLight.position;
-    lightSourceUniforms[`lightAttenuation${i}`] = pointLight.attenuation || [1, 0, 0];
+    lights[currentLight] = {
+      ...lights[currentLight],
+      color: convertColor(pointLight),
+      position: pointLight.position,
+      attenuation: pointLight.attenuation || [1, 0, 0]
+    };
     currentLight++;
+    pointLightCount++;
   }
 
-  for (const directionalLight of directionalLights) {
-    lightSourceUniforms.lightType = LIGHT_TYPE.DIRECTIONAL;
+  for (const spotLight of spotLights) {
+    if (currentLight >= MAX_LIGHTS) {
+      break;
+    }
 
-    const i = currentLight as 0 | 1 | 2;
-    lightSourceUniforms[`lightColor${i}`] = convertColor(directionalLight);
-    lightSourceUniforms[`lightDirection${i}`] = directionalLight.direction;
+    lights[currentLight] = {
+      ...lights[currentLight],
+      color: convertColor(spotLight),
+      position: spotLight.position,
+      direction: spotLight.direction,
+      attenuation: spotLight.attenuation || [1, 0, 0],
+      coneCos: getSpotConeCos(spotLight)
+    };
     currentLight++;
+    spotLightCount++;
   }
 
-  if (currentLight > MAX_LIGHTS) {
-    log.warn('MAX_LIGHTS exceeded')();
+  for (const directionalLight of directionalLights) {
+    if (currentLight >= MAX_LIGHTS) {
+      break;
+    }
+
+    lights[currentLight] = {
+      ...lights[currentLight],
+      color: convertColor(directionalLight),
+      direction: directionalLight.direction
+    };
+    currentLight++;
+    directionalLightCount++;
   }
 
-  lightSourceUniforms.directionalLightCount = directionalLights.length;
-  lightSourceUniforms.pointLightCount = pointLights.length;
+  if (pointLights.length + spotLights.length + directionalLights.length > MAX_LIGHTS) {
+    log.warn(`MAX_LIGHTS exceeded, truncating to ${MAX_LIGHTS}`)();
+  }
 
-  return lightSourceUniforms;
+  return {
+    ambientColor: convertColor(ambientLight),
+    directionalLightCount,
+    pointLightCount,
+    spotLightCount,
+    lights
+  };
 }
 
 function extractLightTypes(lights: Light[]): LightingProps {
-  const lightSources: LightingProps = {pointLights: [], directionalLights: []};
+  const lightSources: LightingProps = {pointLights: [], spotLights: [], directionalLights: []};
   for (const light of lights || []) {
     switch (light.type) {
       case 'ambient':
@@ -240,6 +305,9 @@ function extractLightTypes(lights: Light[]): LightingProps {
       case 'point':
         lightSources.pointLights?.push(light);
         break;
+      case 'spot':
+        lightSources.spotLights?.push(light);
+        break;
       default:
       // eslint-disable-next-line
       // console.warn(light.type);
@@ -255,3 +323,34 @@ function convertColor(
   const {color = [0, 0, 0], intensity = 1.0} = colorDef;
   return color.map(component => (component * intensity) / COLOR_FACTOR) as NumberArray3;
 }
+
+function createDefaultLightingUniforms(): LightingUniforms {
+  return {
+    enabled: 1,
+    directionalLightCount: 0,
+    pointLightCount: 0,
+    spotLightCount: 0,
+    ambientColor: [0.1, 0.1, 0.1],
+    lights: createDefaultLightUniforms()
+  };
+}
+
+function createDefaultLightUniforms(): LightingLightUniform[] {
+  return Array.from({length: MAX_LIGHTS}, () => createDefaultLightUniform());
+}
+
+function createDefaultLightUniform(): LightingLightUniform {
+  return {
+    color: [1, 1, 1],
+    position: [1, 1, 2],
+    direction: [1, 1, 1],
+    attenuation: [1, 0, 0],
+    coneCos: [1, 0]
+  };
+}
+
+function getSpotConeCos(spotLight: SpotLight): NumberArray2 {
+  const innerConeAngle = spotLight.innerConeAngle ?? 0;
+  const outerConeAngle = spotLight.outerConeAngle ?? Math.PI / 4;
+  return [Math.cos(innerConeAngle), Math.cos(outerConeAngle)];
+}

package/src/modules/lighting/no-material/dirlight.ts

@@ -23,7 +23,7 @@ struct DirlightInputs {
   normal: DirlightNormal,
 };
 
-@binding(1) @group(0) var<uniform> dirlight : dirlightUniforms;
+@group(2) @binding(auto) var<uniform> dirlight : dirlightUniforms;
 
 // For vertex
 fn dirlight_setNormal(normal: vec3<f32>) -> DirlightNormal {
@@ -49,7 +49,7 @@ void dirlight_setNormal(vec3 normal) {
 `;
 
 const FS_GLSL = /* glsl */ `\
-uniform dirlightUniforms {
+layout(std140) uniform dirlightUniforms {
   vec3 lightDirection;
 } dirlight;
 
@@ -70,6 +70,8 @@ export const dirlight = {
   uniforms: {} as DirlightUniforms,
 
   name: 'dirlight',
+  bindingLayout: [{name: 'dirlight', group: 2}],
+  firstBindingSlot: 16,
   dependencies: [],
   source: SOURCE_WGSL,
   vs: VS_GLSL,