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

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

@@ -0,0 +1,385 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {
+  type AreaLight,
+  type AreaLightUniform,
+  AREA_LIGHT_UNIFORM_TYPE,
+  MAX_AREA_LIGHTS,
+  packAreaLights
+} from '../area-lighting/area-light-types';
+import {ShaderModule} from '../../../lib/shader-module/shader-module';
+import {lightingUniformsGLSL} from './lighting-glsl';
+import {lightingUniformsWGSL} from './lighting-wgsl';
+import type {NumberArray2, NumberArray3} from '@math.gl/core';
+import {normalizeByteColor3, resolveUseByteColors} from '../../../lib/color/normalize-byte-colors';
+
+/** Max number of supported lights (in addition to ambient light */
+const MAX_LIGHTS = 5;
+
+/** Supported light source descriptions accepted by the lighting shader module. */
+export type Light = AmbientLight | PointLight | SpotLight | DirectionalLight | AreaLight;
+
+/** 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 direction in which light travels. */
+  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;
+  /** When true, light colors are interpreted as byte-style 0-255 values. */
+  useByteColors?: boolean;
+  /** Preferred API for supplying mixed ambient, point, spot, directional, rectangle, and disk lights. */
+  lights?: Light[];
+  /**
+   * Legacy ambient-light prop.
+   * @deprecated Use `lights` with `{type: 'ambient', ...}` entries instead.
+   */
+  ambientLight?: AmbientLight;
+  /**
+   * Legacy point-light prop.
+   * @deprecated Use `lights` with `{type: 'point', ...}` entries instead.
+   */
+  pointLights?: PointLight[];
+  /**
+   * 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;
+  /** Number of packed directional lights in the `lights` array. */
+  directionalLightCount: number;
+  /** Number of packed point lights in the `lights` array. */
+  pointLightCount: number;
+  /** 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>;
+  areaLightCount: number;
+  areaLights: readonly AreaLightUniform[];
+};
+
+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,
+
+  name: 'lighting',
+
+  defines: {
+    // MAX_LIGHTS
+  },
+
+  uniformTypes: {
+    enabled: 'i32',
+    directionalLightCount: 'i32',
+    pointLightCount: 'i32',
+    spotLightCount: 'i32',
+    ambientColor: 'vec3<f32>',
+    lights: [LIGHT_UNIFORM_TYPE, MAX_LIGHTS],
+    areaLightCount: 'i32',
+    areaLights: [AREA_LIGHT_UNIFORM_TYPE, MAX_AREA_LIGHTS]
+  },
+
+  defaultUniforms: createDefaultLightingUniforms(),
+  bindingLayout: [{name: 'lighting', group: 2}],
+  firstBindingSlot: 0,
+  source: lightingUniformsWGSL,
+  vs: lightingUniformsGLSL,
+  fs: lightingUniformsGLSL,
+
+  getUniforms
+} as const satisfies ShaderModule<LightingProps, LightingUniforms, {}>;
+
+function getUniforms(
+  props?: LightingProps,
+  _prevUniforms: Partial<LightingUniforms> = {}
+): LightingUniforms {
+  // Copy props so we can modify
+  props = props ? {...props} : props;
+
+  const areaLights = (props?.lights || []).filter(
+    (light): light is AreaLight => light.type === 'rect' || light.type === 'disk'
+  );
+
+  // TODO legacy
+  if (!props) {
+    return createDefaultLightingUniforms();
+  }
+  // Support for array of lights. Type of light is detected by type field
+  if (props.lights) {
+    props = {...props, ...extractLightTypes(props.lights), lights: undefined};
+  }
+
+  // Specify lights separately
+  const {useByteColors, 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 && areaLights.length === 0) {
+    return {
+      ...createDefaultLightingUniforms(),
+      enabled: 0
+    };
+  }
+
+  const uniforms = {
+    ...createDefaultLightingUniforms(),
+    ...getLightSourceUniforms({
+      useByteColors,
+      ambientLight,
+      pointLights,
+      spotLights,
+      directionalLights
+    })
+  };
+
+  uniforms.areaLightCount = Math.min(areaLights.length, MAX_AREA_LIGHTS);
+  uniforms.areaLights = packAreaLights(areaLights, resolveUseByteColors(props.useByteColors, true));
+
+  if (props.enabled !== undefined) {
+    uniforms.enabled = props.enabled ? 1 : 0;
+  }
+
+  return uniforms;
+}
+
+function getLightSourceUniforms({
+  useByteColors,
+  ambientLight,
+  pointLights = [],
+  spotLights = [],
+  directionalLights = []
+}: LightingProps): Omit<LightingUniforms, 'enabled' | 'areaLightCount' | 'areaLights'> {
+  const lights = createDefaultLightUniforms();
+
+  let currentLight = 0;
+  let pointLightCount = 0;
+  let spotLightCount = 0;
+  let directionalLightCount = 0;
+
+  for (const pointLight of pointLights) {
+    if (currentLight >= MAX_LIGHTS) {
+      break;
+    }
+
+    lights[currentLight] = {
+      ...lights[currentLight],
+      color: convertColor(pointLight, useByteColors),
+      position: pointLight.position,
+      attenuation: pointLight.attenuation || [1, 0, 0]
+    };
+    currentLight++;
+    pointLightCount++;
+  }
+
+  for (const spotLight of spotLights) {
+    if (currentLight >= MAX_LIGHTS) {
+      break;
+    }
+
+    lights[currentLight] = {
+      ...lights[currentLight],
+      color: convertColor(spotLight, useByteColors),
+      position: spotLight.position,
+      direction: spotLight.direction,
+      attenuation: spotLight.attenuation || [1, 0, 0],
+      coneCos: getSpotConeCos(spotLight)
+    };
+    currentLight++;
+    spotLightCount++;
+  }
+
+  for (const directionalLight of directionalLights) {
+    if (currentLight >= MAX_LIGHTS) {
+      break;
+    }
+
+    lights[currentLight] = {
+      ...lights[currentLight],
+      color: convertColor(directionalLight, useByteColors),
+      direction: directionalLight.direction
+    };
+    currentLight++;
+    directionalLightCount++;
+  }
+
+  if (pointLights.length + spotLights.length + directionalLights.length > MAX_LIGHTS) {
+    // biome-ignore lint/suspicious/noConsole: preserve the standalone module warning without a core logger.
+    console.warn(`MAX_LIGHTS exceeded, truncating to ${MAX_LIGHTS}`);
+  }
+
+  return {
+    ambientColor: convertColor(ambientLight, useByteColors),
+    directionalLightCount,
+    pointLightCount,
+    spotLightCount,
+    lights
+  };
+}
+
+function extractLightTypes(lights: Light[]): LightingProps {
+  const lightSources: LightingProps = {pointLights: [], spotLights: [], directionalLights: []};
+  for (const light of lights || []) {
+    switch (light.type) {
+      case 'ambient':
+        // Note: Only uses last ambient light
+        // TODO - add ambient light sources on CPU?
+        lightSources.ambientLight = light;
+        break;
+      case 'directional':
+        lightSources.directionalLights?.push(light);
+        break;
+      case 'point':
+        lightSources.pointLights?.push(light);
+        break;
+      case 'spot':
+        lightSources.spotLights?.push(light);
+        break;
+      default:
+      // eslint-disable-next-line
+      // console.warn(light.type);
+    }
+  }
+  return lightSources;
+}
+
+/** Take color 0-255 and intensity as input and output 0.0-1.0 range */
+function convertColor(
+  colorDef: {color?: Readonly<NumberArray3>; intensity?: number} = {},
+  useByteColors?: boolean
+): NumberArray3 {
+  const {color = [0, 0, 0], intensity = 1.0} = colorDef;
+  const normalizedColor = normalizeByteColor3(color, resolveUseByteColors(useByteColors, true));
+  return normalizedColor.map(component => component * intensity) as NumberArray3;
+}
+
+function createDefaultLightingUniforms(): LightingUniforms {
+  return {
+    enabled: 1,
+    directionalLightCount: 0,
+    pointLightCount: 0,
+    spotLightCount: 0,
+    ambientColor: [0.1, 0.1, 0.1],
+    lights: createDefaultLightUniforms(),
+    areaLightCount: 0,
+    areaLights: packAreaLights([])
+  };
+}
+
+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

@@ -0,0 +1,101 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {NumberArray3} from '@math.gl/core';
+import {ShaderModule} from '../../../lib/shader-module/shader-module';
+
+export type DirlightProps = {
+  lightDirection?: NumberArray3;
+};
+
+export type DirlightUniforms = DirlightProps;
+
+// TODO
+export const SOURCE_WGSL = /* WGSL */ `\
+struct dirlightUniforms {
+  lightDirection: vec3<f32>,
+};
+
+alias DirlightNormal = vec3<f32>;
+
+struct DirlightInputs {
+  normal: DirlightNormal,
+};
+
+@group(2) @binding(auto) var<uniform> dirlight : dirlightUniforms;
+
+// For vertex
+fn dirlight_setNormal(normal: vec3<f32>) -> DirlightNormal {
+  return normalize(normal);
+}
+
+// Returns color attenuated by angle from light source
+fn dirlight_filterColor(color: vec4<f32>, inputs: DirlightInputs) -> vec4<f32> {
+  // TODO - fix default light direction
+  // let lightDirection = dirlight.lightDirection;
+  let lightDirection = vec3<f32>(1, 1, 1);
+  let d: f32 = abs(dot(inputs.normal, normalize(lightDirection)));
+  return vec4<f32>(color.rgb * d, color.a);
+}
+`;
+
+const VS_GLSL = /* glsl */ `\
+out vec3 dirlight_vNormal;
+
+void dirlight_setNormal(vec3 normal) {
+  dirlight_vNormal = normalize(normal);
+}
+`;
+
+const FS_GLSL = /* glsl */ `\
+layout(std140) uniform dirlightUniforms {
+  vec3 lightDirection;
+} dirlight;
+
+in vec3 dirlight_vNormal;
+
+// Returns color attenuated by angle from light source
+vec4 dirlight_filterColor(vec4 color) {
+  float d = abs(dot(dirlight_vNormal, normalize(dirlight.lightDirection)));
+  return vec4(color.rgb * d, color.a);
+}
+`;
+
+/**
+ * Cheap lighting - single directional light, single dot product, one uniform
+ */
+export const dirlight = {
+  props: {} as DirlightProps,
+  uniforms: {} as DirlightUniforms,
+
+  name: 'dirlight',
+  bindingLayout: [{name: 'dirlight', group: 2}],
+  firstBindingSlot: 16,
+  dependencies: [],
+  source: SOURCE_WGSL,
+  vs: VS_GLSL,
+  fs: FS_GLSL,
+
+  // fragmentInputs: [
+  //   {
+  //     name: 'dirlight_vNormal',
+  //     type: 'vec3<f32>'
+  //   }
+  // ],
+  uniformTypes: {
+    lightDirection: 'vec3<f32>'
+  },
+  defaultUniforms: {
+    lightDirection: [1, 1, 2]
+  },
+  getUniforms
+} as const satisfies ShaderModule<DirlightProps, DirlightUniforms>;
+
+function getUniforms(opts: DirlightProps = dirlight.defaultUniforms): DirlightUniforms {
+  const uniforms: DirlightUniforms = {};
+  if (opts.lightDirection) {
+    uniforms.lightDirection = opts.lightDirection;
+  }
+  return uniforms;
+}