@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/fx/water-wgsl.js

@@ -0,0 +1,197 @@
+import { WGSL_PBR } from '../render/pbr-wgsl.js';
+import { WGSL_GLOBALS, WGSL_LIGHTS, WGSL_NOISE } from '../render/wgsl.js';
+/** Wave layers the params block carries (`WaterOptions.waves` beyond this are ignored). */
+export const WATER_MAX_WAVES = 4;
+/**
+ * The water shader: a plane in the engine's 3D vertex layout, no instance, group 1 = the
+ * water's params block and its copy of the scene depth.
+ *
+ * Waves. Each layer is an analytic field with a closed-form gradient (`water_wave`):
+ * `p = (x, z) * scale + dir * (t * speed)`, `a = p.x + 0.6 sin(1.3 p.y)`,
+ * `b = 0.8 p.y + 0.5 sin(0.9 p.x)`, value `sin(a) cos(b)` in -1..1, and its derivatives by the
+ * chain rule. The height is `level + displace * Σ amplitude_i * value_i` (the vertex shader
+ * offsets y by it; `waterHeight` in `water.ts` is the same sum in TypeScript), and the normal
+ * is `normalize(-slope.x, 1, -slope.z)` with `slope = Σ amplitude_i * scale_i * grad_i`, so
+ * `amplitude` is the normal strength whether or not vertices move.
+ *
+ * Shading, all linear: the view ray's Schlick Fresnel (f0 0.02) times `fresnel` lerps the
+ * refraction colour (`shallow` → `deep` by the linear depth below the surface over
+ * `depth_fade`, from the depth copy) towards the reflection colour (a sky gradient between
+ * `lights.fog.rgb`, or a pale haze without fog, at the horizon and a bluer zenith, darkened at
+ * night like `Sky`); the sun adds a GGX lobe of `roughness` (`engine_d_ggx`,
+ * `engine_v_smith_ggx`, `engine_f_schlick` from `WGSL_PBR`), which also goes to the emissive
+ * target so bloom picks it up; foam (`foam.w` > 0) mixes `foam.rgb` in where the depth below the
+ * surface is under `foam.w`, through a two-octave noise mask; the alpha ramps up from zero at
+ * the shoreline over a quarter of `depth_fade` to `opacity`, then `engine_fog`.
+ *
+ * Depth copy. `misc.z` says whether `scene_depth` holds this frame's copy. Its texel is turned
+ * into view-space z (`view_z_of`) and compared with the fragment's own: the difference is the
+ * water depth along the ray. A texel within a sliver of the fragment's own depth is the water
+ * surface itself (the copy was taken after a frame that drew this water into the same depth
+ * buffer) and counts as no information: fully deep, no foam. Without a copy the surface is
+ * deep everywhere, foam off.
+ */
+export const WATER_WGSL = /* wgsl */ `
+${WGSL_GLOBALS}
+${WGSL_LIGHTS}
+${WGSL_NOISE}
+${WGSL_PBR}
+struct WaterParams {
+  shallow: vec4f,     // rgb, opacity
+  deep: vec4f,        // rgb, depth fade (world units)
+  surface: vec4f,     // fresnel, roughness, displace, level
+  foam: vec4f,        // rgb, width (0 = off)
+  misc: vec4f,        // time, wave count, depth copy on, origin y
+  waves: array<vec4f, ${WATER_MAX_WAVES}>, // scale, speed, amplitude, direction angle
+};
+@group(1) @binding(0) var<uniform> water: WaterParams;
+@group(1) @binding(1) var scene_depth: texture_depth_2d;
+
+struct VertexIn {
+  @location(0) pos: vec3f,
+  @location(10) normal: vec3f,
+  @location(1) uv: vec2f,
+  @location(2) color: vec4f,
+};
+
+struct WaterOut {
+  @builtin(position) clip: vec4f,
+  @location(0) world: vec3f,
+  @location(1) view_z: f32,
+};
+
+struct FragOut {
+  @location(0) color: vec4f,
+  @location(1) emissive: vec4f,
+};
+
+// One layer's value and gradient (d/dp.x, d/dp.y) at p.
+fn water_wave(p: vec2f) -> vec3f {
+  let a = p.x + 0.6 * sin(1.3 * p.y);
+  let b = 0.8 * p.y + 0.5 * sin(0.9 * p.x);
+  let sa = sin(a);
+  let ca = cos(a);
+  let sb = sin(b);
+  let cb = cos(b);
+  let dx = ca * cb - sa * sb * 0.45 * cos(0.9 * p.x);
+  let dy = ca * cb * 0.78 * cos(1.3 * p.y) - sa * sb * 0.8;
+  return vec3f(sa * cb, dx, dy);
+}
+
+// Summed layers at world (x, z): height sum (before displace) and the normal slope.
+fn water_field(xz: vec2f, t: f32) -> vec3f {
+  var h = 0.0;
+  var slope = vec2f(0.0);
+  let n = u32(water.misc.y);
+  for (var i = 0u; i < n; i++) {
+    let w = water.waves[i];
+    let dir = vec2f(cos(w.w), sin(w.w));
+    let p = xz * w.x + dir * (t * w.y);
+    let f = water_wave(p);
+    h += w.z * f.x;
+    slope += w.z * w.x * f.yz;
+  }
+  return vec3f(h, slope);
+}
+
+@vertex fn vs(v: VertexIn) -> WaterOut {
+  let t = water.misc.x;
+  let f = water_field(v.pos.xz, t);
+  let world = vec3f(v.pos.x, water.misc.w + water.surface.w + water.surface.z * f.x, v.pos.z);
+  var o: WaterOut;
+  o.clip = camera.view_proj * vec4f(world, 1.0);
+  o.world = world;
+  o.view_z = (camera.view * vec4f(world, 1.0)).z;
+  return o;
+}
+
+// View-space z of a depth-buffer value under camera.proj (any perspective or ortho matrix).
+fn view_z_of(d: f32) -> f32 {
+  let p = camera.proj;
+  let den = d * p[2][3] - p[2][2];
+  return (p[3][2] - d * p[3][3]) / select(den, 1e-6, abs(den) < 1e-6);
+}
+
+@fragment fn fs(in: WaterOut) -> FragOut {
+  let t = water.misc.x;
+  let f = water_field(in.world.xz, t);
+  let n = normalize(vec3f(-f.y, 1.0, -f.z));
+  let v = normalize(camera.camera_pos.xyz - in.world);
+  let n_dot_v = max(dot(n, v), 1e-4);
+  let depth_fade = max(water.deep.w, 1e-3);
+
+  // Water depth along the view ray, from the depth copy.
+  var diff = depth_fade;
+  var has_depth = false;
+  if (water.misc.z > 0.5) {
+    let dims = vec2i(textureDimensions(scene_depth));
+    let px = clamp(vec2i(in.clip.xy), vec2i(0), dims - 1);
+    let scene_z = view_z_of(textureLoad(scene_depth, px, 0));
+    let own = abs(scene_z - in.view_z) < 0.002 * abs(in.view_z) + 1e-3;
+    if (!own) {
+      diff = max(in.view_z - scene_z, 0.0);
+      has_depth = true;
+    }
+  }
+  let deep_t = saturate(diff / depth_fade);
+  let refraction = mix(water.shallow.rgb, water.deep.rgb, deep_t);
+
+  // Reflection: the sky gradient the reflected ray would see.
+  let r = reflect(-v, n);
+  let has_fog = lights.fog.w > 0.0;
+  let horizon = select(vec3f(0.62, 0.72, 0.9), lights.fog.rgb, has_fog);
+  let zenith = horizon * vec3f(0.35, 0.55, 1.0);
+  let to_sun = -lights.sun_dir;
+  let has_sun = dot(lights.sun_color, vec3f(1.0)) > 0.0;
+  let day = select(1.0, smoothstep(-0.12, 0.08, to_sun.y), has_sun);
+  let sky = mix(horizon, zenith, pow(saturate(r.y), 0.6)) * mix(0.06, 1.0, day);
+
+  let fresnel = water.surface.x * engine_f_schlick(vec3f(0.02), n_dot_v).x;
+  var col = mix(refraction, sky, saturate(fresnel));
+
+  // Sun highlight.
+  var spec = vec3f(0.0);
+  let n_dot_l = dot(n, to_sun);
+  if (has_sun && n_dot_l > 0.0) {
+    let rough = max(water.surface.y, ENGINE_MIN_ROUGHNESS);
+    let a2 = rough * rough * rough * rough;
+    let h = normalize(to_sun + v);
+    let d = engine_d_ggx(saturate(dot(n, h)), a2);
+    let vis = engine_v_smith_ggx(n_dot_v, n_dot_l, a2);
+    let f_s = engine_f_schlick(vec3f(0.02), saturate(dot(v, h)));
+    spec = lights.sun_color * (d * vis * ENGINE_PI * n_dot_l) * f_s;
+  }
+  col += spec;
+
+  // Alpha: transparent at the shoreline, opacity further out.
+  var alpha = water.shallow.w * smoothstep(0.0, 0.25 * depth_fade, diff);
+
+  // Foam against geometry.
+  var foam = 0.0;
+  if (has_depth && water.foam.w > 0.0) {
+    let edge = saturate(1.0 - diff / water.foam.w);
+    let mask = 0.65 * engine_noise(in.world.xz * 5.0 + vec2f(t * 0.4, -t * 0.3))
+      + 0.35 * engine_noise(in.world.xz * 13.0 - vec2f(t * 0.9, t * 0.5));
+    foam = edge * smoothstep(0.42, 0.72, mask + 0.4 * edge);
+    col = mix(col, water.foam.rgb, foam);
+    alpha = max(alpha, foam * water.shallow.w);
+  }
+
+  col = engine_fog(col, in.world);
+  var o: FragOut;
+  o.color = vec4f(col * alpha, alpha);
+  o.emissive = vec4f(spec * alpha, alpha);
+  return o;
+}
+`;
+/** Copies a depth texture into the water's own depth32float copy (one fullscreen triangle). */
+export const WATER_DEPTH_COPY_WGSL = /* wgsl */ `
+@group(0) @binding(0) var src: texture_depth_2d;
+@vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {
+  let p = vec2f(f32((i << 1u) & 2u), f32(i & 2u));
+  return vec4f(p * 2.0 - 1.0, 0.0, 1.0);
+}
+@fragment fn fs(@builtin(position) pos: vec4f) -> @builtin(frag_depth) f32 {
+  return textureLoad(src, vec2i(pos.xy), 0);
+}
+`;

package/dist/fx/water.d.ts

@@ -0,0 +1,176 @@
+import type { Drawable, Frame, ViewInfo } from '../render/frame.js';
+import { type Mesh } from '../render/mesh.js';
+import type { Renderer } from '../render/renderer.js';
+import type { SceneTarget } from '../render/scene-target.js';
+/** Floats in the water's params block: 5 vec4 + `WATER_MAX_WAVES` vec4 (144 bytes). */
+export declare const WATER_PARAMS_FLOATS: number;
+/** One scrolling wave layer (`WaterOptions.waves`, `Water.waves`). */
+export interface WaterWave {
+    /** World units → field units (bigger is choppier). */
+    scale: number;
+    /** Field units scrolled per second. */
+    speed: number;
+    /** Normal strength (and, times `displace`, height) of the layer. */
+    amplitude: number;
+    /** Scroll direction in the xz plane; normalised when packed. */
+    direction: [number, number];
+}
+/** Foam settings (`WaterOptions.foam`, `Water.foam`); `null` for none. */
+export interface WaterFoam {
+    /** World units of water depth under which foam forms. Default 0.4. */
+    width: number;
+    /** Linear RGB. Default near white. */
+    color: ArrayLike<number>;
+}
+export interface WaterOptions {
+    /** Plane extent along x and z (one number for a square). Default 100. Fixed at construction. */
+    size?: number | [number, number];
+    /** Grid subdivisions; `displace` needs more than 1 to show. Default 1. Fixed at construction. */
+    segments?: number | [number, number];
+    /** Surface height (y), relative to `origin`. Default 0. */
+    level?: number;
+    /**
+     * World position of the plane's centre: x and z are baked into the mesh, y is added to
+     * `level` (a world whose corner is the origin puts its water at `[sizeX / 2, 0, sizeZ / 2]`).
+     * Default `[0, 0, 0]`. Fixed at construction.
+     */
+    origin?: ArrayLike<number>;
+    /** Linear RGB where the water is shallow. */
+    shallowColor?: ArrayLike<number>;
+    /** Linear RGB at full depth. */
+    deepColor?: ArrayLike<number>;
+    /** World units of water depth at which the tint reaches `deepColor`. Default 4. */
+    depthFade?: number;
+    /** Reflection strength, 0..1 (the weight of the sky colour at grazing angles). Default 0.6. */
+    fresnel?: number;
+    /** Roughness of the sun highlight. Default 0.08. */
+    roughness?: number;
+    /** Wave layers (up to `WATER_MAX_WAVES`). Default two layers. */
+    waves?: WaterWave[];
+    /** Foam where the surface meets geometry; `null` for none. Default on, width 0.4. */
+    foam?: Partial<WaterFoam> | null;
+    /** Vertex height amplitude of the summed layers. Default 0 (flat mesh, normals still move). */
+    displace?: number;
+    /** Alpha away from the shoreline. Default 0.85. */
+    opacity?: number;
+    /** Where to copy the scene depth from (`renderer.target` by default). */
+    depthTarget?: SceneTarget;
+    /**
+     * Take this frame's opaque depth from the renderer's depth hook (`Drawable.readsDepth`,
+     * ws/render-hooks) instead of copying the previous frame's in `prepare`: the view splits its
+     * scene pass and the water samples the renderer's copy. Only a view with `depthTest` splits;
+     * elsewhere the water is then deep everywhere (no copy of its own). Default false.
+     */
+    readsDepth?: boolean;
+}
+/**
+ * An animated water surface: a plane from `geom`'s `plane` whose shader sums scrolling
+ * analytic wave layers for the normal (and the height when `displace` > 0), lerps a depth-tinted
+ * refraction colour towards a sky reflection by Fresnel, adds the sun's GGX highlight (also to
+ * the emissive target), fades to transparent at the shoreline and foams where the water is
+ * shallower than `foam.width`. `frame.drawable(water, order)` draws it after opaque geometry
+ * (drawables sort as blended); `update(dt)` advances the waves.
+ *
+ * Every field is live; `prepare` packs them into one `WATER_PARAMS_FLOATS` params block per
+ * frame. The sun, its colour and the fog colour (the horizon of the reflection) come from
+ * `frame.lights`; `Sky` present or not.
+ *
+ * Depth: under a depth camera the water tests and writes depth (`less-equal`), so particles and
+ * trails sort against it, and `prepare` copies the scene depth (`depthTarget ?? renderer.target`,
+ * its `SceneTarget.depth`) into its own `depth32float` texture for the depth fade, the shoreline
+ * alpha and the foam. The copy runs before this frame's scene pass, so it holds what the target
+ * held then: the previous frame's depth (which includes this water's own surface, read as "no
+ * information": deep, no foam) or that of an earlier `renderer.render` call this frame. For a
+ * shoreline, draw the water on its own layer in a second view of the same camera, after the
+ * opaque view (`harness/water.ts` does). Without a depth camera there is no copy: the surface is
+ * deep everywhere, foam off, and the pipeline has no depth state.
+ */
+export declare class Water implements Drawable {
+    /** Surface height (y) above `origin`. Live. */
+    level: number;
+    /** World position of the plane's centre (`WaterOptions.origin`). Fixed. */
+    readonly origin: Float32Array<ArrayBuffer>;
+    /** Linear RGB where the water is shallow. Live. */
+    readonly shallowColor: Float32Array<ArrayBuffer>;
+    /** Linear RGB at full depth. Live. */
+    readonly deepColor: Float32Array<ArrayBuffer>;
+    /** World units of water depth to full `deepColor`. Live. */
+    depthFade: number;
+    /** Reflection strength, 0..1. Live. */
+    fresnel: number;
+    /** Roughness of the sun highlight. Live. */
+    roughness: number;
+    /** Wave layers; the first `WATER_MAX_WAVES` are uploaded. Live (replace or mutate). */
+    waves: WaterWave[];
+    /** Foam settings, or null for none. Live (replace or mutate). */
+    foam: WaterFoam | null;
+    /** Vertex height amplitude. Live. */
+    displace: number;
+    /** Alpha away from the shoreline. Live. */
+    opacity: number;
+    /** Where the scene depth is copied from; null for `renderer.target`. Live. */
+    depthTarget: SceneTarget | null;
+    /** See `WaterOptions.readsDepth`. Live. */
+    readsDepth: boolean;
+    /** Seconds `update` has advanced; the waves' clock. */
+    time: number;
+    /** The plane, owned; drawn through this drawable's own pipeline. */
+    readonly mesh: Mesh;
+    private readonly renderer;
+    private readonly device;
+    private readonly params;
+    private readonly paramsBuffer;
+    private readonly layout;
+    private readonly dummy;
+    private readonly dummyGroup;
+    private readonly desc;
+    /**
+     * Pipelines per depth format (null: none; a depth one writes depth) × the view target's aux
+     * key, built on first use from `renderer.sceneTargets` (ws/render-10).
+     */
+    private readonly pipelines;
+    private readonly copyLayout;
+    private readonly copyPipeline;
+    private readonly copyAtt;
+    private readonly copyPass;
+    private copy;
+    private copyGroup;
+    private src;
+    private srcGroup;
+    /** The depth copy ran this frame (`draw` binds it and the shader reads it). */
+    private depthOn;
+    /** The renderer's `depthCopy` view the hook group was made for (`readsDepth`). */
+    private hookView;
+    private hookGroup;
+    /** The group `draw` binds: own copy, the renderer's copy, or the 1×1 stand-in. */
+    private depthGroup;
+    constructor(renderer: Renderer, opts?: WaterOptions);
+    /** Advance the waves' clock. */
+    update(dt: number): void;
+    /**
+     * Copy the scene depth (under a depth camera) and pack the live fields into the params block
+     * (`WATER_PARAMS_FLOATS` floats: shallow rgb + opacity, deep rgb + depthFade, fresnel,
+     * roughness, displace, level, foam rgb + width, time, wave count, depth copy on, 0, then
+     * scale, speed, amplitude, direction angle per wave). Called by the renderer once per frame.
+     * No allocation in steady state.
+     */
+    prepare(encoder: GPUCommandEncoder, frame?: Frame): void;
+    /** Draw inside the scene pass: the plane, a depth-writing pipeline when the frame has depth. */
+    draw(pass: GPURenderPassEncoder, frame?: Frame): void;
+    /**
+     * The renderer's depth hook (`readsDepth`): bind this frame's opaque depth copy and flip the
+     * shader's depth flag on (a 4-byte write; `queue.writeBuffer` lands before the frame's
+     * commands run). A new bind group only when the copy texture changed (resize).
+     */
+    afterOpaque(_encoder: GPUCommandEncoder, view: ViewInfo): void;
+    private copyDepth;
+    private makeGroup;
+    private pipelineFor;
+    destroy(): void;
+}
+/**
+ * The surface height at world (`x`, `z`) at time `t` (default `water.time`): the origin's y
+ * plus `level` plus `displace` times the summed wave layers, the formula the vertex shader
+ * runs. Pure; no allocation. With `displace` 0 it is `origin[1] + level`.
+ */
+export declare function waterHeight(water: Water, x: number, z: number, t?: number): number;