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

package/src/modules/lighting/clouds/README.md

@@ -0,0 +1,24 @@
+# clouds
+
+Procedural, wind-driven sky clouds for GLSL and WGSL. The module uses shared `valueNoise` and
+returns premultiplied RGBA from `clouds_getColor(camera, normalizedRayDirection)`.
+Camera positions, slab dimensions, and velocity use a local east/north/up metre frame.
+
+The cloud slab starts at `altitude`, extends through `thickness`, and uses `scale` for the
+horizontal size of formations. `cover` ranges from clear (0) to overcast (1); `density`
+controls extinction per metre. Set `time` in seconds and `velocity` in east/north metres per
+second. The shader adds gradual shape evolution independently of advection. `sunDirection`
+points toward the sun; `sunColor` is linear RGB. The direction must be nonzero.
+
+A fixed 64-sample march integrates density through the slab, with approximate local sunlight
+attenuation and a forward-scattering highlight. The horizon fades at long distances. There
+are no cloud shadow maps, temporal accumulation, or atmospheric multiple scattering.
+`clouds_getTransmittance(position)` integrates sunlight extinction through that same density
+field with sixteen midpoint samples. Multiply direct sunlight by this factor, preserving
+ambient illumination. It returns one for clear/zero-density clouds and sun elevation at or
+below approximately 1.1 degrees. Sky and receivers must share the origin, dimensions, time and wind.
+The light march caps at 40 km, limiting cost and low-sun precision. It does not create
+shadow-map resources or implement terrain/volume shadowing. The
+caller supplies world-space camera rays, composites over the sky, and arranges foreground
+occlusion. `CloudLayer` in the deck.gl adapter provides this integration for perspective
+flat-map views. Cloud render cost scales with visible sky area.

package/src/modules/lighting/clouds/clouds.ts

@@ -0,0 +1,216 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ShaderModule} from '../../../lib/shader-module/shader-module';
+import {valueNoise} from '../../math/value-noise/value-noise';
+
+export type CloudUniforms = {
+  /** Fractional cloud cover, from clear (0) to overcast (1). */
+  cover: number;
+  /** Bottom and thickness of the cloud slab, in metres above the coordinate origin. */
+  altitude: number;
+  thickness: number;
+  /** Horizontal size of cloud formations, in metres. */
+  scale: number;
+  /** Extinction coefficient, in inverse metres. */
+  density: number;
+  /** Elapsed seconds; callers own animation. */
+  time: number;
+  /** East/north drift velocity in metres per second. */
+  velocity: [number, number];
+  /** Direction toward the sun in east/north/up coordinates; nonzero. */
+  sunDirection: [number, number, number];
+  /** Linear sunlight tint. */
+  sunColor: [number, number, number];
+};
+export type CloudProps = Partial<CloudUniforms>;
+
+const DEFAULT_UNIFORMS: CloudUniforms = {
+  cover: 0.45,
+  altitude: 1000,
+  thickness: 1200,
+  scale: 1400,
+  density: 0.005,
+  time: 0,
+  velocity: [14, 4],
+  sunDirection: [0, 0.8, 0.6],
+  sunColor: [1, 0.95, 0.85]
+};
+
+/** Sixty-four-sample cloud slab with approximate sunlight scattering. Returns premultiplied RGBA.
+ * Positions/directions use a local east/north/up frame, with lengths in metres.
+ * Receivers can sample clouds_getTransmittance to attenuate direct sunlight.
+ */
+export const clouds = {
+  name: 'clouds',
+  dependencies: [valueNoise],
+  uniformTypes: {
+    cover: 'f32',
+    altitude: 'f32',
+    thickness: 'f32',
+    scale: 'f32',
+    density: 'f32',
+    time: 'f32',
+    velocity: 'vec2<f32>',
+    sunDirection: 'vec3<f32>',
+    sunColor: 'vec3<f32>'
+  },
+  defaultUniforms: DEFAULT_UNIFORMS,
+  getUniforms(props = {}, previousUniforms = DEFAULT_UNIFORMS) {
+    return {...DEFAULT_UNIFORMS, ...previousUniforms, ...props};
+  },
+  fs: /* glsl */ `
+layout(std140) uniform cloudsUniforms {
+  float cover;
+  float altitude;
+  float thickness;
+  float scale;
+  float density;
+  float time;
+  vec2 velocity;
+  vec3 sunDirection;
+  vec3 sunColor;
+} clouds;
+// Shared normalized density field for planar slabs and spherical shells.
+float clouds_getDensityAt(vec3 coordinate, float height) {
+  float envelope = smoothstep(0.0, 0.2, height) * (1.0 - smoothstep(0.65, 1.0, height));
+  coordinate += vec3(8.7, 3.2, clouds.time * 0.003);
+  float broad = valueNoise_noise3(coordinate);
+  float detail = valueNoise_noise3(coordinate * 2.07 + vec3(13.1, 7.3, 2.8));
+  float fine = valueNoise_noise3(coordinate * 4.23 + vec3(5.4, 11.7, 8.1));
+  float threshold = mix(0.78, 0.18, clamp(clouds.cover, 0.0, 1.0));
+  return envelope * smoothstep(threshold, threshold + 0.16, broad * 0.72 + detail * 0.2 + fine * 0.08);
+}
+
+float clouds_getDensity(vec3 position) {
+  float height = (position.z - clouds.altitude) / max(clouds.thickness, 1.0);
+  return clouds_getDensityAt(vec3((position.xy - clouds.velocity * clouds.time) / max(clouds.scale, 1.0), height * 0.8), height);
+}
+vec3 clouds_getLighting(float density, float sunDensity, float daylight, float silver) {
+  vec3 ambient = mix(vec3(0.035, 0.05, 0.085), vec3(0.28, 0.34, 0.42), daylight);
+  float sunlight = exp(-(density + sunDensity) * 2.0);
+  return ambient + clouds.sunColor * daylight * sunlight * (0.5 + silver * 0.3);
+}
+
+// Beer-Lambert extinction toward the sun through the same density used for sky rendering.
+float clouds_getTransmittance(vec3 position) {
+  if (clouds.cover <= 0.0 || clouds.density <= 0.0) return 1.0;
+  vec3 direction = normalize(clouds.sunDirection);
+  if (direction.z <= 0.02) return 1.0;
+  float start = max((clouds.altitude - position.z) / direction.z, 0.0);
+  float end = min((clouds.altitude + clouds.thickness - position.z) / direction.z, 40000.0);
+  if (end <= start) return 1.0;
+  float stepLength = (end - start) / 16.0;
+  float opticalDepth = 0.0;
+  for (int sampleIndex = 0; sampleIndex < 16; sampleIndex++) {
+    opticalDepth += clouds_getDensity(position + direction * (start + (float(sampleIndex) + 0.5) * stepLength)) * stepLength;
+  }
+  return exp(-opticalDepth * max(clouds.density, 0.0));
+}
+
+vec4 clouds_getColor(vec3 camera, vec3 rayDirection) {
+  if (clouds.cover <= 0.0 || clouds.density <= 0.0 || abs(rayDirection.z) < 0.0001) return vec4(0.0);
+  float bottom = (clouds.altitude - camera.z) / rayDirection.z;
+  float top = (clouds.altitude + max(clouds.thickness, 1.0) - camera.z) / rayDirection.z;
+  float start = max(min(bottom, top), 0.0);
+  float end = min(max(bottom, top), 20000.0);
+  if (end <= start) return vec4(0.0);
+  float jitter = valueNoise_hash(rayDirection.xy * 4096.0);
+  float stepLength = (end - start) / 64.0;
+  vec3 sunDirection = normalize(clouds.sunDirection);
+  float daylight = smoothstep(-0.08, 0.18, sunDirection.z);
+  float silver = pow(max(dot(rayDirection, sunDirection), 0.0), 12.0);
+  vec3 radiance = vec3(0.0);
+  float transmittance = 1.0;
+  for (int sampleIndex = 0; sampleIndex < 64; sampleIndex++) {
+    vec3 position = camera + rayDirection * (start + (float(sampleIndex) + jitter) * stepLength);
+    float density = clouds_getDensity(position);
+    float sunDensity = clouds_getDensity(position + sunDirection * clouds.thickness * 0.28);
+    float alpha = 1.0 - exp(-density * max(clouds.density, 0.0) * stepLength);
+    vec3 color = clouds_getLighting(density, sunDensity, daylight, silver);
+    radiance += transmittance * alpha * color;
+    transmittance *= 1.0 - alpha;
+  }
+  float distanceFade = 1.0 - smoothstep(10000.0, 20000.0, start);
+  return vec4(radiance, 1.0 - transmittance) * distanceFade;
+}
+`,
+  source: /* wgsl */ `
+struct cloudsUniforms {
+  cover: f32,
+  altitude: f32,
+  thickness: f32,
+  scale: f32,
+  density: f32,
+  time: f32,
+  velocity: vec2f,
+  sunDirection: vec3f,
+  sunColor: vec3f,
+};
+@group(3) @binding(auto) var<uniform> clouds: cloudsUniforms;
+fn clouds_getDensityAt(inputCoordinate: vec3f, height: f32) -> f32 {
+  let envelope = smoothstep(0.0, 0.2, height) * (1.0 - smoothstep(0.65, 1.0, height));
+  var coordinate = inputCoordinate;
+  coordinate += vec3f(8.7, 3.2, clouds.time * 0.003);
+  let broad = valueNoise_noise3(coordinate);
+  let detail = valueNoise_noise3(coordinate * 2.07 + vec3f(13.1, 7.3, 2.8));
+  let fine = valueNoise_noise3(coordinate * 4.23 + vec3f(5.4, 11.7, 8.1));
+  let threshold = mix(0.78, 0.18, clamp(clouds.cover, 0.0, 1.0));
+  return envelope * smoothstep(threshold, threshold + 0.16, broad * 0.72 + detail * 0.2 + fine * 0.08);
+}
+
+fn clouds_getDensity(position: vec3f) -> f32 {
+  let height = (position.z - clouds.altitude) / max(clouds.thickness, 1.0);
+  return clouds_getDensityAt(vec3f((position.xy - clouds.velocity * clouds.time) / max(clouds.scale, 1.0), height * 0.8), height);
+}
+fn clouds_getLighting(density: f32, sunDensity: f32, daylight: f32, silver: f32) -> vec3f {
+  let ambient = mix(vec3f(0.035, 0.05, 0.085), vec3f(0.28, 0.34, 0.42), daylight);
+  let sunlight = exp(-(density + sunDensity) * 2.0);
+  return ambient + clouds.sunColor * daylight * sunlight * (0.5 + silver * 0.3);
+}
+
+// Beer-Lambert extinction toward the sun through the same density used for sky rendering.
+fn clouds_getTransmittance(position: vec3f) -> f32 {
+  if (clouds.cover <= 0.0 || clouds.density <= 0.0) { return 1.0; }
+  var direction: vec3f = normalize(clouds.sunDirection);
+  if (direction.z <= 0.02) { return 1.0; }
+  var start: f32 = max((clouds.altitude - position.z) / direction.z, 0.0);
+  var end: f32 = min((clouds.altitude + clouds.thickness - position.z) / direction.z, 40000.0);
+  if (end <= start) { return 1.0; }
+  var stepLength: f32 = (end - start) / 16.0;
+  var opticalDepth: f32 = 0.0;
+  for (var sampleIndex: i32 = 0; sampleIndex < 16; sampleIndex++) {
+    opticalDepth += clouds_getDensity(position + direction * (start + (f32(sampleIndex) + 0.5) * stepLength)) * stepLength;
+  }
+  return exp(-opticalDepth * max(clouds.density, 0.0));
+}
+
+fn clouds_getColor(camera: vec3f, rayDirection: vec3f) -> vec4f {
+  if (clouds.cover <= 0.0 || clouds.density <= 0.0 || abs(rayDirection.z) < 0.0001) { return vec4f(0.0); }
+  let bottom = (clouds.altitude - camera.z) / rayDirection.z;
+  let top = (clouds.altitude + max(clouds.thickness, 1.0) - camera.z) / rayDirection.z;
+  let start = max(min(bottom, top), 0.0);
+  let end = min(max(bottom, top), 20000.0);
+  if (end <= start) { return vec4f(0.0); }
+  let jitter = valueNoise_hash(rayDirection.xy * 4096.0);
+  let stepLength = (end - start) / 64.0;
+  let sunDirection = normalize(clouds.sunDirection);
+  let daylight = smoothstep(-0.08, 0.18, sunDirection.z);
+  let silver = pow(max(dot(rayDirection, sunDirection), 0.0), 12.0);
+  var radiance = vec3f(0.0);
+  var transmittance = 1.0;
+  for (var sampleIndex = 0; sampleIndex < 64; sampleIndex++) {
+    let position = camera + rayDirection * (start + (f32(sampleIndex) + jitter) * stepLength);
+    let density = clouds_getDensity(position);
+    let sunDensity = clouds_getDensity(position + sunDirection * clouds.thickness * 0.28);
+    let alpha = 1.0 - exp(-density * max(clouds.density, 0.0) * stepLength);
+    let color = clouds_getLighting(density, sunDensity, daylight, silver);
+    radiance += transmittance * alpha * color;
+    transmittance *= 1.0 - alpha;
+  }
+  let distanceFade = 1.0 - smoothstep(10000.0, 20000.0, start);
+  return vec4f(radiance, 1.0 - transmittance) * distanceFade;
+}
+`
+} as const satisfies ShaderModule<CloudProps, CloudUniforms>;

package/src/modules/lighting/firefly/firefly.ts

@@ -0,0 +1,64 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ShaderModule} from '../../../lib/shader-module/shader-module';
+
+export type FireflyProps = {
+  enabled?: number;
+  time?: number;
+  radius?: number;
+  speed?: number;
+  pulse?: number;
+};
+export type FireflyUniforms = Required<FireflyProps>;
+const uniforms = {enabled: 0, time: 0, radius: 8, speed: 0.6, pulse: 0.85};
+
+/** Seeded smooth wandering and independently phased bioluminescence. Positions are in metres. */
+export const firefly = {
+  name: 'firefly',
+  uniformTypes: {enabled: 'f32', time: 'f32', radius: 'f32', speed: 'f32', pulse: 'f32'},
+  defaultUniforms: uniforms,
+  getUniforms(props = {}, previous = uniforms) {
+    return {...uniforms, ...previous, ...props};
+  },
+  source: `struct FireflyUniforms {enabled: f32, time: f32, radius: f32, speed: f32, pulse: f32};
+  @group(3) @binding(auto) var<uniform> firefly: FireflyUniforms;
+  fn firefly_getPosition(position: vec3f, seed: f32, time: f32) -> vec3f {
+    if (firefly.enabled <= 0.0) { return position; }
+    let phase = seed * 2.399963;
+    let travel = time * firefly.speed;
+    let offset = vec3f(sin(travel * 0.71 + phase) + sin(travel * 1.31 + phase * 1.7) * 0.35,
+      cos(travel * 0.83 + phase * 1.2) + sin(travel * 0.47 + phase * 2.3) * 0.4,
+      sin(travel * 0.59 + phase * 1.9) * 0.3);
+    return position + offset * firefly.radius * firefly.enabled;
+  }
+  fn firefly_getBrightness(seed: f32, time: f32) -> f32 {
+    if (firefly.enabled <= 0.0) { return 1.0; }
+    let phase = seed * 2.399963;
+    let pulse = pow(0.5 + 0.5 * sin(time * firefly.speed * (1.6 + fract(seed * 0.37)) + phase), 3.0);
+    return mix(1.0, mix(0.08, 1.0, pulse), firefly.pulse * firefly.enabled);
+  }`,
+  vs: `layout(std140) uniform fireflyUniforms {
+    float enabled;
+    float time;
+    float radius;
+    float speed;
+    float pulse;
+  } firefly;
+  vec3 firefly_getPosition(vec3 position, float seed, float time) {
+    if (firefly.enabled <= 0.0) { return position; }
+    float phase = seed * 2.399963;
+    float travel = time * firefly.speed;
+    vec3 offset = vec3(sin(travel * 0.71 + phase) + sin(travel * 1.31 + phase * 1.7) * 0.35,
+      cos(travel * 0.83 + phase * 1.2) + sin(travel * 0.47 + phase * 2.3) * 0.4,
+      sin(travel * 0.59 + phase * 1.9) * 0.3);
+    return position + offset * firefly.radius * firefly.enabled;
+  }
+  float firefly_getBrightness(float seed, float time) {
+    if (firefly.enabled <= 0.0) { return 1.0; }
+    float phase = seed * 2.399963;
+    float pulse = pow(0.5 + 0.5 * sin(time * firefly.speed * (1.6 + fract(seed * 0.37)) + phase), 3.0);
+    return mix(1.0, mix(0.08, 1.0, pulse), firefly.pulse * firefly.enabled);
+  }`
+} as const satisfies ShaderModule<FireflyProps, FireflyUniforms>;

package/src/modules/lighting/globe-clouds/globe-clouds.ts

@@ -0,0 +1,124 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ShaderModule} from '../../../lib/shader-module/shader-module';
+import {clouds} from '../clouds/clouds';
+
+export type GlobeCloudUniforms = {planetRadius: number};
+export type GlobeCloudProps = Partial<GlobeCloudUniforms>;
+
+/** Spherical cloud shell using the existing cloud density, noise and sunlight model.
+ * Camera and rays are globe-centered, with the planet's surface at unit radius.
+ * The shared clouds uniforms retain metre/second units; sunDirection is globe-centered XYZ.
+ */
+export const globeClouds = {
+  name: 'globeClouds',
+  dependencies: [clouds],
+  uniformTypes: {planetRadius: 'f32'},
+  defaultUniforms: {planetRadius: 6370972},
+  fs: /* glsl */ `
+layout(std140) uniform globeCloudsUniforms { float planetRadius; } globeClouds;
+vec2 globeClouds_intersectSphere(vec3 camera, vec3 direction, float radius) {
+  float projected = dot(camera, direction);
+  float discriminant = projected * projected - dot(camera, camera) + radius * radius;
+  if (discriminant < 0.0) return vec2(-1.0);
+  float root = sqrt(discriminant);
+  return vec2(-projected - root, -projected + root);
+}
+float globeClouds_getDensity(vec3 position) {
+  float height = ((length(position) - 1.0) * globeClouds.planetRadius - clouds.altitude) / max(clouds.thickness, 1.0);
+  // Rotate a 3D field rather than wrapping longitude UVs: no seams or pinched poles.
+  vec2 angle = clouds.velocity * clouds.time / globeClouds.planetRadius;
+  vec3 rotated = vec3(cos(angle.x) * position.x + sin(angle.x) * position.y,
+    -sin(angle.x) * position.x + cos(angle.x) * position.y, position.z);
+  rotated = vec3(rotated.x, cos(angle.y) * rotated.y + sin(angle.y) * rotated.z,
+    -sin(angle.y) * rotated.y + cos(angle.y) * rotated.z);
+  return clouds_getDensityAt(rotated * globeClouds.planetRadius / max(clouds.scale, 1.0), height);
+}
+vec4 globeClouds_getColor(vec3 camera, vec3 direction) {
+  if (clouds.cover <= 0.0 || clouds.density <= 0.0) return vec4(0.0);
+  float bottom = 1.0 + clouds.altitude / globeClouds.planetRadius;
+  float top = bottom + max(clouds.thickness, 1.0) / globeClouds.planetRadius;
+  vec2 outer = globeClouds_intersectSphere(camera, direction, top);
+  if (outer.y <= 0.0) return vec4(0.0);
+  float start = max(outer.x, 0.0);
+  float end = outer.y;
+  vec2 inner = globeClouds_intersectSphere(camera, direction, bottom);
+  if (length(camera) < bottom) start = max(start, inner.y);
+  else if (inner.x >= start) end = min(end, inner.x);
+  vec2 ground = globeClouds_intersectSphere(camera, direction, 1.0);
+  if (ground.x >= 0.0) end = min(end, ground.x);
+  if (end <= start) return vec4(0.0);
+  float stepLength = (end - start) / 32.0;
+  float jitter = valueNoise_hash(direction.xy * 4096.0);
+  vec3 sunlightDirection = normalize(clouds.sunDirection);
+  float silver = pow(max(dot(direction, sunlightDirection), 0.0), 12.0);
+  vec3 radiance = vec3(0.0);
+  float transmittance = 1.0;
+  for (int sampleIndex = 0; sampleIndex < 32; sampleIndex++) {
+    vec3 position = camera + direction * (start + (float(sampleIndex) + jitter) * stepLength);
+    float density = globeClouds_getDensity(position);
+    float sunDensity = globeClouds_getDensity(position + sunlightDirection * clouds.thickness * 0.28 / globeClouds.planetRadius);
+    float daylight = smoothstep(-0.08, 0.18, dot(normalize(position), sunlightDirection));
+    float alpha = 1.0 - exp(-density * clouds.density * stepLength * globeClouds.planetRadius);
+    radiance += transmittance * alpha * clouds_getLighting(density * 0.25, sunDensity * 0.25, daylight, silver);
+    transmittance *= 1.0 - alpha;
+    if (transmittance < 0.01) break;
+  }
+  return vec4(radiance, 1.0 - transmittance);
+}
+`,
+  source: /* wgsl */ `
+struct globeCloudsUniforms { planetRadius: f32 };
+@group(3) @binding(auto) var<uniform> globeClouds: globeCloudsUniforms;
+fn globeClouds_intersectSphere(camera: vec3f, direction: vec3f, radius: f32) -> vec2f {
+  let projected = dot(camera, direction);
+  let discriminant = projected * projected - dot(camera, camera) + radius * radius;
+  if (discriminant < 0.0) { return vec2f(-1.0); }
+  let root = sqrt(discriminant);
+  return vec2f(-projected - root, -projected + root);
+}
+fn globeClouds_getDensity(position: vec3f) -> f32 {
+  let height = ((length(position) - 1.0) * globeClouds.planetRadius - clouds.altitude) / max(clouds.thickness, 1.0);
+  let angle = clouds.velocity * clouds.time / globeClouds.planetRadius;
+  var rotated = vec3f(cos(angle.x) * position.x + sin(angle.x) * position.y,
+    -sin(angle.x) * position.x + cos(angle.x) * position.y, position.z);
+  rotated = vec3f(rotated.x, cos(angle.y) * rotated.y + sin(angle.y) * rotated.z,
+    -sin(angle.y) * rotated.y + cos(angle.y) * rotated.z);
+  return clouds_getDensityAt(rotated * globeClouds.planetRadius / max(clouds.scale, 1.0), height);
+}
+fn globeClouds_getColor(camera: vec3f, direction: vec3f) -> vec4f {
+  if (clouds.cover <= 0.0 || clouds.density <= 0.0) { return vec4f(0.0); }
+  let bottom = 1.0 + clouds.altitude / globeClouds.planetRadius;
+  let top = bottom + max(clouds.thickness, 1.0) / globeClouds.planetRadius;
+  let outer = globeClouds_intersectSphere(camera, direction, top);
+  if (outer.y <= 0.0) { return vec4f(0.0); }
+  var start = max(outer.x, 0.0);
+  var end = outer.y;
+  let inner = globeClouds_intersectSphere(camera, direction, bottom);
+  if (length(camera) < bottom) { start = max(start, inner.y); }
+  else if (inner.x >= start) { end = min(end, inner.x); }
+  let ground = globeClouds_intersectSphere(camera, direction, 1.0);
+  if (ground.x >= 0.0) { end = min(end, ground.x); }
+  if (end <= start) { return vec4f(0.0); }
+  let stepLength = (end - start) / 32.0;
+  let jitter = valueNoise_hash(direction.xy * 4096.0);
+  let sunlightDirection = normalize(clouds.sunDirection);
+  let silver = pow(max(dot(direction, sunlightDirection), 0.0), 12.0);
+  var radiance = vec3f(0.0);
+  var transmittance = 1.0;
+  for (var sampleIndex = 0; sampleIndex < 32; sampleIndex++) {
+    let position = camera + direction * (start + (f32(sampleIndex) + jitter) * stepLength);
+    let density = globeClouds_getDensity(position);
+    let sunDensity = globeClouds_getDensity(position + sunlightDirection * clouds.thickness * 0.28 / globeClouds.planetRadius);
+    let daylight = smoothstep(-0.08, 0.18, dot(normalize(position), sunlightDirection));
+    let alpha = 1.0 - exp(-density * clouds.density * stepLength * globeClouds.planetRadius);
+    radiance += transmittance * alpha * clouds_getLighting(density * 0.25, sunDensity * 0.25, daylight, silver);
+    transmittance *= 1.0 - alpha;
+    if (transmittance < 0.01) { break; }
+  }
+  return vec4f(radiance, 1.0 - transmittance);
+}
+`
+} as const satisfies ShaderModule<GlobeCloudProps, GlobeCloudUniforms>;

package/src/modules/lighting/gouraud-material/gouraud-material.ts

@@ -0,0 +1,55 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {NumberArray3} from '@math.gl/core';
+import {ShaderModule} from '../../../lib/shader-module/shader-module';
+import {floatColors} from '../../color/float-colors';
+import {lighting} from '../lights/lighting';
+import {PHONG_VS, PHONG_FS} from '../phong-material/phong-shaders-glsl';
+import {PHONG_WGSL} from '../phong-material/phong-shaders-wgsl';
+
+export type GouraudMaterialProps = {
+  unlit?: boolean;
+  ambient?: number;
+  diffuse?: number;
+  /** Specularity exponent */
+  shininess?: number;
+  specularColor?: [number, number, number];
+};
+
+const DEFAULT_SPECULAR_COLOR: NumberArray3 = [38.25, 38.25, 38.25];
+
+/** In Gouraud shading, color is calculated for each triangle vertex normal, and then color is interpolated colors across the triangle */
+export const gouraudMaterial: ShaderModule<GouraudMaterialProps> = {
+  props: {} as GouraudMaterialProps,
+
+  name: 'gouraudMaterial',
+  bindingLayout: [{name: 'gouraudMaterial', group: 3}],
+  // Note these are switched between phong and gouraud
+  vs: PHONG_FS.replace('phongMaterial', 'gouraudMaterial'),
+  fs: PHONG_VS.replace('phongMaterial', 'gouraudMaterial'),
+  source: PHONG_WGSL.replaceAll('phongMaterial', 'gouraudMaterial'),
+  defines: {
+    LIGHTING_VERTEX: true
+  },
+  dependencies: [lighting, floatColors],
+  uniformTypes: {
+    unlit: 'i32',
+    ambient: 'f32',
+    diffuse: 'f32',
+    shininess: 'f32',
+    specularColor: 'vec3<f32>'
+  },
+  defaultUniforms: {
+    unlit: false,
+    ambient: 0.35,
+    diffuse: 0.6,
+    shininess: 32,
+    specularColor: DEFAULT_SPECULAR_COLOR
+  },
+
+  getUniforms(props: GouraudMaterialProps) {
+    return {...gouraudMaterial.defaultUniforms, ...props};
+  }
+};

package/src/modules/lighting/height-fog/README.md

@@ -0,0 +1,36 @@
+# heightFog
+
+Analytic fog extinction for fragment shaders in GLSL and WGSL. Call
+`heightFog_getColor(color, position, cameraPosition)` with both positions in the same
+local east/north/up metre coordinates. It preserves alpha and mixes linear RGB with
+`heightFog.color`. `heightFog_getTransmittance(position, cameraPosition)` returns the
+unscattered fraction for custom compositing.
+
+`density` is base extinction per metre, `baseHeight` is in metres, and `heightFalloff`
+is inverse metres. Density stays constant below the base and decays exponentially above
+it. Zero density disables fog; zero falloff gives uniform distance fog. The ray integral
+handles horizontal rays and rays crossing the base without a marching loop or history.
+This is a constant-color atmosphere approximation, without shadowing or directional scattering.
+
+
+`heightFogFunctions` exposes the same calculation without a uniform block. Its
+`heightFog_getRayTransmittance(rayLength, cameraHeight, fragmentHeight, density, baseHeight, heightFalloff)`
+function accepts scalar metre-space ray length and heights, allowing callers to choose an up
+axis and supply their own uniform layout. The `heightFog` material module depends on it, as does
+`@luma.gl/engine/effects`' analytic height-fog pass. The two paths therefore share the density integral.
+
+
+For drifting wisps, set `variation` from 0 to 1, `wispScale` in metres, `velocity`
+in metres per second, and `time` in seconds. Defaults keep the uniform analytic path.
+With variation enabled, twelve ray segments sample warped, multiscale world-space
+noise; each segment retains the analytic height integral. This is a bounded-cost density
+approximation, not a volumetric fluid simulation. Pausing time freezes it; zero velocity
+keeps a static, nonuniform field. Both material and depth-pass fog call the same
+`heightFog_getSpatialTransmittance` helper. It needs no noise textures or temporal history.
+The tint remains constant; density varies. Very long rays through small wisps can undersample
+this fixed twelve-segment approximation, so choose bank sizes appropriate to the scene.
+
+Set `evolutionSpeed` above zero for gentle internal deformation in addition to advection.
+Zero retains the rigid density field. Applications control time; freeze it to pause both
+forms of motion. When changing drift speed interactively, integrate distance over time
+instead of multiplying the new speed by the entire elapsed clock.

package/src/modules/lighting/height-fog/height-fog-functions.ts

@@ -0,0 +1,116 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ShaderModule} from '../../../lib/shader-module/shader-module';
+import {valueNoise} from '../../math/value-noise/value-noise';
+
+/** Uniform-free analytic extinction shared by materials and screen-space effects.
+ * Lengths and heights are metres; density and falloff are inverse metres.
+ */
+export const heightFogFunctions = {
+  name: 'heightFogFunctions',
+  dependencies: [valueNoise],
+  fs: /* glsl */ `
+float heightFog_getRayTransmittance(float rayLength, float cameraHeight, float fragmentHeight, float density, float baseHeight, float heightFalloff) {
+  float startHeight = (cameraHeight - baseHeight) * max(heightFalloff, 0.0);
+  float endHeight = (fragmentHeight - baseHeight) * max(heightFalloff, 0.0);
+  float lowerHeight = min(startHeight, endHeight);
+  float upperHeight = max(startHeight, endHeight);
+  float averageDensity = 1.0;
+  if (upperHeight > 0.0) {
+    float heightSpan = upperHeight - lowerHeight;
+    if (heightSpan < 0.001) {
+      averageDensity = exp(-max((startHeight + endHeight) * 0.5, 0.0));
+    } else if (lowerHeight >= 0.0) {
+      averageDensity = (exp(-lowerHeight) - exp(-upperHeight)) / heightSpan;
+    } else {
+      averageDensity = (-lowerHeight + 1.0 - exp(-upperHeight)) / heightSpan;
+    }
+  }
+  return exp(-max(density, 0.0) * rayLength * averageDensity);
+}
+float heightFog_hash(vec2 cell) { return valueNoise_hash(cell); }
+float heightFog_noise(vec2 position) { return valueNoise_noise(position); }
+// Integrate drifting density along the ray so wisps occupy space rather than coat surfaces.
+float heightFog_getSpatialTransmittance(vec3 camera, vec3 position, vec3 upDirection,
+    float density, float baseHeight, float heightFalloff, float variation, float wispScale,
+    float time, vec3 velocity, float evolutionSpeed) {
+  if (density <= 0.0) return 1.0;
+  float rayLength = distance(camera, position);
+  if (variation <= 0.0) return heightFog_getRayTransmittance(rayLength, dot(camera, upDirection),
+    dot(position, upDirection), density, baseHeight, heightFalloff);
+  vec3 reference = abs(upDirection.z) < 0.9 ? vec3(0.0, 0.0, 1.0) : vec3(0.0, 1.0, 0.0);
+  vec3 horizontal = normalize(cross(reference, upDirection));
+  vec3 forward = cross(upDirection, horizontal);
+  float transmittance = 1.0;
+  for (int sampleIndex = 0; sampleIndex < 12; sampleIndex++) {
+    float fraction = float(sampleIndex) / 12.0;
+    vec3 start = mix(camera, position, fraction);
+    vec3 end = mix(camera, position, fraction + 1.0 / 12.0);
+    vec3 samplePosition = (start + end) * 0.5 - velocity * time;
+    vec2 coordinate = vec2(dot(samplePosition, horizontal), dot(samplePosition, forward)) / max(wispScale, 1.0);
+    coordinate.y = coordinate.y * 1.8 + dot(samplePosition, upDirection) / max(wispScale, 1.0);
+    float warp = heightFog_noise(coordinate * 0.45 + vec2(8.3, 2.7) + time * evolutionSpeed * vec2(1.0, 0.37));
+    float broad = heightFog_noise(coordinate + vec2(warp * 2.0, warp * 0.8));
+    float detail = heightFog_noise(mat2(0.8, 0.6, -0.6, 0.8) * coordinate * 2.17 + vec2(17.1, 9.2) + broad * 0.7);
+    float modulation = mix(1.0, 1.8 * smoothstep(0.15, 0.85, broad * 0.7 + detail * 0.3), clamp(variation, 0.0, 1.0));
+    transmittance *= heightFog_getRayTransmittance(rayLength / 12.0, dot(start, upDirection),
+      dot(end, upDirection), density * modulation, baseHeight, heightFalloff);
+  }
+  return transmittance;
+}
+
+`,
+  source: /* wgsl */ `
+fn heightFog_getRayTransmittance(rayLength: f32, cameraHeight: f32, fragmentHeight: f32, density: f32, baseHeight: f32, heightFalloff: f32) -> f32 {
+  let startHeight = (cameraHeight - baseHeight) * max(heightFalloff, 0.0);
+  let endHeight = (fragmentHeight - baseHeight) * max(heightFalloff, 0.0);
+  let lowerHeight = min(startHeight, endHeight);
+  let upperHeight = max(startHeight, endHeight);
+  var averageDensity = 1.0;
+  if (upperHeight > 0.0) {
+    let heightSpan = upperHeight - lowerHeight;
+    if (heightSpan < 0.001) {
+      averageDensity = exp(-max((startHeight + endHeight) * 0.5, 0.0));
+    } else if (lowerHeight >= 0.0) {
+      averageDensity = (exp(-lowerHeight) - exp(-upperHeight)) / heightSpan;
+    } else {
+      averageDensity = (-lowerHeight + 1.0 - exp(-upperHeight)) / heightSpan;
+    }
+  }
+  return exp(-max(density, 0.0) * rayLength * averageDensity);
+}
+fn heightFog_hash(cell: vec2f) -> f32 { return valueNoise_hash(cell); }
+fn heightFog_noise(position: vec2f) -> f32 { return valueNoise_noise(position); }
+// Integrate drifting density along the ray so wisps occupy space rather than coat surfaces.
+fn heightFog_getSpatialTransmittance(camera: vec3f, position: vec3f, upDirection: vec3f,
+    density: f32, baseHeight: f32, heightFalloff: f32, variation: f32, wispScale: f32,
+    time: f32, velocity: vec3f, evolutionSpeed: f32) -> f32 {
+  if (density <= 0.0) { return 1.0; }
+  let rayLength = distance(camera, position);
+  if (variation <= 0.0) { return heightFog_getRayTransmittance(rayLength, dot(camera, upDirection),
+    dot(position, upDirection), density, baseHeight, heightFalloff); }
+  let reference = select(vec3f(0.0, 1.0, 0.0), vec3f(0.0, 0.0, 1.0), abs(upDirection.z) < 0.9);
+  let horizontal = normalize(cross(reference, upDirection));
+  let forward = cross(upDirection, horizontal);
+  var transmittance = 1.0;
+  for (var sampleIndex = 0; sampleIndex < 12; sampleIndex++) {
+    let fraction = f32(sampleIndex) / 12.0;
+    let start = mix(camera, position, fraction);
+    let end = mix(camera, position, fraction + 1.0 / 12.0);
+    let samplePosition = (start + end) * 0.5 - velocity * time;
+    var coordinate = vec2f(dot(samplePosition, horizontal), dot(samplePosition, forward)) / max(wispScale, 1.0);
+    coordinate.y = coordinate.y * 1.8 + dot(samplePosition, upDirection) / max(wispScale, 1.0);
+    let warp = heightFog_noise(coordinate * 0.45 + vec2f(8.3, 2.7) + time * evolutionSpeed * vec2f(1.0, 0.37));
+    let broad = heightFog_noise(coordinate + vec2f(warp * 2.0, warp * 0.8));
+    let detail = heightFog_noise(mat2x2f(vec2f(0.8, 0.6), vec2f(-0.6, 0.8)) * coordinate * 2.17 + vec2f(17.1, 9.2) + vec2f(broad * 0.7));
+    let modulation = mix(1.0, 1.8 * smoothstep(0.15, 0.85, broad * 0.7 + detail * 0.3), clamp(variation, 0.0, 1.0));
+    transmittance *= heightFog_getRayTransmittance(rayLength / 12.0, dot(start, upDirection),
+      dot(end, upDirection), density * modulation, baseHeight, heightFalloff);
+  }
+  return transmittance;
+}
+
+`
+} as const satisfies ShaderModule;