@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/fx/decals-wgsl.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Depth-projected box decal. The vertex shader places the unit box; the fragment shader
+ * reconstructs the world position under each pixel from the previous frame's depth copy
+ * (`inv_view_proj × (ndc, depth)`), maps it into the box, rejects what falls outside, samples
+ * the atlas by the local xy and fades by the local z edge, the surface's facing (its normal
+ * from `dpdx`/`dpdy` of the reconstructed position against the box axis) and the age.
+ */
+export declare const WGSL_DECAL_BOX = "\nstruct EngineGlobals {\n  logicalSize: vec2f,\n  targetSize: vec2f,\n  time: f32,\n  dt: f32,\n  _pad: vec2f,\n};\n@group(0) @binding(0) var<uniform> globals: EngineGlobals;\nstruct EngineCamera {\n  view: mat4x4f,\n  proj: mat4x4f,\n  view_proj: mat4x4f,\n  camera_pos: vec4f,\n  viewport: vec4f,\n  view_index: u32,\n  _pad0: u32, _pad1: u32, _pad2: u32,\n  inv_view_proj: mat4x4f,\n  prev_view_proj: mat4x4f,\n  prev_view: mat4x4f,\n  jitter: vec4f,\n};\n@group(0) @binding(1) var<uniform> camera: EngineCamera;\n\nstruct DecalParams {\n  inv_view_proj: mat4x4f,\n  // normal_bias, fade_edge, offset, multiply (1 = multiply blend)\n  shape: vec4f,\n  // fade at age 0, fade at age 1, pad, pad\n  fade: vec4f,\n};\n@group(1) @binding(0) var<uniform> decal: DecalParams;\n@group(1) @binding(1) var decal_sampler: sampler;\n@group(1) @binding(2) var decal_tex: texture_2d<f32>;\n@group(1) @binding(3) var scene_depth: texture_depth_2d;\n\nstruct DecalVertex {\n  @location(0) position: vec3f,\n  @location(3) m0: vec4f,\n  @location(4) m1: vec4f,\n  @location(5) m2: vec4f,\n  @location(6) uv_rect: vec4f,\n  @location(7) color: vec4f,\n  @location(8) life: vec4f,\n};\n\nstruct DecalFrame {\n  origin: vec3f,\n  ax: vec3f,\n  ay: vec3f,\n  az: vec3f,\n  normal: vec3f,\n};\n\n// The rows of the world \u2192 local matrix are axis_i / scale_i and -dot(axis_i, origin) / scale_i:\n// local \u2192 world is origin + sum(axis_i * scale_i * local_i).\nfn decal_frame(m0: vec4f, m1: vec4f, m2: vec4f) -> DecalFrame {\n  var f: DecalFrame;\n  let s0 = 1.0 / max(dot(m0.xyz, m0.xyz), 1e-12);\n  let s1 = 1.0 / max(dot(m1.xyz, m1.xyz), 1e-12);\n  let s2 = 1.0 / max(dot(m2.xyz, m2.xyz), 1e-12);\n  f.ax = m0.xyz * s0;\n  f.ay = m1.xyz * s1;\n  f.az = m2.xyz * s2;\n  f.origin = -(f.ax * m0.w + f.ay * m1.w + f.az * m2.w);\n  f.normal = normalize(m2.xyz);\n  return f;\n}\n\nstruct FragOut {\n  @location(0) color: vec4f,\n  @location(1) emissive: vec4f,\n};\n\nfn decal_out(c: vec4f, alpha: f32) -> FragOut {\n  var o: FragOut;\n  if (decal.shape.w > 0.5) {\n    o.color = vec4f(mix(vec3f(1.0), c.rgb, alpha), 1.0);\n    o.emissive = vec4f(1.0);\n  } else {\n    o.color = vec4f(c.rgb, alpha);\n    o.emissive = vec4f(0.0);\n  }\n  return o;\n}\n\nfn decal_age_fade(life: vec4f) -> f32 {\n  return mix(decal.fade.x, decal.fade.y, clamp(life.x, 0.0, 1.0));\n}\n\nstruct BoxOut {\n  @builtin(position) clip: vec4f,\n  @location(0) @interpolate(flat) m0: vec4f,\n  @location(1) @interpolate(flat) m1: vec4f,\n  @location(2) @interpolate(flat) m2: vec4f,\n  @location(3) @interpolate(flat) uv_rect: vec4f,\n  @location(4) @interpolate(flat) color: vec4f,\n  @location(5) @interpolate(flat) life: vec4f,\n  @location(6) @interpolate(flat) normal: vec3f,\n};\n\n@vertex fn vs(v: DecalVertex) -> BoxOut {\n  let f = decal_frame(v.m0, v.m1, v.m2);\n  let world = f.origin + f.ax * v.position.x + f.ay * v.position.y + f.az * v.position.z;\n  var o: BoxOut;\n  o.clip = camera.view_proj * vec4f(world, 1.0);\n  o.m0 = v.m0;\n  o.m1 = v.m1;\n  o.m2 = v.m2;\n  o.uv_rect = v.uv_rect;\n  o.color = v.color;\n  o.life = v.life;\n  o.normal = f.normal;\n  return o;\n}\n\n@fragment fn fs(in: BoxOut) -> FragOut {\n  let dims = vec2i(textureDimensions(scene_depth));\n  let px = clamp(vec2i(in.clip.xy), vec2i(0), dims - vec2i(1));\n  let d = textureLoad(scene_depth, px, 0);\n  if (d >= 1.0) { discard; }\n  let vp = camera.viewport;\n  let ndc = vec2f(\n    (in.clip.x - vp.x) / vp.z * 2.0 - 1.0,\n    1.0 - (in.clip.y - vp.y) / vp.w * 2.0);\n  let wp = decal.inv_view_proj * vec4f(ndc, d, 1.0);\n  let world = wp.xyz / wp.w;\n  let w4 = vec4f(world, 1.0);\n  let local = vec3f(dot(in.m0, w4), dot(in.m1, w4), dot(in.m2, w4));\n  if (any(abs(local) > vec3f(0.5))) { discard; }\n  // Surface normal from the reconstructed position, turned towards the camera.\n  let n0 = normalize(cross(dpdx(world), dpdy(world)));\n  let n = select(-n0, n0, dot(n0, camera.camera_pos.xyz - world) >= 0.0);\n  if (dot(n, in.normal) < decal.shape.x) { discard; }\n  let uv = in.uv_rect.xy + vec2f(local.x + 0.5, 0.5 - local.y) * in.uv_rect.zw;\n  let c = textureSample(decal_tex, decal_sampler, uv) * in.color;\n  let edge = smoothstep(0.0, max(decal.shape.y, 1e-4), (0.5 - abs(local.z)) * 2.0);\n  return decal_out(c, c.a * edge * decal_age_fade(in.life));\n}\n";
+/**
+ * Surface quad decal: the unit quad (local xy, z = 0) placed in the decal's frame and lifted
+ * along its normal by `decal.shape.z`; the fragment is the atlas × colour × age fade.
+ */
+export declare const WGSL_DECAL_QUAD = "\nstruct EngineGlobals {\n  logicalSize: vec2f,\n  targetSize: vec2f,\n  time: f32,\n  dt: f32,\n  _pad: vec2f,\n};\n@group(0) @binding(0) var<uniform> globals: EngineGlobals;\nstruct EngineCamera {\n  view: mat4x4f,\n  proj: mat4x4f,\n  view_proj: mat4x4f,\n  camera_pos: vec4f,\n  viewport: vec4f,\n  view_index: u32,\n  _pad0: u32, _pad1: u32, _pad2: u32,\n  inv_view_proj: mat4x4f,\n  prev_view_proj: mat4x4f,\n  prev_view: mat4x4f,\n  jitter: vec4f,\n};\n@group(0) @binding(1) var<uniform> camera: EngineCamera;\n\nstruct DecalParams {\n  inv_view_proj: mat4x4f,\n  // normal_bias, fade_edge, offset, multiply (1 = multiply blend)\n  shape: vec4f,\n  // fade at age 0, fade at age 1, pad, pad\n  fade: vec4f,\n};\n@group(1) @binding(0) var<uniform> decal: DecalParams;\n@group(1) @binding(1) var decal_sampler: sampler;\n@group(1) @binding(2) var decal_tex: texture_2d<f32>;\n@group(1) @binding(3) var scene_depth: texture_depth_2d;\n\nstruct DecalVertex {\n  @location(0) position: vec3f,\n  @location(3) m0: vec4f,\n  @location(4) m1: vec4f,\n  @location(5) m2: vec4f,\n  @location(6) uv_rect: vec4f,\n  @location(7) color: vec4f,\n  @location(8) life: vec4f,\n};\n\nstruct DecalFrame {\n  origin: vec3f,\n  ax: vec3f,\n  ay: vec3f,\n  az: vec3f,\n  normal: vec3f,\n};\n\n// The rows of the world \u2192 local matrix are axis_i / scale_i and -dot(axis_i, origin) / scale_i:\n// local \u2192 world is origin + sum(axis_i * scale_i * local_i).\nfn decal_frame(m0: vec4f, m1: vec4f, m2: vec4f) -> DecalFrame {\n  var f: DecalFrame;\n  let s0 = 1.0 / max(dot(m0.xyz, m0.xyz), 1e-12);\n  let s1 = 1.0 / max(dot(m1.xyz, m1.xyz), 1e-12);\n  let s2 = 1.0 / max(dot(m2.xyz, m2.xyz), 1e-12);\n  f.ax = m0.xyz * s0;\n  f.ay = m1.xyz * s1;\n  f.az = m2.xyz * s2;\n  f.origin = -(f.ax * m0.w + f.ay * m1.w + f.az * m2.w);\n  f.normal = normalize(m2.xyz);\n  return f;\n}\n\nstruct FragOut {\n  @location(0) color: vec4f,\n  @location(1) emissive: vec4f,\n};\n\nfn decal_out(c: vec4f, alpha: f32) -> FragOut {\n  var o: FragOut;\n  if (decal.shape.w > 0.5) {\n    o.color = vec4f(mix(vec3f(1.0), c.rgb, alpha), 1.0);\n    o.emissive = vec4f(1.0);\n  } else {\n    o.color = vec4f(c.rgb, alpha);\n    o.emissive = vec4f(0.0);\n  }\n  return o;\n}\n\nfn decal_age_fade(life: vec4f) -> f32 {\n  return mix(decal.fade.x, decal.fade.y, clamp(life.x, 0.0, 1.0));\n}\n\nstruct QuadOut {\n  @builtin(position) clip: vec4f,\n  @location(0) uv: vec2f,\n  @location(1) @interpolate(flat) color: vec4f,\n  @location(2) @interpolate(flat) life: vec4f,\n};\n\n@vertex fn vs(v: DecalVertex) -> QuadOut {\n  let f = decal_frame(v.m0, v.m1, v.m2);\n  let world = f.origin + f.ax * v.position.x + f.ay * v.position.y + f.normal * decal.shape.z;\n  var o: QuadOut;\n  o.clip = camera.view_proj * vec4f(world, 1.0);\n  o.uv = v.uv_rect.xy + vec2f(v.position.x + 0.5, 0.5 - v.position.y) * v.uv_rect.zw;\n  o.color = v.color;\n  o.life = v.life;\n  return o;\n}\n\n@fragment fn fs(in: QuadOut) -> FragOut {\n  let c = textureSample(decal_tex, decal_sampler, in.uv) * in.color;\n  return decal_out(c, c.a * decal_age_fade(in.life));\n}\n";
+/** Copies the scene depth into the decals' own `depth32float` texture (fullscreen triangle). */
+export declare const WGSL_DECAL_DEPTH_COPY = "\n@group(0) @binding(0) var src: texture_depth_2d;\n@vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {\n  let p = vec2f(f32((i << 1u) & 2u), f32(i & 2u));\n  return vec4f(p * 2.0 - 1.0, 0.0, 1.0);\n}\n@fragment fn fs(@builtin(position) pos: vec4f) -> @builtin(frag_depth) f32 {\n  return textureLoad(src, vec2i(pos.xy), 0);\n}\n";

package/dist/fx/decals-wgsl.js

@@ -0,0 +1,173 @@
+import { WGSL_GLOBALS } from '../render/wgsl.js';
+/**
+ * Shared by both decal shaders: the params block, the atlas, the depth copy and the instance
+ * decode. An instance carries the world → local 3×4 matrix of its unit box (rows `m0..m2`,
+ * each `xyz` a scaled axis and `w` the translation), its atlas rect (`u0, v0, du, dv`), its
+ * colour and `life` (`x` = age / lifetime, 0 when the decal lives forever). `decal_frame`
+ * inverts the rows back into the three world axes (scaled) and the origin, which the vertex
+ * shader needs to place the box or quad.
+ */
+const DECAL_COMMON = /* wgsl */ `
+struct DecalParams {
+  inv_view_proj: mat4x4f,
+  // normal_bias, fade_edge, offset, multiply (1 = multiply blend)
+  shape: vec4f,
+  // fade at age 0, fade at age 1, pad, pad
+  fade: vec4f,
+};
+@group(1) @binding(0) var<uniform> decal: DecalParams;
+@group(1) @binding(1) var decal_sampler: sampler;
+@group(1) @binding(2) var decal_tex: texture_2d<f32>;
+@group(1) @binding(3) var scene_depth: texture_depth_2d;
+
+struct DecalVertex {
+  @location(0) position: vec3f,
+  @location(3) m0: vec4f,
+  @location(4) m1: vec4f,
+  @location(5) m2: vec4f,
+  @location(6) uv_rect: vec4f,
+  @location(7) color: vec4f,
+  @location(8) life: vec4f,
+};
+
+struct DecalFrame {
+  origin: vec3f,
+  ax: vec3f,
+  ay: vec3f,
+  az: vec3f,
+  normal: vec3f,
+};
+
+// The rows of the world → local matrix are axis_i / scale_i and -dot(axis_i, origin) / scale_i:
+// local → world is origin + sum(axis_i * scale_i * local_i).
+fn decal_frame(m0: vec4f, m1: vec4f, m2: vec4f) -> DecalFrame {
+  var f: DecalFrame;
+  let s0 = 1.0 / max(dot(m0.xyz, m0.xyz), 1e-12);
+  let s1 = 1.0 / max(dot(m1.xyz, m1.xyz), 1e-12);
+  let s2 = 1.0 / max(dot(m2.xyz, m2.xyz), 1e-12);
+  f.ax = m0.xyz * s0;
+  f.ay = m1.xyz * s1;
+  f.az = m2.xyz * s2;
+  f.origin = -(f.ax * m0.w + f.ay * m1.w + f.az * m2.w);
+  f.normal = normalize(m2.xyz);
+  return f;
+}
+
+struct FragOut {
+  @location(0) color: vec4f,
+  @location(1) emissive: vec4f,
+};
+
+fn decal_out(c: vec4f, alpha: f32) -> FragOut {
+  var o: FragOut;
+  if (decal.shape.w > 0.5) {
+    o.color = vec4f(mix(vec3f(1.0), c.rgb, alpha), 1.0);
+    o.emissive = vec4f(1.0);
+  } else {
+    o.color = vec4f(c.rgb, alpha);
+    o.emissive = vec4f(0.0);
+  }
+  return o;
+}
+
+fn decal_age_fade(life: vec4f) -> f32 {
+  return mix(decal.fade.x, decal.fade.y, clamp(life.x, 0.0, 1.0));
+}
+`;
+/**
+ * Depth-projected box decal. The vertex shader places the unit box; the fragment shader
+ * reconstructs the world position under each pixel from the previous frame's depth copy
+ * (`inv_view_proj × (ndc, depth)`), maps it into the box, rejects what falls outside, samples
+ * the atlas by the local xy and fades by the local z edge, the surface's facing (its normal
+ * from `dpdx`/`dpdy` of the reconstructed position against the box axis) and the age.
+ */
+export const WGSL_DECAL_BOX = /* wgsl */ `${WGSL_GLOBALS}${DECAL_COMMON}
+struct BoxOut {
+  @builtin(position) clip: vec4f,
+  @location(0) @interpolate(flat) m0: vec4f,
+  @location(1) @interpolate(flat) m1: vec4f,
+  @location(2) @interpolate(flat) m2: vec4f,
+  @location(3) @interpolate(flat) uv_rect: vec4f,
+  @location(4) @interpolate(flat) color: vec4f,
+  @location(5) @interpolate(flat) life: vec4f,
+  @location(6) @interpolate(flat) normal: vec3f,
+};
+
+@vertex fn vs(v: DecalVertex) -> BoxOut {
+  let f = decal_frame(v.m0, v.m1, v.m2);
+  let world = f.origin + f.ax * v.position.x + f.ay * v.position.y + f.az * v.position.z;
+  var o: BoxOut;
+  o.clip = camera.view_proj * vec4f(world, 1.0);
+  o.m0 = v.m0;
+  o.m1 = v.m1;
+  o.m2 = v.m2;
+  o.uv_rect = v.uv_rect;
+  o.color = v.color;
+  o.life = v.life;
+  o.normal = f.normal;
+  return o;
+}
+
+@fragment fn fs(in: BoxOut) -> FragOut {
+  let dims = vec2i(textureDimensions(scene_depth));
+  let px = clamp(vec2i(in.clip.xy), vec2i(0), dims - vec2i(1));
+  let d = textureLoad(scene_depth, px, 0);
+  if (d >= 1.0) { discard; }
+  let vp = camera.viewport;
+  let ndc = vec2f(
+    (in.clip.x - vp.x) / vp.z * 2.0 - 1.0,
+    1.0 - (in.clip.y - vp.y) / vp.w * 2.0);
+  let wp = decal.inv_view_proj * vec4f(ndc, d, 1.0);
+  let world = wp.xyz / wp.w;
+  let w4 = vec4f(world, 1.0);
+  let local = vec3f(dot(in.m0, w4), dot(in.m1, w4), dot(in.m2, w4));
+  if (any(abs(local) > vec3f(0.5))) { discard; }
+  // Surface normal from the reconstructed position, turned towards the camera.
+  let n0 = normalize(cross(dpdx(world), dpdy(world)));
+  let n = select(-n0, n0, dot(n0, camera.camera_pos.xyz - world) >= 0.0);
+  if (dot(n, in.normal) < decal.shape.x) { discard; }
+  let uv = in.uv_rect.xy + vec2f(local.x + 0.5, 0.5 - local.y) * in.uv_rect.zw;
+  let c = textureSample(decal_tex, decal_sampler, uv) * in.color;
+  let edge = smoothstep(0.0, max(decal.shape.y, 1e-4), (0.5 - abs(local.z)) * 2.0);
+  return decal_out(c, c.a * edge * decal_age_fade(in.life));
+}
+`;
+/**
+ * Surface quad decal: the unit quad (local xy, z = 0) placed in the decal's frame and lifted
+ * along its normal by `decal.shape.z`; the fragment is the atlas × colour × age fade.
+ */
+export const WGSL_DECAL_QUAD = /* wgsl */ `${WGSL_GLOBALS}${DECAL_COMMON}
+struct QuadOut {
+  @builtin(position) clip: vec4f,
+  @location(0) uv: vec2f,
+  @location(1) @interpolate(flat) color: vec4f,
+  @location(2) @interpolate(flat) life: vec4f,
+};
+
+@vertex fn vs(v: DecalVertex) -> QuadOut {
+  let f = decal_frame(v.m0, v.m1, v.m2);
+  let world = f.origin + f.ax * v.position.x + f.ay * v.position.y + f.normal * decal.shape.z;
+  var o: QuadOut;
+  o.clip = camera.view_proj * vec4f(world, 1.0);
+  o.uv = v.uv_rect.xy + vec2f(v.position.x + 0.5, 0.5 - v.position.y) * v.uv_rect.zw;
+  o.color = v.color;
+  o.life = v.life;
+  return o;
+}
+
+@fragment fn fs(in: QuadOut) -> FragOut {
+  let c = textureSample(decal_tex, decal_sampler, in.uv) * in.color;
+  return decal_out(c, c.a * decal_age_fade(in.life));
+}
+`;
+/** Copies the scene depth into the decals' own `depth32float` texture (fullscreen triangle). */
+export const WGSL_DECAL_DEPTH_COPY = /* 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/decals.d.ts

@@ -0,0 +1,216 @@
+import type { Random } from '../core/random.js';
+import type { Drawable, Frame, ViewInfo } from '../render/frame.js';
+import type { Renderer } from '../render/renderer.js';
+import type { TextureLike } from '../render/texture.js';
+/**
+ * Floats per decal instance (6 × vec4f = 96 bytes):
+ *
+ * | floats | WGSL (`DecalVertex`) | content |
+ * | --- | --- | --- |
+ * | 0..11 | `m0..m2` @location(3..5) | world → local 3×4 matrix, row-major (unit box) |
+ * | 12..15 | `uv_rect` @location(6) | atlas rect: u0, v0, du, dv |
+ * | 16..19 | `color` @location(7) | linear RGBA multiplier |
+ * | 20..23 | `life` @location(8) | age / lifetime (0 when infinite), lifetime, 0, 0 |
+ */
+export declare const DECAL_INSTANCE_FLOATS = 24;
+/** Floats in the decals' params block: `inv_view_proj` (16), `shape` (4), `fade` (4). */
+export declare const DECAL_PARAMS_FLOATS = 24;
+/** How decals mix with what is under them. */
+export type DecalBlend = 'alpha' | 'multiply' | 'additive';
+/** `box` projects through the scene depth, `quad` lies on the surface, `auto` picks by camera. */
+export type DecalMode = 'auto' | 'box' | 'quad';
+export interface DecalsOptions {
+    /** Decals kept at once; the oldest is overwritten when full. Default 256. */
+    capacity?: number;
+    /** The atlas every decal samples. */
+    texture: TextureLike;
+    /** Atlas grid (`tile` indexes it row-major). Default 1×1. */
+    atlas?: {
+        columns: number;
+        rows: number;
+    };
+    /** Default `alpha`. */
+    blend?: DecalBlend;
+    /** Alpha over normalised age (0 → 1). Default `[1, 0]`; ignored for infinite lifetimes. */
+    fade?: [number, number];
+    /** Default lifetime, seconds. Default Infinity. */
+    lifetime?: number;
+    /** Default `auto`: `box` under a depth camera, else `quad`. */
+    mode?: DecalMode;
+    /** Quad mode: lift along the normal, world units. Default 0.01. */
+    offset?: number;
+    /** Box mode: reject surfaces whose normal's cosine against the decal's is below this. Default 0.3. */
+    normalBias?: number;
+    /** Box mode: fade over this share of the box's half depth at each end. Default 0.2. */
+    fadeEdge?: number;
+    /**
+     * Box mode: read this frame's opaque depth from the renderer's depth hook
+     * (`Drawable.readsDepth`, ws/fx-4). Default true (false for `mode: 'quad'`, which reads no
+     * depth). `false` is the fallback: `prepare` copies the
+     * scene depth before the scene pass, so the box samples the **previous frame's** depth (a
+     * moving surface trails by a frame). The fallback is also taken automatically when the
+     * renderer cannot copy its depth (an adopted XR depth without `COPY_SRC`).
+     */
+    readsDepth?: boolean;
+    /**
+     * The stream `rotation: 'random'` and `tile: 'random'` draw from (ws/fx-4). Default: a fork
+     * of the fx module default (`FX_DEFAULT_SEED`), named by creation order.
+     */
+    random?: Random;
+}
+/** One decal to place (`Decals.add`). */
+export interface DecalDesc {
+    x: number;
+    y: number;
+    z: number;
+    /** Surface normal the decal faces along (need not be unit). */
+    nx: number;
+    ny: number;
+    nz: number;
+    /** Width and height (and box depth), world units. */
+    size: number;
+    /** Spin about the normal, radians, or `'random'` (drawn from `Decals.random`). Default 0. */
+    rotation?: number | 'random';
+    /** Atlas tile, row-major, or `'random'` (any tile of the atlas, from `Decals.random`). Default 0. */
+    tile?: number | 'random';
+    /** Linear RGBA multiplier. Default white. */
+    color?: ArrayLike<number>;
+    /** Seconds, overriding the system default. */
+    lifetime?: number;
+}
+/**
+ * Projected decals: an atlas stamped onto scenery, every live decal in one instanced draw.
+ * `frame.drawable(decals, order)` draws them; `update(dt)` ages them.
+ *
+ * Two implementations behind one API. **Box** (under a depth camera): each decal is a unit box
+ * in its own frame; the fragment shader reconstructs the world position under the pixel from a
+ * copy of the scene depth, rejects what is outside the box and samples the atlas by the local
+ * xy, so the decal wraps whatever it covers (depth test and write off). The depth is this
+ * frame's opaque depth, from the renderer's depth hook (`readsDepth`, `afterOpaque`), so a decal
+ * on a moving surface stays on it. With `readsDepth: false` (or a target whose depth cannot be
+ * copied) the fallback copy is taken in `prepare`, before the scene pass, and holds the
+ * **previous frame's** depth: a decal placed this frame appears next frame. **Quad**
+ * (no depth, or `mode: 'quad'`): a camera-independent quad lifted along the normal by `offset`
+ * (depth test on, write off).
+ *
+ * Handles are monotonic ids; `remove` marks a decal dead and the next `update` (or `prepare`)
+ * compacts the live ones to the front, keeping the id → slot map. Nothing allocates per frame
+ * when nothing died.
+ */
+export declare class Decals implements Drawable {
+    readonly capacity: number;
+    readonly mode: DecalMode;
+    /** The mode the last `prepare` resolved (`auto` → by the frame's depth); null before. */
+    activeMode: 'box' | 'quad' | null;
+    /** Default lifetime for `add` (seconds). Live. */
+    lifetime: number;
+    /** Quad lift along the normal. Live. */
+    offset: number;
+    /** Box: minimum cosine between the surface and decal normals. Live. */
+    normalBias: number;
+    /** Box: share of the half depth faded at each end. Live. */
+    fadeEdge: number;
+    /** Alpha at age 0 and at the lifetime. Live. */
+    readonly fade: [number, number];
+    /** Box: take this frame's depth from the renderer's hook (see `DecalsOptions`). Live. */
+    readsDepth: boolean;
+    /** The stream `'random'` rotations and tiles draw from. Live. */
+    random: Random;
+    private readonly renderer;
+    private readonly device;
+    private readonly columns;
+    private readonly rows;
+    private readonly multiply;
+    private readonly data;
+    private readonly ages;
+    private readonly lives;
+    private readonly ids;
+    private readonly alive;
+    private readonly slotOf;
+    private live;
+    /** Slots in use, dead ones included until the next compaction. */
+    private used;
+    private dirty;
+    private nextId;
+    private readonly params;
+    private readonly paramsBuffer;
+    private readonly instanceBuffer;
+    private readonly box;
+    private readonly quad;
+    private readonly layout;
+    private readonly sampler;
+    private readonly texture;
+    private readonly dummyDepth;
+    private group;
+    private readonly boxModule;
+    private readonly quadModule;
+    private readonly pipelineLayout;
+    private readonly blend;
+    /**
+     * Pipelines per mode: depth format (null: none) × the view target's aux key, built on first
+     * use from `renderer.sceneTargets` (ws/render-10).
+     */
+    private readonly boxPipelines;
+    private readonly quadPipelines;
+    private readonly copyLayout;
+    private readonly copyPipeline;
+    private readonly copyAtt;
+    private readonly copyPass;
+    private copyTex;
+    private copySrc;
+    private copySrcGroup;
+    /** The box draw has a depth copy to read this frame. */
+    private depthReady;
+    /** The bind group over the fallback copy (`copyTex`). */
+    private copyGroup;
+    /** The renderer's `depthCopy` view the hook group was made for. */
+    private hookView;
+    private hookGroup;
+    private readonly noDepthGroup;
+    constructor(renderer: Renderer, opts: DecalsOptions);
+    /** Live decals. */
+    get count(): number;
+    /** Whether `handle` is still live. */
+    has(handle: number): boolean;
+    /**
+     * Place a decal at (`x`, `y`, `z`) facing along (`nx`, `ny`, `nz`), `size` wide. Returns its
+     * handle. When the system is full the oldest live decal is overwritten.
+     */
+    add(d: DecalDesc): number;
+    /** Remove a decal; false when the handle is not live. Compacted on the next `update`. */
+    remove(handle: number): boolean;
+    /** Remove every decal. */
+    clear(): void;
+    /** Age every decal by `dt` seconds, expire the ones past their lifetime and compact. */
+    update(dt: number): void;
+    /** Age of the decal at `handle`, seconds; -1 when not live. */
+    ageOf(handle: number): number;
+    /**
+     * Whether the box draw is waiting on the renderer's depth hook this frame: `readsDepth` on and
+     * the target's depth copyable. Otherwise `prepare` takes the fallback copy.
+     */
+    private get hooked();
+    /**
+     * Resolve the mode for this frame, upload the params block and the live instances. Box mode
+     * waits for the depth hook (`afterOpaque`), or takes the fallback copy of last frame's depth.
+     * Called by the renderer once per frame. No allocation.
+     */
+    prepare(encoder: GPUCommandEncoder, frame?: Frame): void;
+    /**
+     * The renderer's depth hook (`readsDepth`): bind this frame's opaque depth copy. The bind
+     * group is rebuilt only when the renderer's copy changes (a resize).
+     */
+    afterOpaque(_encoder: GPUCommandEncoder, view: ViewInfo): void;
+    /** Draw every live decal in one instanced draw (nothing in box mode until depth exists). */
+    draw(pass: GPURenderPassEncoder, frame?: Frame): void;
+    destroy(): void;
+    private writeInstance;
+    /** Move the live slots to the front, in order, and remap their handles. */
+    private compact;
+    /** Full and compact: drop slot 0 (the oldest) and shift the rest down. */
+    private dropOldest;
+    /** Copy the scene depth into our own texture; false when there is none yet. */
+    private copyDepth;
+    private makeGroup;
+    private pipelineFor;
+}