@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/render/parallax.js

@@ -0,0 +1,47 @@
+/** Wrapped parallax offset: `camera - (camera × factor mod wrap)`, in `camera - wrap .. camera`. */
+export function parallaxOffset(camera, factor, wrap) {
+    if (wrap === undefined || !(wrap > 0))
+        return camera * (1 - factor);
+    const scroll = camera * factor;
+    return camera - (((scroll % wrap) + wrap) % wrap);
+}
+/**
+ * Make a `Parallax` over layers built on `renderer`. Each layer's `origin` at this moment is its
+ * base position. Allocates once.
+ */
+export function createParallax(_renderer, layers) {
+    const list = layers.map((l) => ({
+        layer: l.layer,
+        factorX: l.factorX,
+        factorY: l.factorY,
+        wrapW: l.wrapW,
+        wrapH: l.wrapH,
+        params: l.params,
+        baseX: l.layer.origin.x,
+        baseY: l.layer.origin.y,
+        offsetX: 0,
+        offsetY: 0,
+    }));
+    return {
+        layers: list,
+        update(cameraX, cameraY) {
+            for (let i = 0; i < list.length; i++) {
+                const l = list[i];
+                l.offsetX = parallaxOffset(cameraX, l.factorX, l.wrapW);
+                l.offsetY = parallaxOffset(cameraY, l.factorY, l.wrapH);
+                l.layer.origin.x = l.baseX + l.offsetX;
+                l.layer.origin.y = l.baseY + l.offsetY;
+            }
+        },
+        draw(frame) {
+            for (let i = 0; i < list.length; i++) {
+                const l = list[i];
+                l.layer.draw(frame, l.params);
+            }
+        },
+        destroy() {
+            for (const l of list)
+                l.layer.destroy();
+        },
+    };
+}

package/dist/render/pbr-wgsl.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Physically based shading helpers for custom materials (`WGSL_PBR`). Appended by
+ * `createStandardMaterial`; a game's own material appends the same text after the prelude and
+ * calls `engine_pbr` from its `fs_main`. Everything here reads the engine's lighting block
+ * (`lights`, `engine_shadow`, `engine_fog` from `WGSL_LIGHTS`) and the camera block, so it only
+ * compiles after `materialPrelude`.
+ *
+ * Model: GGX normal distribution (`engine_d_ggx`), height-correlated Smith-GGX visibility
+ * (`engine_v_smith_ggx`), Schlick Fresnel (`engine_f_schlick`) and Lambert diffuse. Radiance is
+ * in the same units as `engine_lambert`: a light of colour `c` on a white rough dielectric facing
+ * it returns about `c` (the specular lobe is scaled by π to match, so a PBR material and a Lambert
+ * one agree on brightness under the same `Lights`).
+ *
+ * `engine_pbr_layers(base, metallic, roughness, N, V, world_pos, ao, emissive, layer_mask)` sums
+ * ambient × `ao` (diffuse plus a roughness-aware Fresnel term so metals are not black in the
+ * dark), every light of the block whose `layers` share a bit with `layer_mask` through
+ * `engine_pbr_accum` (the engine light loop, `wgslLightLoop` with `engine_brdf`: the sun ×
+ * `engine_shadow`, the point lights with the `(1 - d/radius)²` falloff of `engine_point_lights`,
+ * the spot lights with that falloff × `engine_spot_cone`) and `emissive`, then applies
+ * `engine_fog`. `N` and `V` are unit world-space vectors; `V` points from the surface to the eye.
+ * `engine_pbr(base, metallic, roughness, N, V, world_pos, ao, emissive)` is the same over every
+ * layer (`0xffffffffu`); the standard material passes `engine_instance_layers(in.flags)`.
+ *
+ * `engine_perturb_normal(n, world_pos, uv, map, scale)` applies a tangent-space normal map
+ * (`map` is the decoded texel, 0..1; +Y is up in the image, the OpenGL / glTF convention; `scale`
+ * scales its xy) using a tangent frame built from screen-space derivatives (`dpdx` / `dpdy` of the
+ * world position and the uv), so meshes need no tangent attribute: `VERTEX_LAYOUT_3D` has none
+ * (xyz, normal, uv, rgba). It is fragment-stage only. When the uv has no screen-space change
+ * (a collapsed uv rect, a sliver) it returns `n`.
+ */
+export declare const WGSL_PBR: string;

package/dist/render/pbr-wgsl.js

@@ -0,0 +1,119 @@
+import { wgslLightLoop } from './wgsl.js';
+/**
+ * Physically based shading helpers for custom materials (`WGSL_PBR`). Appended by
+ * `createStandardMaterial`; a game's own material appends the same text after the prelude and
+ * calls `engine_pbr` from its `fs_main`. Everything here reads the engine's lighting block
+ * (`lights`, `engine_shadow`, `engine_fog` from `WGSL_LIGHTS`) and the camera block, so it only
+ * compiles after `materialPrelude`.
+ *
+ * Model: GGX normal distribution (`engine_d_ggx`), height-correlated Smith-GGX visibility
+ * (`engine_v_smith_ggx`), Schlick Fresnel (`engine_f_schlick`) and Lambert diffuse. Radiance is
+ * in the same units as `engine_lambert`: a light of colour `c` on a white rough dielectric facing
+ * it returns about `c` (the specular lobe is scaled by π to match, so a PBR material and a Lambert
+ * one agree on brightness under the same `Lights`).
+ *
+ * `engine_pbr_layers(base, metallic, roughness, N, V, world_pos, ao, emissive, layer_mask)` sums
+ * ambient × `ao` (diffuse plus a roughness-aware Fresnel term so metals are not black in the
+ * dark), every light of the block whose `layers` share a bit with `layer_mask` through
+ * `engine_pbr_accum` (the engine light loop, `wgslLightLoop` with `engine_brdf`: the sun ×
+ * `engine_shadow`, the point lights with the `(1 - d/radius)²` falloff of `engine_point_lights`,
+ * the spot lights with that falloff × `engine_spot_cone`) and `emissive`, then applies
+ * `engine_fog`. `N` and `V` are unit world-space vectors; `V` points from the surface to the eye.
+ * `engine_pbr(base, metallic, roughness, N, V, world_pos, ao, emissive)` is the same over every
+ * layer (`0xffffffffu`); the standard material passes `engine_instance_layers(in.flags)`.
+ *
+ * `engine_perturb_normal(n, world_pos, uv, map, scale)` applies a tangent-space normal map
+ * (`map` is the decoded texel, 0..1; +Y is up in the image, the OpenGL / glTF convention; `scale`
+ * scales its xy) using a tangent frame built from screen-space derivatives (`dpdx` / `dpdy` of the
+ * world position and the uv), so meshes need no tangent attribute: `VERTEX_LAYOUT_3D` has none
+ * (xyz, normal, uv, rgba). It is fragment-stage only. When the uv has no screen-space change
+ * (a collapsed uv rect, a sliver) it returns `n`.
+ */
+export const WGSL_PBR = /* wgsl */ `
+const ENGINE_PI: f32 = 3.14159265;
+const ENGINE_MIN_ROUGHNESS: f32 = 0.045;
+
+fn engine_d_ggx(n_dot_h: f32, a2: f32) -> f32 {
+  let d = n_dot_h * n_dot_h * (a2 - 1.0) + 1.0;
+  return a2 / (ENGINE_PI * d * d + 1e-7);
+}
+
+fn engine_v_smith_ggx(n_dot_v: f32, n_dot_l: f32, a2: f32) -> f32 {
+  let gv = n_dot_l * sqrt(n_dot_v * n_dot_v * (1.0 - a2) + a2);
+  let gl = n_dot_v * sqrt(n_dot_l * n_dot_l * (1.0 - a2) + a2);
+  return 0.5 / (gv + gl + 1e-5);
+}
+
+fn engine_f_schlick(f0: vec3f, v_dot_h: f32) -> vec3f {
+  let f = pow(1.0 - v_dot_h, 5.0);
+  return f0 + (vec3f(1.0) - f0) * f;
+}
+
+/** One light's reflected radiance factor: (diffuse + specular) × N·L, before the light colour. */
+fn engine_brdf(
+  n: vec3f, v: vec3f, l: vec3f, diffuse_color: vec3f, f0: vec3f, a2: f32, n_dot_v: f32,
+) -> vec3f {
+  let n_dot_l = dot(n, l);
+  if (n_dot_l <= 0.0) { return vec3f(0.0); }
+  let h = normalize(l + v);
+  let n_dot_h = saturate(dot(n, h));
+  let v_dot_h = saturate(dot(v, h));
+  let d = engine_d_ggx(n_dot_h, a2);
+  let vis = engine_v_smith_ggx(n_dot_v, n_dot_l, a2);
+  let f = engine_f_schlick(f0, v_dot_h);
+  let specular = (d * vis * ENGINE_PI) * f;
+  return (diffuse_color + specular) * n_dot_l;
+}
+
+${wgslLightLoop('engine_pbr_accum', 'engine_brdf(normal, v, l, diffuse_color, f0, a2, n_dot_v)', ', v: vec3f, diffuse_color: vec3f, f0: vec3f, a2: f32, n_dot_v: f32')}
+
+fn engine_pbr_layers(
+  base: vec3f, metallic: f32, roughness: f32, n: vec3f, v: vec3f, world_pos: vec3f,
+  ao: f32, emissive: vec3f, layer_mask: u32,
+) -> vec3f {
+  let r = clamp(roughness, ENGINE_MIN_ROUGHNESS, 1.0);
+  let a = r * r;
+  let a2 = a * a;
+  let m = saturate(metallic);
+  let f0 = mix(vec3f(0.04), base, m);
+  let diffuse_color = base * (1.0 - m);
+  let n_dot_v = max(dot(n, v), 1e-4);
+  // Ambient: diffuse plus a roughness-aware Fresnel so metals keep their colour in the dark.
+  let fr = max(vec3f(1.0 - r), f0) - f0;
+  let ambient_spec = f0 + fr * pow(1.0 - n_dot_v, 5.0);
+  var color = lights.ambient * ao * (diffuse_color + ambient_spec);
+  color += engine_pbr_accum(world_pos, n, layer_mask, v, diffuse_color, f0, a2, n_dot_v);
+  color += emissive;
+  return engine_fog(color, world_pos);
+}
+
+fn engine_pbr(
+  base: vec3f, metallic: f32, roughness: f32, n: vec3f, v: vec3f, world_pos: vec3f,
+  ao: f32, emissive: vec3f,
+) -> vec3f {
+  return engine_pbr_layers(base, metallic, roughness, n, v, world_pos, ao, emissive, 0xffffffffu);
+}
+
+fn engine_perturb_normal(n: vec3f, world_pos: vec3f, uv: vec2f, map: vec3f, scale: f32) -> vec3f {
+  let dp1 = dpdx(world_pos);
+  let dp2 = dpdy(world_pos);
+  let duv1 = dpdx(uv);
+  let duv2 = dpdy(uv);
+  // Solve dp1 = t du1 + b dv1, dp2 = t du2 + b dv2 for t and b (times |det|: only the sign of
+  // the determinant matters, the lengths are normalised away below). Unlike the cross-product
+  // frame this does not assume cross(dp1, dp2) points along n, which it does not with a y-down
+  // framebuffer.
+  let det = duv1.x * duv2.y - duv2.x * duv1.y;
+  let s = select(-1.0, 1.0, det >= 0.0);
+  var t = (dp1 * duv2.y - dp2 * duv1.y) * s;
+  var b = (dp2 * duv1.x - dp1 * duv2.x) * s;
+  t -= n * dot(n, t);
+  b -= n * dot(n, b);
+  let m2 = max(dot(t, t), dot(b, b));
+  if (m2 < 1e-16) { return n; }
+  let inv = inverseSqrt(m2);
+  // uv v runs down the image, so the map's +Y (up in the image) is -b.
+  let tn = (map * 2.0 - 1.0) * vec3f(scale, scale, 1.0);
+  return normalize(t * inv * tn.x - b * inv * tn.y + n * tn.z);
+}
+`;

package/dist/render/ping-pong.d.ts

@@ -0,0 +1,42 @@
+import type { FullscreenPass } from './fullscreen.js';
+import { Texture, type TextureDesc } from './texture.js';
+export interface PingPongStepOptions {
+    /** Texture slot of `pass` that reads the previous state. Default 0. */
+    slot?: number;
+    /** Clear colour for the write target; `null` loads it. Default transparent black. */
+    clear?: GPUColor | null;
+}
+/**
+ * Two same-sized render targets for feedback effects (fluid sims, trails, blur chains):
+ * each `step` runs a fullscreen pass that reads `read` and writes `write`, then swaps.
+ * Alternating textures reuses cached bind groups, so a steady ping-pong allocates nothing.
+ *
+ * ```ts
+ * const sim = renderer.createPingPong({ width: 256, height: 256, label: 'sim' });
+ * frame.prePass(stepSim);               // a stable function:
+ * function stepSim(enc: GPUCommandEncoder) {
+ *   sim.step(enc, simPass);             // simPass samples slot 0 = previous state
+ *   material.setTexture(0, sim.read);   // sample the newest state in this frame's draws
+ * }
+ * ```
+ */
+export declare class PingPong {
+    private readonly device;
+    private readonly desc;
+    private a;
+    private b;
+    constructor(device: GPUDevice, desc: TextureDesc);
+    /** The latest state (written by the last `step`). Sample this. */
+    get read(): Texture;
+    /** The target the next `step` writes. */
+    get write(): Texture;
+    get width(): number;
+    get height(): number;
+    swap(): void;
+    /** Encode `pass` reading `read` (texture `slot`) into `write`, then swap. */
+    step(encoder: GPUCommandEncoder, pass: FullscreenPass, opts?: PingPongStepOptions): void;
+    /** Recreate both targets at a new size (contents are lost). No-op when unchanged. */
+    resize(width: number, height: number): void;
+    destroy(): void;
+    private make;
+}

package/dist/render/ping-pong.js

@@ -0,0 +1,74 @@
+import { Texture } from './texture.js';
+/**
+ * Two same-sized render targets for feedback effects (fluid sims, trails, blur chains):
+ * each `step` runs a fullscreen pass that reads `read` and writes `write`, then swaps.
+ * Alternating textures reuses cached bind groups, so a steady ping-pong allocates nothing.
+ *
+ * ```ts
+ * const sim = renderer.createPingPong({ width: 256, height: 256, label: 'sim' });
+ * frame.prePass(stepSim);               // a stable function:
+ * function stepSim(enc: GPUCommandEncoder) {
+ *   sim.step(enc, simPass);             // simPass samples slot 0 = previous state
+ *   material.setTexture(0, sim.read);   // sample the newest state in this frame's draws
+ * }
+ * ```
+ */
+export class PingPong {
+    device;
+    desc;
+    a;
+    b;
+    constructor(device, desc) {
+        this.device = device;
+        this.desc = desc;
+        this.a = this.make('a');
+        this.b = this.make('b');
+    }
+    /** The latest state (written by the last `step`). Sample this. */
+    get read() {
+        return this.a;
+    }
+    /** The target the next `step` writes. */
+    get write() {
+        return this.b;
+    }
+    get width() {
+        return this.a.width;
+    }
+    get height() {
+        return this.a.height;
+    }
+    swap() {
+        const t = this.a;
+        this.a = this.b;
+        this.b = t;
+    }
+    /** Encode `pass` reading `read` (texture `slot`) into `write`, then swap. */
+    step(encoder, pass, opts = {}) {
+        pass.setTexture(opts.slot ?? 0, this.a);
+        pass.encode(encoder, this.b.view, { clear: opts.clear });
+        this.swap();
+    }
+    /** Recreate both targets at a new size (contents are lost). No-op when unchanged. */
+    resize(width, height) {
+        const w = Math.max(1, Math.floor(width));
+        const h = Math.max(1, Math.floor(height));
+        if (w === this.a.width && h === this.a.height)
+            return;
+        this.destroy();
+        this.desc.width = w;
+        this.desc.height = h;
+        this.a = this.make('a');
+        this.b = this.make('b');
+    }
+    destroy() {
+        this.a.destroy();
+        this.b.destroy();
+    }
+    make(which) {
+        return new Texture(this.device, {
+            ...this.desc,
+            label: `${this.desc.label ?? 'ping-pong'}:${which}`,
+        });
+    }
+}