@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/fx/billboard-wgsl.js

@@ -0,0 +1,158 @@
+import { WGSL_MOTION } from '../render/scene-pipelines.js';
+import { WGSL_GLOBALS } from '../render/wgsl.js';
+/** Floats per billboard instance in the storage buffer (`BILLBOARD_BYTES` / 4). */
+export const BILLBOARD_FLOATS = 20;
+export const BILLBOARD_BYTES = BILLBOARD_FLOATS * 4;
+/** Instance flag bits, in `pos.w` as a float. */
+export const BB_FLAG_PX = 1;
+export const BB_FLAG_YAW = 2;
+export const BB_FLAG_TEXTURED = 4;
+export const BB_FLAG_BAR = 8;
+/**
+ * The billboard batch's shader: six vertices per instance, read from a storage buffer.
+ *
+ * - `pos.xyz` is the world anchor (position plus offset); `pos.w` carries the flags above.
+ * - `size.xy` is the quad size: world units, or logical px with `BB_FLAG_PX` (then the quad is
+ *   screen-aligned and sized from `globals.logicalSize`, `globals.targetSize` and the view's
+ *   `camera.viewport`, so it keeps its px size at any distance). `size.z` is the bar fraction.
+ * - World-unit quads face the camera (`camera.view` rows 0 and 1), or turn only about y with
+ *   `BB_FLAG_YAW` (right = the view's right flattened onto xz, up = +y).
+ * - `color` multiplies the atlas sample (`BB_FLAG_TEXTURED`) or stands alone; with `BB_FLAG_BAR`
+ *   the fragment is `color` where `uv.x < size.z` and `color2` beyond.
+ */
+export const BILLBOARD_WGSL = /* wgsl */ `
+${WGSL_GLOBALS}
+struct Billboard {
+  pos: vec4f,
+  size: vec4f,
+  uv: vec4f,
+  color: vec4f,
+  color2: vec4f,
+};
+@group(1) @binding(0) var<storage, read> billboards: array<Billboard>;
+@group(1) @binding(1) var atlas_sampler: sampler;
+@group(1) @binding(2) var atlas: texture_2d<f32>;
+
+struct VSOut {
+  @builtin(position) clip: vec4f,
+  @location(0) uv: vec2f,
+  @location(1) q: vec2f,
+  @location(2) color: vec4f,
+  @location(3) color2: vec4f,
+  @location(4) @interpolate(flat) flags: u32,
+  @location(5) fraction: f32,
+};
+struct FragOut {
+  @location(0) color: vec4f,
+  @location(1) emissive: vec4f,
+};
+
+fn view_row(r: u32) -> vec3f {
+  return vec3f(camera.view[0][r], camera.view[1][r], camera.view[2][r]);
+}
+
+@vertex fn vs(@builtin(vertex_index) vi: u32, @builtin(instance_index) ii: u32) -> VSOut {
+  var o: VSOut;
+  let b = billboards[ii];
+  var corners = array<vec2f, 6>(
+    vec2f(-1.0, -1.0), vec2f(1.0, -1.0), vec2f(1.0, 1.0),
+    vec2f(-1.0, -1.0), vec2f(1.0, 1.0), vec2f(-1.0, 1.0)
+  );
+  let q = corners[vi];
+  let flags = u32(b.pos.w + 0.5);
+  let half = b.size.xy * 0.5;
+  if ((flags & ${BB_FLAG_PX}u) != 0u) {
+    var clip = camera.view_proj * vec4f(b.pos.xyz, 1.0);
+    // Logical px → target px → NDC, scaled by w so the division leaves the px size intact.
+    let px_per_logical = globals.targetSize / globals.logicalSize;
+    let ndc = (q * half * px_per_logical) / max(camera.viewport.zw, vec2f(1.0)) * 2.0;
+    clip = vec4f(clip.xy + ndc * clip.w, clip.zw);
+    o.clip = clip;
+  } else {
+    var right = view_row(0u);
+    var up = view_row(1u);
+    if ((flags & ${BB_FLAG_YAW}u) != 0u) {
+      let flat = vec3f(right.x, 0.0, right.z);
+      let len = length(flat);
+      right = select(vec3f(1.0, 0.0, 0.0), flat / max(len, 1e-6), len > 1e-6);
+      up = vec3f(0.0, 1.0, 0.0);
+    }
+    let world = b.pos.xyz + right * (q.x * half.x) + up * (q.y * half.y);
+    o.clip = camera.view_proj * vec4f(world, 1.0);
+  }
+  // Canvas uv: v grows downward, so the top of the quad (q.y = 1) samples v0.
+  let t = q * 0.5 + 0.5;
+  o.uv = vec2f(mix(b.uv.x, b.uv.z, t.x), mix(b.uv.w, b.uv.y, t.y));
+  o.q = t;
+  o.color = b.color;
+  o.color2 = b.color2;
+  o.flags = flags;
+  o.fraction = b.size.z;
+  return o;
+}
+
+@fragment fn fs(in: VSOut) -> FragOut {
+  var c = in.color;
+  if ((in.flags & ${BB_FLAG_BAR}u) != 0u) {
+    c = select(in.color2, in.color, in.q.x < in.fraction);
+  }
+  // Sampled unconditionally: textureSample needs uniform control flow.
+  let s = textureSample(atlas, atlas_sampler, in.uv);
+  c *= select(vec4f(1.0), s, (in.flags & ${BB_FLAG_TEXTURED}u) != 0u);
+  var o: FragOut;
+  o.color = c;
+  o.emissive = vec4f(0.0, 0.0, 0.0, c.a);
+  return o;
+}
+`;
+/** Insert `add` after the one occurrence of `at` in `src` (throws unless there is exactly one). */
+function after(src, at, add) {
+    const i = src.indexOf(at);
+    if (i < 0 || src.indexOf(at, i + 1) >= 0)
+        throw new Error(`billboardWgsl: anchor ${at}`);
+    return src.slice(0, i + at.length) + add + src.slice(i + at.length);
+}
+/**
+ * `BILLBOARD_WGSL`, or with `velocity` (the velocity attachment's fragment location, 2 or 3)
+ * the build that writes its own motion (ws/render-11): binding 3 holds each sorted instance's
+ * previous anchor (`xyz`, `w` = 1 when known), the vertex stage projects the same corner of
+ * last frame's quad through `camera.prev_view_proj` / `prev_view`, and the fragment writes
+ * `vec4f(engine_motion(..), 0, alpha)` there. Internal; `0` is the exported string itself.
+ */
+export function billboardWgsl(velocity) {
+    if (velocity <= 0)
+        return BILLBOARD_WGSL;
+    let s = after(BILLBOARD_WGSL, WGSL_GLOBALS, WGSL_MOTION);
+    s = after(s, '@group(1) @binding(2) var atlas: texture_2d<f32>;', '\n@group(1) @binding(3) var<storage, read> billboard_prev: array<vec4f>;');
+    s = after(s, '  @location(5) fraction: f32,', '\n  @location(6) prev_clip: vec4f,');
+    s = after(s, '  @location(1) emissive: vec4f,', `\n  @location(${velocity}) velocity: vec4f,`);
+    s = after(s, `fn view_row(r: u32) -> vec3f {
+  return vec3f(camera.view[0][r], camera.view[1][r], camera.view[2][r]);
+}
+`, `
+fn prev_view_row(r: u32) -> vec3f {
+  return vec3f(camera.prev_view[0][r], camera.prev_view[1][r], camera.prev_view[2][r]);
+}
+fn yaw_right(r: vec3f) -> vec3f {
+  let flat = vec3f(r.x, 0.0, r.z);
+  let len = length(flat);
+  return select(vec3f(1.0, 0.0, 0.0), flat / max(len, 1e-6), len > 1e-6);
+}
+`);
+    s = after(s, '  let half = b.size.xy * 0.5;', `
+  let pv = billboard_prev[ii];
+  let pa = select(b.pos.xyz, pv.xyz, pv.w > 0.5);`);
+    s = after(s, '    o.clip = clip;', `
+    let pc = camera.prev_view_proj * vec4f(pa, 1.0);
+    o.prev_clip = vec4f(pc.xy + ndc * pc.w, pc.zw);`);
+    s = after(s, '    o.clip = camera.view_proj * vec4f(world, 1.0);', `
+    var pr = prev_view_row(0u);
+    var pu = prev_view_row(1u);
+    if ((flags & ${BB_FLAG_YAW}u) != 0u) {
+      pr = yaw_right(pr);
+      pu = vec3f(0.0, 1.0, 0.0);
+    }
+    let prev_world = pa + pr * (q.x * half.x) + pu * (q.y * half.y);
+    o.prev_clip = camera.prev_view_proj * vec4f(prev_world, 1.0);`);
+    return after(s, '  o.emissive = vec4f(0.0, 0.0, 0.0, c.a);', '\n  o.velocity = vec4f(engine_motion(in.clip, in.prev_clip), 0.0, c.a);');
+}

package/dist/fx/billboard.d.ts

@@ -0,0 +1,249 @@
+import type { Camera } from '../render/camera.js';
+import type { Drawable, Frame } from '../render/frame.js';
+import type { Renderer } from '../render/renderer.js';
+import type { Texture } from '../render/texture.js';
+import { type AtlasRegion, TextAtlas, type TextAtlasOptions, type TextStyle } from './text-atlas.js';
+/** `'camera'`: the quad faces the eye. `'cameraY'`: it turns about y only (stays upright). */
+export type BillboardFacing = 'camera' | 'cameraY';
+/** `'test'`: hidden behind scene geometry (no depth write). `'always'`: drawn over everything. */
+export type BillboardDepth = 'test' | 'always';
+/** `[w, h]` in world units, or `{ px: [w, h] }` in logical px, the same size at any distance. */
+export type BillboardSize = readonly [number, number] | {
+    readonly px: readonly [number, number];
+};
+export interface BillboardDesc {
+    /**
+     * World anchor. A `Float32Array` (x, y, z at 0..2) is followed live, so a plate tracks the
+     * thing it is over without being told; a tuple is copied.
+     */
+    position: Float32Array | readonly [number, number, number];
+    /** World-space offset from `position` (a head height). Default none. */
+    offset?: readonly [number, number, number];
+    size: BillboardSize;
+    /** An atlas region to show (`billboards.text(...)`), or `null`/unset for a solid colour. */
+    region?: AtlasRegion | null;
+    /**
+     * A text plate (ws/fx-4): `text` in its own atlas cell (`TextAtlas.cell`), changed later with
+     * `handle.setText`. Overrides `region`. Size the quad to the text with `billboards.measure`.
+     */
+    text?: string;
+    /** The plate's style (with `text`). */
+    textStyle?: TextStyle;
+    /** Linear RGBA multiplier (straight alpha). Default white. */
+    color?: ArrayLike<number>;
+    /** Default `'camera'`. `{ px }` sizes are always screen-aligned. */
+    facing?: BillboardFacing;
+    /** Default `'test'`. */
+    depth?: BillboardDepth;
+    /**
+     * Seconds to live: the quad holds for the first half, fades over the second and removes
+     * itself at the end. Default none (lives until `remove`).
+     */
+    life?: number;
+    /** World units per second added to the anchor (damage numbers drift up). Default none. */
+    velocity?: readonly [number, number, number];
+    /**
+     * A health bar in one quad: `color` fills `fraction` of the width from the left, `bg` the
+     * rest. `billboards.bar(...)` builds this. Default none.
+     */
+    bar?: {
+        fraction: number;
+        bg: ArrayLike<number>;
+    };
+}
+export interface BillboardsOptions {
+    /** Billboards the buffers start with (they grow when full). Default 1024. */
+    capacity?: number;
+    /** The text atlas: canvas `size` (default 1024) and default `font`. */
+    atlas?: TextAtlasOptions;
+    label?: string;
+}
+/**
+ * World units a span of `px` logical px covers at `viewDistance` from a camera whose projection
+ * is `projection` (column-major; `projection[5]` is the vertical scale) on a viewport
+ * `viewportPx` logical px tall. The shader applies the same ratio in clip space for `{ px }`
+ * sizes; use this on the CPU to size something in world units to match a px plate.
+ */
+export declare function pxToWorld(px: number, viewDistance: number, projection: ArrayLike<number>, viewportPx: number): number;
+/**
+ * One billboard, returned by `Billboards.add`. Setters change it in place; it is `alive` until
+ * `remove` or its `life` runs out, after which the setters do nothing.
+ */
+export declare class BillboardHandle {
+    private readonly owner;
+    /** @internal slot in the owner's arrays, -1 when dead. */
+    slot: number;
+    constructor(owner: Billboards);
+    get alive(): boolean;
+    set position(p: Float32Array | readonly [number, number, number]);
+    set offset(o: readonly [number, number, number]);
+    set color(c: ArrayLike<number>);
+    set size(s: BillboardSize);
+    set region(r: AtlasRegion | null);
+    /** The text plate's text (`desc.text`, `setText`); null when not a plate. */
+    get text(): string | null;
+    /**
+     * Change a text plate's text (ws/fx-4). Re-rasterised into the plate's own atlas cell when it
+     * fits (no new region, no new texture), else into a wider cell: the quad's height stays and
+     * its width grows with the cell, so the glyphs keep their scale. A handle that is not a plate
+     * becomes one, in the default style, at its current size.
+     */
+    setText(text: string): void;
+    /** The filled share of a bar quad, 0..1. */
+    set fraction(f: number);
+}
+/**
+ * World-anchored, camera-facing quads in one batch: name plates, damage numbers, health bars,
+ * markers. Each shows a region of the shared text atlas or a solid colour, is sized in world
+ * units or in screen px, optionally fades out over `life` and drifts by `velocity`. Alpha
+ * blended, depth tested without writing (or drawn over everything with `depth: 'always'`),
+ * sorted back to front each `update`. Draw with `frame.drawable(billboards)`.
+ *
+ * ```ts
+ * const bb = createBillboards(renderer);
+ * const plate = bb.add({ position: hero.position, offset: [0, 2, 0], size: { px: [160, 40] },
+ *                        region: bb.text('Hero', { size: 28, stroke: '#000', strokeWidth: 4 }) });
+ * bb.add({ position: hero.position, offset: [0, 2.3, 0], size: [1, 0.12], life: 0.9,
+ *          velocity: [0, 1.2, 0], region: bb.text('-37', { color: '#f44' }) });
+ * bb.update(dt, camera);        // ages, drifts, sorts
+ * frame.drawable(bb);           // inside the scene's render
+ * ```
+ *
+ * Nothing allocates per frame once the buffers are big enough; `add` past `capacity` doubles
+ * them.
+ */
+export declare class Billboards implements Drawable {
+    /** The atlas canvas as a texture, uploaded when the atlas changed (once per frame at most). */
+    readonly atlasTexture: Texture;
+    /** The text atlas behind `text()`. */
+    readonly atlas: TextAtlas;
+    /** Draw calls the last `draw` issued (0, 1 or 2: one per depth mode in use). */
+    draws: number;
+    private readonly renderer;
+    private readonly device;
+    private readonly label;
+    private capacity;
+    private n;
+    private anchor;
+    private tracked;
+    private offset;
+    private velocity;
+    /** age, life (life <= 0: immortal). */
+    private life;
+    private rgba;
+    private mode;
+    private regions;
+    /** A text plate's text (its region an owned atlas cell); null when not a plate. */
+    private plates;
+    private handles;
+    /** Instance data per slot, in `BILLBOARD_WGSL`'s layout. */
+    private inst;
+    private order;
+    private keys;
+    private upload;
+    /**
+     * Motion (ws/render-11): per slot the anchor its quad was last drawn at (`xyz`, `w` = 1 once
+     * drawn), and the previous anchors in sorted order for `prevBuffer` (binding 3), which the
+     * velocity build of the shader reads. Kept only once a view with a velocity attachment drew
+     * the batch (`motion`); until then the buffer holds zeros, read as "unknown" (no motion).
+     */
+    private drawn;
+    private prevUpload;
+    private prevBuffer;
+    private motion;
+    /** The velocity builds of the shader, by fragment location (2 or 3), made on first use. */
+    private readonly motionModules;
+    private testCount;
+    private alwaysCount;
+    private uploadDirty;
+    private buffer;
+    private group;
+    private readonly groupLayout;
+    private readonly pipelineDesc;
+    /**
+     * Pipelines per depth format (null: none) × the view target's aux key, made on first use
+     * from `renderer.sceneTargets` (ws/render-10): `testPipelines` depth-test (and hold the
+     * depthless one), `alwaysPipelines` ignore depth.
+     */
+    private readonly testPipelines;
+    private readonly alwaysPipelines;
+    constructor(renderer: Renderer, opts?: BillboardsOptions);
+    /** Live billboards. */
+    get count(): number;
+    /** Share of the atlas canvas in use, 0..1. */
+    get atlasUsed(): number;
+    private makeBuffer;
+    private makePrevBuffer;
+    private makeGroup;
+    /** Double every array and the GPU buffer (only when `add` finds the batch full). */
+    private grow;
+    /** Add a billboard; the handle changes or removes it later. */
+    add(desc: BillboardDesc): BillboardHandle;
+    /** Remove a billboard now (a no-op for one already gone). */
+    remove(handle: BillboardHandle): void;
+    /** Remove every billboard. Atlas text stays cached; text plates give their cells back. */
+    clear(): void;
+    /** Swap-remove slot `i`: the last slot moves into it. */
+    private removeAt;
+    /**
+     * The atlas region for `text` in `style`, rasterised on first use and cached (text + style).
+     * Throws when the string is larger than the whole atlas canvas.
+     */
+    text(text: string, style?: TextStyle): AtlasRegion;
+    /**
+     * A health bar in one quad, `fraction` (0..1) of its width in `fg` and the rest in `bg`:
+     * spread it into `add` with a `position`, then set `handle.fraction`.
+     */
+    bar(fraction: number, size: BillboardSize, fg: ArrayLike<number>, bg: ArrayLike<number>): Omit<BillboardDesc, 'position'>;
+    /** @internal */
+    setPosition(i: number, p: Float32Array | readonly [number, number, number]): void;
+    /** @internal */
+    setOffset(i: number, o: readonly [number, number, number]): void;
+    /** @internal */
+    setColor(i: number, c: ArrayLike<number>): void;
+    /** @internal */
+    setSize(i: number, s: BillboardSize): void;
+    /**
+     * The width and height, in atlas px, a text plate of `text` in `style` gets (its cell): size
+     * a plate's quad to this aspect.
+     */
+    measure(text: string, style?: TextStyle): {
+        width: number;
+        height: number;
+    };
+    /** @internal */
+    plateText(i: number): string | null;
+    /** @internal */
+    setText(i: number, text: string): void;
+    private makePlate;
+    private releasePlate;
+    /** @internal */
+    setRegion(i: number, r: AtlasRegion | null): void;
+    private writeRegion;
+    /** @internal */
+    setFraction(i: number, f: number): void;
+    /**
+     * Age and drift every billboard, remove the ones past their `life`, resolve anchors and fades
+     * into the instance data and sort back to front for `camera` (without one, submission order).
+     * Call once per update or frame; allocation-free.
+     */
+    update(dt: number, camera?: Camera | null): void;
+    /**
+     * Upload the instance data, last frame's drawn anchors when the view has velocity and, when
+     * the atlas changed, its canvas. Runs before the pass.
+     */
+    prepare(_encoder: GPUCommandEncoder, _frame?: Frame): void;
+    /**
+     * Once per frame with `motion` on: each drawn quad's previous anchor (where it was drawn last
+     * frame, or its current one the first time) into `prevBuffer` in draw order, then remember
+     * the current anchors. Without an `update` since, current equals previous (no motion).
+     */
+    private writePrevious;
+    /** Draw inside the scene pass: the `'test'` quads, then the `'always'` ones. */
+    draw(pass: GPURenderPassEncoder, frame?: Frame): void;
+    private pipelineFor;
+    private motionModule;
+    destroy(): void;
+}
+/** `new Billboards(renderer, opts)`. */
+export declare function createBillboards(renderer: Renderer, opts?: BillboardsOptions): Billboards;