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

package/src/modules/lighting/surface-weather/surface-weather.ts

@@ -0,0 +1,198 @@
+// 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 SurfaceWeatherState = {wetness: number; snow: number};
+export type SurfaceWeatherUniforms = SurfaceWeatherState & {
+  puddles: number;
+  /** World-anchored patch size in metres. */
+  scale: number;
+  snowColor: [number, number, number];
+  skyColor: [number, number, number];
+};
+export type SurfaceWeatherProps = Partial<SurfaceWeatherUniforms>;
+export type SurfaceWeatherRates = {
+  /** Per-second rates; precipitation fills the remaining capacity. */
+  rainfall: number;
+  snowfall: number;
+  evaporation: number;
+  snowmelt: number;
+};
+
+/** Exact integration of bounded accumulation/decay for a constant-rate interval.
+ * Caller owns the state, clock, rates and any spatial exposure map. Pausing requires no GPU state.
+ */
+export function integrateSurfaceWeather(
+  state: Readonly<SurfaceWeatherState>,
+  rates: Readonly<SurfaceWeatherRates>,
+  elapsedSeconds: number
+): SurfaceWeatherState {
+  function integrate(value: number, incoming: number, outgoing: number): number {
+    const total = Math.max(incoming, 0) + Math.max(outgoing, 0);
+    const bounded = Math.min(1, Math.max(0, value));
+    if (total === 0 || elapsedSeconds <= 0) return bounded;
+    const target = Math.max(incoming, 0) / total;
+    return target + (bounded - target) * Math.exp(-total * Math.max(elapsedSeconds, 0));
+  }
+  return {
+    wetness: integrate(state.wetness, rates.rainfall, rates.evaporation),
+    snow: integrate(state.snow, rates.snowfall, rates.snowmelt)
+  };
+}
+const DEFAULT_UNIFORMS: SurfaceWeatherUniforms = {
+  wetness: 0,
+  snow: 0,
+  puddles: 0.8,
+  scale: 20,
+  snowColor: [0.9, 0.94, 0.98],
+  skyColor: [0.48, 0.6, 0.72]
+};
+
+/** Material helpers for persistent wetness, puddles and upward-facing snow.
+ * Every helper accepts a caller-provided exposure mask, so water and sheltered surfaces can opt out.
+ */
+export const surfaceWeather = {
+  name: 'surfaceWeather',
+  dependencies: [valueNoise],
+  uniformTypes: {
+    wetness: 'f32',
+    snow: 'f32',
+    puddles: 'f32',
+    scale: 'f32',
+    snowColor: 'vec3<f32>',
+    skyColor: 'vec3<f32>'
+  },
+  defaultUniforms: DEFAULT_UNIFORMS,
+  getUniforms(props = {}, previousUniforms = DEFAULT_UNIFORMS) {
+    return {...DEFAULT_UNIFORMS, ...previousUniforms, ...props};
+  },
+  fs: /* glsl */ `
+layout(std140) uniform surfaceWeatherUniforms {
+  float wetness;
+  float snow;
+  float puddles;
+  float scale;
+  vec3 snowColor;
+  vec3 skyColor;
+} surfaceWeather;
+
+float surfaceWeather_getSnow(vec3 position, vec3 normal, float exposure) {
+  if (surfaceWeather.snow <= 0.0 || exposure <= 0.0) return 0.0;
+  float slope = smoothstep(0.4, 0.85, normalize(normal).z);
+  float variation = valueNoise_noise(position.xy / max(surfaceWeather.scale, 0.01));
+  float coverage = smoothstep(variation * 0.65, variation * 0.65 + 0.35, surfaceWeather.snow);
+  return coverage * slope * clamp(exposure, 0.0, 1.0);
+}
+float surfaceWeather_getWetness(vec3 position, vec3 normal, float exposure) {
+  if (surfaceWeather.wetness <= 0.0 || exposure <= 0.0) return 0.0;
+  return clamp(surfaceWeather.wetness, 0.0, 1.0) * clamp(exposure, 0.0, 1.0) * (1.0 - surfaceWeather_getSnow(position, normal, exposure));
+}
+float surfaceWeather_getPuddle(vec3 position, vec3 normal, float exposure) {
+  if (surfaceWeather.wetness <= 0.0 || surfaceWeather.puddles <= 0.0 || exposure <= 0.0) return 0.0;
+  float variation = valueNoise_noise(position.xy / max(surfaceWeather.scale, 0.01) + vec2(8.3, 2.7));
+  return surfaceWeather_getWetness(position, normal, exposure) * clamp(surfaceWeather.puddles, 0.0, 1.0) *
+    smoothstep(0.8, 0.98, normalize(normal).z) * smoothstep(0.38, 0.7, variation);
+}
+vec3 surfaceWeather_getAlbedo(vec3 albedo, vec3 position, vec3 normal, float exposure) {
+  if ((surfaceWeather.wetness <= 0.0 && surfaceWeather.snow <= 0.0) || exposure <= 0.0) return albedo;
+  float wetness = surfaceWeather_getWetness(position, normal, exposure);
+  float snow = surfaceWeather_getSnow(position, normal, exposure);
+  return mix(albedo * (1.0 - wetness * 0.38), surfaceWeather.snowColor, snow);
+}
+float surfaceWeather_getRoughness(float roughness, vec3 position, vec3 normal, float exposure) {
+  if ((surfaceWeather.wetness <= 0.0 && surfaceWeather.snow <= 0.0) || exposure <= 0.0) return roughness;
+  float wetness = surfaceWeather_getWetness(position, normal, exposure);
+  float puddle = surfaceWeather_getPuddle(position, normal, exposure);
+  float snow = surfaceWeather_getSnow(position, normal, exposure);
+  return mix(mix(roughness, 0.16, max(puddle, wetness * 0.6)), 0.95, snow);
+}
+// Approximate dielectric highlights and sky tint; callers may use the albedo/roughness helpers with PBR instead.
+vec3 surfaceWeather_getReflection(vec3 position, vec3 normal, vec3 camera, vec3 lightDirection, vec3 lightColor, float exposure) {
+  if (surfaceWeather.wetness <= 0.0 || exposure <= 0.0) return vec3(0.0);
+  vec3 surfaceNormal = normalize(normal);
+  vec3 view = normalize(camera - position);
+  vec3 halfway = normalize(view + normalize(lightDirection));
+  float wetness = surfaceWeather_getWetness(position, normal, exposure);
+  float puddle = surfaceWeather_getPuddle(position, normal, exposure);
+  float facing = max(dot(surfaceNormal, view), 0.0);
+  float fresnel = 0.02 + 0.98 * pow(1.0 - facing, 5.0);
+  float highlight = pow(max(dot(surfaceNormal, halfway), 0.0), mix(36.0, 160.0, puddle)) * max(dot(surfaceNormal, normalize(lightDirection)), 0.0);
+  return wetness * (surfaceWeather.skyColor * fresnel * (0.15 + puddle * 0.85) + lightColor * highlight * 0.6);
+}
+`,
+  source: /* wgsl */ `
+struct surfaceWeatherUniforms {
+  wetness: f32,
+  snow: f32,
+  puddles: f32,
+  scale: f32,
+  snowColor: vec3f,
+  skyColor: vec3f,
+};
+@group(3) @binding(auto) var<uniform> surfaceWeather: surfaceWeatherUniforms;
+
+fn surfaceWeather_getSnow(position: vec3f,
+  normal: vec3f,
+  exposure: f32) -> f32 {
+  if (surfaceWeather.snow <= 0.0 || exposure <= 0.0) { return 0.0; }
+  var slope: f32 = smoothstep(0.4, 0.85, normalize(normal).z);
+  var variation: f32 = valueNoise_noise(position.xy / max(surfaceWeather.scale, 0.01));
+  var coverage: f32 = smoothstep(variation * 0.65, variation * 0.65 + 0.35, surfaceWeather.snow);
+  return coverage * slope * clamp(exposure, 0.0, 1.0);
+}
+fn surfaceWeather_getWetness(position: vec3f,
+  normal: vec3f,
+  exposure: f32) -> f32 {
+  if (surfaceWeather.wetness <= 0.0 || exposure <= 0.0) { return 0.0; }
+  return clamp(surfaceWeather.wetness, 0.0, 1.0) * clamp(exposure, 0.0, 1.0) * (1.0 - surfaceWeather_getSnow(position, normal, exposure));
+}
+fn surfaceWeather_getPuddle(position: vec3f,
+  normal: vec3f,
+  exposure: f32) -> f32 {
+  if (surfaceWeather.wetness <= 0.0 || surfaceWeather.puddles <= 0.0 || exposure <= 0.0) { return 0.0; }
+  var variation: f32 = valueNoise_noise(position.xy / max(surfaceWeather.scale, 0.01) + vec2f(8.3, 2.7));
+  return surfaceWeather_getWetness(position, normal, exposure) * clamp(surfaceWeather.puddles, 0.0, 1.0) *
+    smoothstep(0.8, 0.98, normalize(normal).z) * smoothstep(0.38, 0.7, variation);
+}
+fn surfaceWeather_getAlbedo(albedo: vec3f,
+  position: vec3f,
+  normal: vec3f,
+  exposure: f32) -> vec3f {
+  if ((surfaceWeather.wetness <= 0.0 && surfaceWeather.snow <= 0.0) || exposure <= 0.0) { return albedo; }
+  var wetness: f32 = surfaceWeather_getWetness(position, normal, exposure);
+  var snow: f32 = surfaceWeather_getSnow(position, normal, exposure);
+  return mix(albedo * (1.0 - wetness * 0.38), surfaceWeather.snowColor, snow);
+}
+fn surfaceWeather_getRoughness(roughness: f32,
+  position: vec3f,
+  normal: vec3f,
+  exposure: f32) -> f32 {
+  if ((surfaceWeather.wetness <= 0.0 && surfaceWeather.snow <= 0.0) || exposure <= 0.0) { return roughness; }
+  var wetness: f32 = surfaceWeather_getWetness(position, normal, exposure);
+  var puddle: f32 = surfaceWeather_getPuddle(position, normal, exposure);
+  var snow: f32 = surfaceWeather_getSnow(position, normal, exposure);
+  return mix(mix(roughness, 0.16, max(puddle, wetness * 0.6)), 0.95, snow);
+}
+// Approximate dielectric highlights and sky tint; callers may use the albedo/roughness helpers with PBR instead.
+fn surfaceWeather_getReflection(position: vec3f,
+  normal: vec3f,
+  camera: vec3f,
+  lightDirection: vec3f,
+  lightColor: vec3f,
+  exposure: f32) -> vec3f {
+  if (surfaceWeather.wetness <= 0.0 || exposure <= 0.0) { return vec3f(0.0); }
+  var surfaceNormal: vec3f = normalize(normal);
+  var view: vec3f = normalize(camera - position);
+  var halfway: vec3f = normalize(view + normalize(lightDirection));
+  var wetness: f32 = surfaceWeather_getWetness(position, normal, exposure);
+  var puddle: f32 = surfaceWeather_getPuddle(position, normal, exposure);
+  var facing: f32 = max(dot(surfaceNormal, view), 0.0);
+  var fresnel: f32 = 0.02 + 0.98 * pow(1.0 - facing, 5.0);
+  var highlight: f32 = pow(max(dot(surfaceNormal, halfway), 0.0), mix(36.0, 160.0, puddle)) * max(dot(surfaceNormal, normalize(lightDirection)), 0.0);
+  return wetness * (surfaceWeather.skyColor * fresnel * (0.15 + puddle * 0.85) + lightColor * highlight * 0.6);
+}
+`
+} as const satisfies ShaderModule<SurfaceWeatherProps, SurfaceWeatherUniforms>;

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

@@ -0,0 +1,44 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ShaderModule} from '../../../lib/shader-module/shader-module';
+
+const SOURCE_WGSL = /* wgsl */ `\
+fn unlitMaterial_getColor(surfaceColor: vec4<f32>) -> vec4<f32> {
+  return surfaceColor;
+}
+
+// Compatibility with the aggregate Phong/Gouraud material evaluation function.
+fn lighting_getLightColor2(surfaceColor: vec3<f32>, cameraPosition: vec3<f32>, positionWorldspace: vec3<f32>, normalWorldspace: vec3<f32>) -> vec3<f32> {
+  return surfaceColor;
+}
+`;
+
+const SOURCE_GLSL = /* glsl */ `\
+vec4 unlitMaterial_getColor(vec4 surfaceColor) {
+  return surfaceColor;
+}
+
+// Compatibility with the aggregate Phong/Gouraud material evaluation function.
+vec3 lighting_getLightColor(vec3 surfaceColor, vec3 cameraPosition, vec3 positionWorldspace, vec3 normalWorldspace) {
+  return surfaceColor;
+}
+`;
+
+/**
+ * Preserves surface RGBA without lighting dependencies, uniforms, or bindings.
+ * Use instead of a lit material module when lighting is never needed. The caller
+ * supplies color/texture sampling and remains responsible for output color space
+ * and alpha conventions. Available in both vertex and fragment stages.
+ */
+export const unlitMaterial: ShaderModule<Record<string, never>> = {
+  name: 'unlitMaterial',
+  source: SOURCE_WGSL,
+  vs: SOURCE_GLSL,
+  fs: SOURCE_GLSL,
+  dependencies: [],
+  bindingLayout: [],
+  uniformTypes: {},
+  defaultUniforms: {}
+};

package/src/modules/lighting/water-material/river-water-material.ts

@@ -0,0 +1,58 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {ShaderModule} from '../../../lib/shader-module/shader-module';
+import {waterMaterial} from './water-material';
+import {RIVER_WATER_GLSL, RIVER_WATER_WGSL} from './river-water-shaders';
+
+export type RiverWaterMaterialProps = {
+  enabled?: number;
+  /** Local east/north direction of river flow. */
+  flowDirection?: [number, number];
+  /** Linear sky tint above the horizon. The horizon uses waterMaterial.fresnelColor. */
+  skyZenithColor?: [number, number, number];
+  /** Unit up direction in the same coordinate frame as the supplied surface normal. */
+  skyUpDirection?: [number, number, number];
+};
+
+export type RiverWaterMaterialUniforms = {
+  enabled?: number;
+  flowDirection?: [number, number];
+  /** Linear sky tint above the horizon. The horizon uses waterMaterial.fresnelColor. */
+  skyZenithColor?: [number, number, number];
+  /** Unit up direction in the same coordinate frame as the supplied surface normal. */
+  skyUpDirection?: [number, number, number];
+};
+
+/** A layered, animated river surface variant built on top of the shared water uniforms. */
+export const riverWaterMaterial: ShaderModule<RiverWaterMaterialProps, RiverWaterMaterialUniforms> =
+  {
+    name: 'riverWaterMaterial',
+    firstBindingSlot: 1,
+    bindingLayout: [{name: 'riverWaterMaterial', group: 3}],
+    dependencies: [waterMaterial],
+    source: RIVER_WATER_WGSL,
+    fs: RIVER_WATER_GLSL,
+    uniformTypes: {
+      enabled: 'i32',
+      flowDirection: 'vec2<f32>',
+      skyZenithColor: 'vec3<f32>',
+      skyUpDirection: 'vec3<f32>'
+    },
+    defaultUniforms: {
+      enabled: 0,
+      flowDirection: [0, 1],
+      skyZenithColor: [0.22, 0.48, 0.57],
+      skyUpDirection: [0, 0, 1]
+    },
+    getUniforms(props = {}, previousUniforms = {}) {
+      return {
+        enabled: props.enabled ?? previousUniforms.enabled ?? 0,
+        flowDirection: props.flowDirection ?? previousUniforms.flowDirection ?? [0, 1],
+        skyZenithColor: props.skyZenithColor ??
+          previousUniforms.skyZenithColor ?? [0.22, 0.48, 0.57],
+        skyUpDirection: props.skyUpDirection ?? previousUniforms.skyUpDirection ?? [0, 0, 1]
+      };
+    }
+  };

package/src/modules/lighting/water-material/river-water-shaders.ts

@@ -0,0 +1,234 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+export const RIVER_WATER_WGSL = /* wgsl */ `\
+struct riverWaterMaterialUniforms {
+  enabled: i32,
+  flowDirection: vec2<f32>,
+  skyZenithColor: vec3<f32>,
+  skyUpDirection: vec3<f32>,
+};
+
+@group(3) @binding(auto) var<uniform> riverWaterMaterial : riverWaterMaterialUniforms;
+
+fn riverWater_getFlowCoordinates(coordinates: vec2<f32>) -> vec2<f32> {
+  let flowDirection = normalize(riverWaterMaterial.flowDirection);
+  let crossDirection = vec2<f32>(-flowDirection.y, flowDirection.x);
+  return vec2<f32>(dot(coordinates, crossDirection), dot(coordinates, flowDirection));
+}
+
+// Smooth spatial variation travels with the surface; it does not flicker per frame.
+fn riverWater_noise(coordinates: vec2<f32>) -> f32 {
+  let cell = floor(coordinates);
+  let fraction = fract(coordinates);
+  let blend = fraction * fraction * (vec2<f32>(3.0) - 2.0 * fraction);
+  let corners = vec4<f32>(
+    dot(cell, vec2<f32>(127.1, 311.7)),
+    dot(cell + vec2<f32>(1.0, 0.0), vec2<f32>(127.1, 311.7)),
+    dot(cell + vec2<f32>(0.0, 1.0), vec2<f32>(127.1, 311.7)),
+    dot(cell + vec2<f32>(1.0, 1.0), vec2<f32>(127.1, 311.7))
+  );
+  let values = fract(sin(corners) * 43758.5453);
+  return mix(mix(values.x, values.y, blend.x), mix(values.z, values.w, blend.x), blend.y);
+}
+
+fn riverWater_waveGradient(
+  coordinates: vec2<f32>,
+  direction: vec2<f32>,
+  frequency: f32,
+  amplitude: f32,
+  speed: f32,
+  phaseOffset: f32
+) -> vec2<f32> {
+  // Advect the irregular wave packets together with their carrier waves.
+  let movingCoordinates = coordinates + direction * (waterMaterial.time * speed / frequency);
+  let crossDirection = vec2<f32>(-direction.y, direction.x);
+  let variationCoordinates = vec2<f32>(dot(movingCoordinates, crossDirection), dot(movingCoordinates, direction)) * frequency * vec2<f32>(0.38, 0.16) + vec2<f32>(phaseOffset * 3.7);
+  let variation = riverWater_noise(variationCoordinates);
+  let detail = riverWater_noise(variationCoordinates * 2.13 + vec2<f32>(11.3, 7.9));
+  let envelope = smoothstep(0.12, 0.88, riverWater_noise(variationCoordinates * 0.71 + vec2<f32>(23.6, 5.2)));
+  let phase = dot(movingCoordinates, direction) * frequency + phaseOffset + (variation - 0.5) * 7.0 + (detail - 0.5) * 2.5;
+  let attenuation = 1.0 - smoothstep(0.8, 3.0, fwidth(phase));
+  return direction * (cos(phase) * frequency * amplitude * attenuation * (0.15 + envelope * 1.2));
+}
+
+fn riverWater_getNormal(
+  position_worldspace: vec3<f32>,
+  position_objectspace: vec3<f32>,
+  normal_worldspace: vec3<f32>,
+  uv: vec2<f32>
+) -> vec3<f32> {
+  let coordinates = riverWater_getFlowCoordinates(
+    water_getCoordinates(position_worldspace, position_objectspace, uv)
+  );
+  let driftCoordinates = coordinates * 0.7 + vec2<f32>(0.0, waterMaterial.time * 0.22);
+  let warp = (vec2<f32>(
+    riverWater_noise(driftCoordinates),
+    riverWater_noise(driftCoordinates + vec2<f32>(17.2, 9.4))
+  ) - vec2<f32>(0.5)) * 0.65;
+  let warpedCoordinates = coordinates + warp;
+  let gradient =
+    riverWater_waveGradient(warpedCoordinates, normalize(vec2<f32>(0.08, 1.0)), 2.1, 0.018, 1.25, 0.0) +
+    riverWater_waveGradient(warpedCoordinates, normalize(vec2<f32>(-0.28, 1.0)), 3.7, 0.018, 0.95, 1.7) +
+    riverWater_waveGradient(warpedCoordinates, normalize(vec2<f32>(0.47, 1.0)), 5.3, 0.012, 1.7, 3.2) +
+    riverWater_waveGradient(warpedCoordinates, normalize(vec2<f32>(-0.68, 1.0)), 7.9, 0.008, 0.76, 0.8) +
+    riverWater_waveGradient(warpedCoordinates, normalize(vec2<f32>(0.92, 1.0)), 11.6, 0.004, 2.2, 2.1) +
+    riverWater_waveGradient(warpedCoordinates, normalize(vec2<f32>(-1.22, 1.0)), 16.3, 0.002, 1.45, 2.8);
+  let tangent = water_getTangent(normalize(normal_worldspace));
+  let bitangent = normalize(cross(normalize(normal_worldspace), tangent));
+  return normalize(normal_worldspace + waterMaterial.normalStrength * 3.2 *
+    (gradient.x * tangent + gradient.y * bitangent));
+}
+
+// Camera-independent sky approximation; missing scene reflections retain this material color.
+fn riverWater_getSkyColor(reflectionDirection: vec3<f32>) -> vec3<f32> {
+  let elevation = clamp(dot(normalize(reflectionDirection), normalize(riverWaterMaterial.skyUpDirection)), 0.0, 1.0);
+  let horizonColor = mix(waterMaterial.fresnelColor, riverWaterMaterial.skyZenithColor, 0.32);
+  return mix(horizonColor, riverWaterMaterial.skyZenithColor, smoothstep(0.0, 1.0, elevation));
+}
+
+fn riverWater_getColorMapped(
+  cameraPosition: vec3<f32>,
+  position_worldspace: vec3<f32>,
+  position_objectspace: vec3<f32>,
+  normal_worldspace: vec3<f32>,
+  uv: vec2<f32>
+) -> vec4<f32> {
+  let waterNormal = riverWater_getNormal(
+    position_worldspace, position_objectspace, normal_worldspace, uv
+  );
+  let viewDirection = normalize(cameraPosition - position_worldspace);
+  let fresnel = pow(1.0 - max(dot(viewDirection, waterNormal), 0.0), 3.2);
+  let deepColor = waterMaterial.baseColor * vec3<f32>(0.52, 0.74, 0.9);
+  let reflectedColor = riverWater_getSkyColor(reflect(-viewDirection, waterNormal));
+  let surfaceColor = mix(deepColor, reflectedColor, clamp(fresnel * 0.78, 0.0, 0.78));
+  var color = surfaceColor * (0.32 + 0.68 * lighting.ambientColor);
+
+  for (var i: i32 = 0; i < lighting.directionalLightCount; i++) {
+    let directionalLight = lighting_getDirectionalLight(i);
+    let lightDirection = normalize(-directionalLight.direction);
+    let halfwayDirection = normalize(lightDirection + viewDirection);
+    let diffuse = max(dot(waterNormal, lightDirection), 0.0);
+    let specular = pow(max(dot(waterNormal, halfwayDirection), 0.0), 64.0);
+    let brokenSpecular = specular * (0.25 + 0.75 * fresnel);
+    color += surfaceColor * directionalLight.color * diffuse * 0.38;
+    color += vec3<f32>(0.72, 0.88, 0.94) * directionalLight.color * brokenSpecular * 2.1;
+  }
+
+  color = mix(color, reflectedColor, clamp(fresnel * 0.3, 0.0, 0.3));
+  return vec4<f32>(color, waterMaterial.opacity);
+}
+`;
+
+export const RIVER_WATER_GLSL = /* glsl */ `\
+layout(std140) uniform riverWaterMaterialUniforms {
+  uniform int enabled;
+  uniform vec2 flowDirection;
+  uniform vec3 skyZenithColor;
+  uniform vec3 skyUpDirection;
+} riverWaterMaterial;
+
+vec2 riverWater_getFlowCoordinates(vec2 coordinates) {
+  vec2 flowDirection = normalize(riverWaterMaterial.flowDirection);
+  vec2 crossDirection = vec2(-flowDirection.y, flowDirection.x);
+  return vec2(dot(coordinates, crossDirection), dot(coordinates, flowDirection));
+}
+
+// Smooth spatial variation travels with the surface; it does not flicker per frame.
+float riverWater_noise(vec2 coordinates) {
+  vec2 cell = floor(coordinates);
+  vec2 fraction = fract(coordinates);
+  vec2 blend = fraction * fraction * (vec2(3.0) - 2.0 * fraction);
+  vec4 corners = vec4(
+    dot(cell, vec2(127.1, 311.7)),
+    dot(cell + vec2(1.0, 0.0), vec2(127.1, 311.7)),
+    dot(cell + vec2(0.0, 1.0), vec2(127.1, 311.7)),
+    dot(cell + vec2(1.0, 1.0), vec2(127.1, 311.7))
+  );
+  vec4 values = fract(sin(corners) * 43758.5453);
+  return mix(mix(values.x, values.y, blend.x), mix(values.z, values.w, blend.x), blend.y);
+}
+
+vec2 riverWater_waveGradient(
+  vec2 coordinates, vec2 direction, float frequency, float amplitude, float speed, float phaseOffset
+) {
+  // Advect the irregular wave packets together with their carrier waves.
+  vec2 movingCoordinates = coordinates + direction * (waterMaterial.time * speed / frequency);
+  vec2 crossDirection = vec2(-direction.y, direction.x);
+  vec2 variationCoordinates = vec2(dot(movingCoordinates, crossDirection), dot(movingCoordinates, direction)) * frequency * vec2(0.38, 0.16) + vec2(phaseOffset * 3.7);
+  float variation = riverWater_noise(variationCoordinates);
+  float detail = riverWater_noise(variationCoordinates * 2.13 + vec2(11.3, 7.9));
+  float envelope = smoothstep(0.12, 0.88, riverWater_noise(variationCoordinates * 0.71 + vec2(23.6, 5.2)));
+  float phase = dot(movingCoordinates, direction) * frequency + phaseOffset + (variation - 0.5) * 7.0 + (detail - 0.5) * 2.5;
+  float attenuation = 1.0 - smoothstep(0.8, 3.0, fwidth(phase));
+  return direction * (cos(phase) * frequency * amplitude * attenuation * (0.15 + envelope * 1.2));
+}
+
+vec3 riverWater_getNormal(
+  vec3 position_worldspace,
+  vec3 position_objectspace,
+  vec3 normal_worldspace,
+  vec2 uv
+) {
+  vec2 coordinates = riverWater_getFlowCoordinates(
+    water_getCoordinates(position_worldspace, position_objectspace, uv)
+  );
+  vec2 driftCoordinates = coordinates * 0.7 + vec2(0.0, waterMaterial.time * 0.22);
+  vec2 warp = (vec2(
+    riverWater_noise(driftCoordinates),
+    riverWater_noise(driftCoordinates + vec2(17.2, 9.4))
+  ) - vec2(0.5)) * 0.65;
+  vec2 warpedCoordinates = coordinates + warp;
+  vec2 gradient =
+    riverWater_waveGradient(warpedCoordinates, normalize(vec2(0.08, 1.0)), 2.1, 0.018, 1.25, 0.0) +
+    riverWater_waveGradient(warpedCoordinates, normalize(vec2(-0.28, 1.0)), 3.7, 0.018, 0.95, 1.7) +
+    riverWater_waveGradient(warpedCoordinates, normalize(vec2(0.47, 1.0)), 5.3, 0.012, 1.7, 3.2) +
+    riverWater_waveGradient(warpedCoordinates, normalize(vec2(-0.68, 1.0)), 7.9, 0.008, 0.76, 0.8) +
+    riverWater_waveGradient(warpedCoordinates, normalize(vec2(0.92, 1.0)), 11.6, 0.004, 2.2, 2.1) +
+    riverWater_waveGradient(warpedCoordinates, normalize(vec2(-1.22, 1.0)), 16.3, 0.002, 1.45, 2.8);
+  vec3 tangent = water_getTangent(normalize(normal_worldspace));
+  vec3 bitangent = normalize(cross(normalize(normal_worldspace), tangent));
+  return normalize(normal_worldspace + waterMaterial.normalStrength * 3.2 *
+    (gradient.x * tangent + gradient.y * bitangent));
+}
+
+// Camera-independent sky approximation; missing scene reflections retain this material color.
+vec3 riverWater_getSkyColor(vec3 reflectionDirection) {
+  float elevation = clamp(dot(normalize(reflectionDirection), normalize(riverWaterMaterial.skyUpDirection)), 0.0, 1.0);
+  vec3 horizonColor = mix(waterMaterial.fresnelColor, riverWaterMaterial.skyZenithColor, 0.32);
+  return mix(horizonColor, riverWaterMaterial.skyZenithColor, smoothstep(0.0, 1.0, elevation));
+}
+
+vec4 riverWater_getColorMapped(
+  vec3 cameraPosition,
+  vec3 position_worldspace,
+  vec3 position_objectspace,
+  vec3 normal_worldspace,
+  vec2 uv
+) {
+  vec3 waterNormal = riverWater_getNormal(
+    position_worldspace, position_objectspace, normal_worldspace, uv
+  );
+  vec3 viewDirection = normalize(cameraPosition - position_worldspace);
+  float fresnel = pow(1.0 - max(dot(viewDirection, waterNormal), 0.0), 3.2);
+  vec3 deepColor = waterMaterial.baseColor * vec3(0.52, 0.74, 0.9);
+  vec3 reflectedColor = riverWater_getSkyColor(reflect(-viewDirection, waterNormal));
+  vec3 surfaceColor = mix(deepColor, reflectedColor, clamp(fresnel * 0.78, 0.0, 0.78));
+  vec3 color = surfaceColor * (0.32 + 0.68 * lighting.ambientColor);
+
+  for (int i = 0; i < lighting.directionalLightCount; i++) {
+    DirectionalLight directionalLight = lighting_getDirectionalLight(i);
+    vec3 lightDirection = normalize(-directionalLight.direction);
+    vec3 halfwayDirection = normalize(lightDirection + viewDirection);
+    float diffuse = max(dot(waterNormal, lightDirection), 0.0);
+    float specular = pow(max(dot(waterNormal, halfwayDirection), 0.0), 64.0);
+    float brokenSpecular = specular * (0.25 + 0.75 * fresnel);
+    color += surfaceColor * directionalLight.color * diffuse * 0.38;
+    color += vec3(0.72, 0.88, 0.94) * directionalLight.color * brokenSpecular * 2.1;
+  }
+
+  color = mix(color, reflectedColor, clamp(fresnel * 0.3, 0.0, 0.3));
+  return vec4(color, waterMaterial.opacity);
+}
+`;