@aethervtt/shard-render 0.0.1 → 0.1.0

package/dist/cutaway-plugin.js

@@ -0,0 +1,364 @@
+import { defineResource, defineSystem, Last } from "@aethervtt/shard-core";
+import { GpuBuffer } from "@aethervtt/shard-gpu";
+import { definePlugin, LogResource } from "@aethervtt/shard-runtime";
+import { Camera3d } from "./camera.js";
+import { CutawayPath, CutawayView, MAX_REVEAL_POINTS } from "./cutaway.js";
+import { addRenderFeatures } from "./features.js";
+import {
+  INSTANCE_FLOATS,
+  InstanceFlags,
+  Instances,
+  prepareInstances
+} from "./instances.js";
+import { Gpu, RenderDescribers, RenderSet, Shaders } from "./plugin.js";
+import { registerShaders } from "./shaders.js";
+import { Cameras } from "./view.js";
+const CUTAWAY_FLOATS = MAX_REVEAL_POINTS * 8 + 4;
+const DIRS = MAX_REVEAL_POINTS * 4;
+const PARAMS = MAX_REVEAL_POINTS * 8;
+const CUTAWAY_SHADERS = {
+  "shard::cutaway": `
+struct Cutaway {
+  /** Reveal points (xyz). */
+  points: array<vec4f, ${MAX_REVEAL_POINTS}>,
+  /**
+   * Each point's line of sight, unit (xyz): from the eye through it, or the view direction when
+   * orthographic. Made on the CPU once a frame, not per fragment.
+   */
+  dirs: array<vec4f, ${MAX_REVEAL_POINTS}>,
+  /** radius, margin, edge (m), and how many points. */
+  params: vec4f,
+}
+
+@group(3) @binding(0) var<uniform> cutaway: Cutaway;
+
+/** InstanceFlags.Cutaway in the record's flags word. */
+const CUTAWAY_FLAG: u32 = 0x10000000u;
+
+/** 0 to 1 across an edge band of width \`edge\` ending at 0 (a step when edge is 0). */
+fn cutaway_ramp(inside: f32, edge: f32) -> f32 {
+  if (edge <= 0.0) { return select(0.0, 1.0, inside > 0.0); }
+  return clamp(inside / edge, 0.0, 1.0);
+}
+
+/**
+ * How cut a world point is, 0 (whole) to 1: within radius of the line from the eye through a
+ * reveal point (along the view direction when orthographic), and nearer the camera than the point
+ * by more than margin. The edge band ramps both.
+ */
+fn cutaway_amount(world: vec3f) -> f32 {
+  let radius = cutaway.params.x;
+  let margin = cutaway.params.y;
+  let edge = cutaway.params.z;
+  let count = u32(cutaway.params.w);
+  var amount = 0.0;
+  for (var i = 0u; i < count; i++) {
+    let d = world - cutaway.points[i].xyz;
+    let along = dot(d, cutaway.dirs[i].xyz);
+    // Not in front of the point by the margin, or outside the radius: this point cuts nothing.
+    let ahead = -along - margin;
+    if (ahead <= 0.0) { continue; }
+    let across2 = max(dot(d, d) - along * along, 0.0);
+    if (across2 >= radius * radius) { continue; }
+    amount = max(amount, min(cutaway_ramp(radius - sqrt(across2), edge), cutaway_ramp(ahead, edge)));
+    if (amount >= 1.0) { break; }
+  }
+  return amount;
+}
+
+/** An ordered 4\xD74 dither threshold at a pixel, in (0, 1). */
+fn cutaway_threshold(frag: vec2f) -> f32 {
+  let x = u32(frag.x);
+  let y = u32(frag.y);
+  let low = (((x ^ y) & 1u) << 1u) | (y & 1u);
+  let high = ((((x ^ y) >> 1u) & 1u) << 1u) | ((y >> 1u) & 1u);
+  return (f32(low * 4u + high) + 0.5) / 16.0;
+}
+
+/** Removes the fragment of a Cutaway instance that stands in front of a reveal point. */
+fn cutaway_clip(world: vec3f, frag: vec2f, flags: u32) {
+  if ((flags & CUTAWAY_FLAG) == 0u) { return; }
+  if (cutaway_amount(world) > cutaway_threshold(frag)) { discard; }
+}`
+};
+const CutawayCameras = defineResource("render/CutawayCameras", {
+  description: "Each camera's reveal points as the cutaway variants read them (0070).",
+  init: () => ({ cameras: /* @__PURE__ */ new Map(), frame: 0, layout: void 0 })
+});
+function cameraOf(state, camera) {
+  let c = state.cameras.get(camera);
+  if (!c) {
+    c = {
+      data: new Float32Array(CUTAWAY_FLOATS),
+      buffer: void 0,
+      bindGroup: void 0,
+      boundGeneration: -1,
+      boundVersion: -1,
+      count: -1,
+      listed: 0,
+      frame: -1,
+      warned: false,
+      written: -1,
+      cuts: new Uint8Array(64)
+    };
+    state.cameras.set(camera, c);
+  }
+  return c;
+}
+function warnTooMany(world, camera, listed) {
+  world.tryResource(LogResource)?.log(
+    "warn",
+    `Camera ${camera} has ${listed} reveal points; only the first ${MAX_REVEAL_POINTS} cut`,
+    {
+      code: "render/too-many-reveal-points",
+      hint: `Give CutawayView at most ${MAX_REVEAL_POINTS} points: the party, or the selected tokens.`,
+      data: { camera, points: listed }
+    }
+  );
+}
+function put(d, o, v) {
+  if (d[o] === Math.fround(v)) return false;
+  d[o] = v;
+  return true;
+}
+const extractCutaways = defineSystem({
+  name: "render/extract-cutaways",
+  description: "Packs cameras' reveal points for the cutaway variants (0070).",
+  setup: (world) => ({ q: world.query({ with: [Camera3d, CutawayView] }) }),
+  run: ({ q }, world) => {
+    const state = world.resource(CutawayCameras);
+    const gpu = world.resource(Gpu);
+    const cameras = world.resource(Cameras);
+    const store = world.resource(Instances);
+    const frame = ++state.frame;
+    for (const table of q.tables) {
+      const points = table.column(CutawayView, "points");
+      const radius = table.column(CutawayView, "radius");
+      const margin = table.column(CutawayView, "margin");
+      const edge = table.column(CutawayView, "edge");
+      for (let i = 0; i < table.count; i++) {
+        const camera = table.entities[i];
+        const c = cameraOf(state, camera);
+        c.frame = frame;
+        const list = points[i] ?? EMPTY;
+        const listed = list.length;
+        const count = Math.min(listed, MAX_REVEAL_POINTS);
+        if (listed > MAX_REVEAL_POINTS && !c.warned) {
+          c.warned = true;
+          warnTooMany(world, camera, listed);
+        }
+        c.listed = listed;
+        const cam = cameras.get(camera);
+        const n = cam ? count : 0;
+        const d = c.data;
+        let changed = c.count !== n;
+        for (let k = 0; k < n; k++) {
+          const p = list[k];
+          const o = k * 4;
+          changed = put(d, o, p[0]) || changed;
+          changed = put(d, o + 1, p[1]) || changed;
+          changed = put(d, o + 2, p[2]) || changed;
+          const f = cam.forward;
+          let x = f[0];
+          let y = f[1];
+          let z = f[2];
+          if (!cam.orthographic) {
+            const e = cam.position;
+            const dx = p[0] - e[0];
+            const dy = p[1] - e[1];
+            const dz = p[2] - e[2];
+            const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+            if (len > 1e-5) {
+              x = dx / len;
+              y = dy / len;
+              z = dz / len;
+            }
+          }
+          changed = put(d, DIRS + o, x) || changed;
+          changed = put(d, DIRS + o + 1, y) || changed;
+          changed = put(d, DIRS + o + 2, z) || changed;
+        }
+        changed = put(d, PARAMS, radius[i]) || changed;
+        changed = put(d, PARAMS + 1, margin[i]) || changed;
+        changed = put(d, PARAMS + 2, edge[i]) || changed;
+        changed = put(d, PARAMS + 3, n) || changed;
+        c.count = n;
+        if (n > 0) markCuts(c, store);
+        if (n > 0 && (changed || c.written !== gpu.generation)) {
+          c.written = gpu.generation;
+          c.buffer ??= new GpuBuffer(gpu, {
+            label: `camera:${camera}/cutaway`,
+            usage: GPUBufferUsage.UNIFORM,
+            size: CUTAWAY_FLOATS * 4
+          });
+          c.buffer.write(d);
+        }
+      }
+    }
+    let live = 0;
+    for (const table of q.tables) live += table.count;
+    if (state.cameras.size > live) {
+      for (const [camera, c] of state.cameras) {
+        if (c.frame === frame) continue;
+        c.buffer?.destroy();
+        state.cameras.delete(camera);
+      }
+    }
+  }
+});
+const EMPTY = [];
+const box = new Float32Array(6);
+function slotBox(f, o, b) {
+  const cx = (b[0] + b[3]) * 0.5;
+  const cy = (b[1] + b[4]) * 0.5;
+  const cz = (b[2] + b[5]) * 0.5;
+  const ex = (b[3] - b[0]) * 0.5;
+  const ey = (b[4] - b[1]) * 0.5;
+  const ez = (b[5] - b[2]) * 0.5;
+  for (let r = 0; r < 3; r++) {
+    const m = o + r * 4;
+    box[r] = f[m] * cx + f[m + 1] * cy + f[m + 2] * cz + f[m + 3];
+    box[3 + r] = Math.abs(f[m]) * ex + Math.abs(f[m + 1]) * ey + Math.abs(f[m + 2]) * ez;
+  }
+}
+function reaches(d, k, radius, margin) {
+  const o = k * 4;
+  let t0 = 0;
+  let t1 = Number.POSITIVE_INFINITY;
+  for (let a = 0; a < 3; a++) {
+    const dir = -d[DIRS + o + a];
+    const start = d[o + a] + dir * margin;
+    const lo = box[a] - box[3 + a] - radius;
+    const hi = box[a] + box[3 + a] + radius;
+    if (Math.abs(dir) < 1e-9) {
+      if (start < lo || start > hi) return false;
+      continue;
+    }
+    let near = (lo - start) / dir;
+    let far = (hi - start) / dir;
+    if (near > far) {
+      const t = near;
+      near = far;
+      far = t;
+    }
+    if (near > t0) t0 = near;
+    if (far < t1) t1 = far;
+    if (t0 > t1) return false;
+  }
+  return true;
+}
+function markCuts(c, store) {
+  const batches = store.batches;
+  if (c.cuts.length < batches.length) c.cuts = new Uint8Array(batches.length * 2);
+  const cuts = c.cuts;
+  const d = c.data;
+  const n = d[PARAMS + 3];
+  const radius = d[PARAMS];
+  const margin = d[PARAMS + 1];
+  for (let b = 0; b < batches.length; b++) {
+    const batch = batches[b];
+    cuts[b] = 0;
+    if (batch.cutaway === 0) continue;
+    if (batch.memberCount < batch.count) {
+      cuts[b] = 1;
+      continue;
+    }
+    for (let m = 0; m < batch.memberCount && cuts[b] === 0; m++) {
+      const slot = batch.members[m];
+      const flags = store.flags[slot];
+      if ((flags & InstanceFlags.Cutaway) === 0) continue;
+      if (flags & InstanceFlags.Skinned) {
+        cuts[b] = 1;
+        break;
+      }
+      slotBox(store.f32, slot * INSTANCE_FLOATS, batch.mesh.bounds);
+      for (let k = 0; k < n; k++) {
+        if (reaches(d, k, radius, margin)) {
+          cuts[b] = 1;
+          break;
+        }
+      }
+    }
+  }
+}
+function support(world) {
+  const state = world.resource(CutawayCameras);
+  const layout = (gpu) => {
+    if (!state.layout || state.layout.generation !== gpu.generation) {
+      state.layout = {
+        layout: gpu.layouts.bindGroupLayout({
+          label: "cutaway",
+          entries: [
+            { binding: 0, visibility: GPUShaderStage.FRAGMENT, buffer: { type: "uniform" } }
+          ]
+        }),
+        generation: gpu.generation
+      };
+    }
+    return state.layout.layout;
+  };
+  return {
+    layout,
+    cuts(camera, batch) {
+      const c = state.cameras.get(camera);
+      return c !== void 0 && c.frame === state.frame && c.count > 0 && c.cuts[batch] === 1;
+    },
+    bindGroup(gpu, camera) {
+      const c = state.cameras.get(camera);
+      if (!c || c.frame !== state.frame || c.count <= 0 || !c.buffer) return void 0;
+      const buffer = c.buffer;
+      const gpuBuffer = buffer.buffer;
+      if (!c.bindGroup || c.boundGeneration !== gpu.generation || c.boundVersion !== buffer.version) {
+        c.bindGroup = gpu.device.createBindGroup({
+          label: "cutaway",
+          layout: layout(gpu),
+          entries: [{ binding: 0, resource: { buffer: gpuBuffer } }]
+        });
+        c.boundGeneration = gpu.generation;
+        c.boundVersion = buffer.version;
+      }
+      return c.bindGroup;
+    }
+  };
+}
+function describeCutaways(world) {
+  const out = {};
+  world.query({ with: [Camera3d, CutawayView] }).each((camera, row, table) => {
+    const points = table.column(CutawayView, "points")[row] ?? [];
+    out[`camera:${camera}`] = {
+      points: Array.from(points.slice(0, MAX_REVEAL_POINTS), (p) => [p[0], p[1], p[2]]),
+      ignored: Math.max(0, points.length - MAX_REVEAL_POINTS),
+      radius: table.column(CutawayView, "radius")[row],
+      margin: table.column(CutawayView, "margin")[row],
+      edge: table.column(CutawayView, "edge")[row]
+    };
+  });
+  return out;
+}
+const cutawayPlugin = definePlugin({
+  name: "render/cutaway",
+  dependencies: ["render/forward"],
+  provides: [CutawayCameras],
+  build(app) {
+    app.world.initResource(CutawayCameras);
+    app.insertResource(CutawayPath, support(app.world));
+    app.addSystems(Last, extractCutaways.inSet(RenderSet.Prepare).after(prepareInstances));
+  },
+  ready(app) {
+    registerShaders(app.world.resource(Shaders), CUTAWAY_SHADERS);
+    app.world.initResource(RenderDescribers).set("cutaways", describeCutaways);
+    addRenderFeatures(app.world, {
+      name: "render/cutaway",
+      description: "Cutaway surfaces opened around cameras' reveal points.",
+      nodes: [],
+      baseline: { strategy: "The same discard; points in a uniform block" }
+    });
+  }
+});
+export {
+  CUTAWAY_SHADERS,
+  CutawayCameras,
+  cutawayPlugin,
+  describeCutaways,
+  extractCutaways
+};

package/dist/cutaway.d.ts

@@ -0,0 +1,27 @@
+import { type Entity } from '@aethervtt/shard-core';
+import type { GpuContext } from '@aethervtt/shard-gpu';
+/** Reveal points a camera can have; more are ignored with `render/too-many-reveal-points`. */
+export declare const MAX_REVEAL_POINTS = 16;
+export declare const Cutaway: import("@aethervtt/shard-core").ComponentDef<{}>;
+export declare const CutawayView: import("@aethervtt/shard-core").ComponentDef<{
+    readonly points: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3[], "object">;
+    readonly radius: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly margin: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly edge: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+/**
+ * Set by `cutawayPlugin`: what the camera passes need to draw the cutaway variants of pipelines.
+ * Forward asks it per view, so core imports no cutaway code.
+ */
+export interface CutawaySupport {
+    /** The bind group layout cutaway pipelines take at group 3. */
+    layout(gpu: GpuContext): GPUBindGroupLayout;
+    /** The camera's reveal points, bound at group 3: undefined when it has none this frame. */
+    bindGroup(gpu: GpuContext, camera: Entity): GPUBindGroup | undefined;
+    /**
+     * Whether a point of the camera can cut an instance of the batch this frame: its bounds reach a
+     * reveal cylinder. The others draw the plain variant (no discard, so no per-fragment cost).
+     */
+    cuts(camera: Entity, batch: number): boolean;
+}
+export declare const CutawayPath: import("@aethervtt/shard-core").ResourceDef<CutawaySupport>;

package/dist/cutaway.js

@@ -0,0 +1,49 @@
+import { defineComponent, defineResource, t } from "@aethervtt/shard-core";
+import { Camera3d } from "./camera.js";
+const MAX_REVEAL_POINTS = 16;
+const Cutaway = defineComponent(
+  "render/Cutaway",
+  {},
+  {
+    description: "Tag on a renderable: it may be cut away around a camera's reveal points (CutawayView). Shadows never cut."
+  }
+);
+const CutawayView = defineComponent(
+  "render/CutawayView",
+  {
+    points: t.list(t.vec3, {
+      description: `World points to reveal, at most ${MAX_REVEAL_POINTS}: a token's position, the party.`
+    }),
+    radius: t.f32({
+      default: 2.5,
+      min: 0,
+      unit: "m",
+      description: "How far from each point's line of sight a Cutaway surface is cut."
+    }),
+    margin: t.f32({
+      default: 0.6,
+      min: 0,
+      unit: "m",
+      description: "How far in front of a point the cut starts, so the floor it stands on, and a stairwell rim, stay."
+    }),
+    edge: t.f32({
+      default: 0.3,
+      min: 0,
+      unit: "m",
+      description: "Width of the dithered rim; 0 is a hard cut."
+    })
+  },
+  {
+    description: "Cuts Cutaway surfaces away between this camera and its reveal points (0070): a disc in a roof from above, a hole in a wall at an angle. Every camera pass (picking too) sees the hole; shadows do not.",
+    requires: [Camera3d]
+  }
+);
+const CutawayPath = defineResource("render/CutawayPath", {
+  description: "Present when cutaways (cutawayPlugin) are installed."
+});
+export {
+  Cutaway,
+  CutawayPath,
+  CutawayView,
+  MAX_REVEAL_POINTS
+};

package/dist/data-store.d.ts

@@ -0,0 +1,69 @@
+import { type GpuContext } from '@aethervtt/shard-gpu';
+/** Texels per row of a data texture (the baseline rewrite's loaders read the same). */
+export declare const DATA_WIDTH = 1024;
+export interface DataStoreOptions {
+    label: string;
+    /** Initial size in bytes. Default 256. */
+    size?: number;
+    /**
+     * Buffer usages beyond STORAGE (full tier) or UNIFORM (a baseline uniform block): a GPU pass that
+     * writes it, a readback. Data textures ignore it.
+     */
+    usage?: GPUBufferUsageFlags;
+    /** How baseline shaders read it: a data texture (default), or a uniform block. */
+    kind?: 'texture' | 'uniform';
+}
+/**
+ * Loads the baseline tier's data textures, once. The render plugin does it as it opens a baseline
+ * device, before anything makes a DataStore; so does code that makes one on its own device.
+ */
+export declare function loadDataTextures(): Promise<void>;
+/**
+ * The layout entry a DataStore of `kind` binds with on this device's tier, for layouts made
+ * before (or without) the store: storage on the full tier, a data texture or a uniform block on
+ * baseline.
+ */
+export declare function dataEntry(gpu: GpuContext, binding: number, visibility: GPUShaderStageFlags, kind?: 'texture' | 'uniform', type?: GPUBufferBindingType): GPUBindGroupLayoutEntry;
+/**
+ * Forgets the data textures `owner` made on `gpu` (an app's render plugin, as it disposes): the
+ * ledger destroys their textures, so they must not flush again.
+ */
+export declare function releaseDataStores(gpu: GpuContext, owner: string): void;
+/** Uploads what every baseline data texture of `gpu` was written this frame. Before the submit. */
+export declare function flushDataStores(gpu: GpuContext): void;
+/**
+ * A binding of indexed engine data that a vertex or fragment shader reads. Same calls as
+ * GpuBuffer: `ensureCapacity`, `write`, `version` (bumps when bind groups must be rebuilt); plus
+ * the layout entry and resource of whichever form the tier binds.
+ */
+export declare class DataStore {
+    readonly label: string;
+    readonly kind: 'texture' | 'uniform';
+    /** Who its GPU objects count against (`gpu.owner` when it was made). */
+    readonly owner: string;
+    /** The texture form: the baseline tier's `@data` binding. */
+    readonly textured: boolean;
+    private readonly gpu;
+    private readonly buffer;
+    private readonly texture;
+    constructor(gpu: GpuContext, options: DataStoreOptions);
+    /** Bumps whenever the GPU object changes: bind groups made on the old one rebuild. */
+    get version(): number;
+    get byteLength(): number;
+    /**
+     * The buffer, on the tiers that bind one (full, and baseline uniform blocks): for full-tier
+     * passes that read or write it as storage (GPU culling).
+     */
+    get gpuBuffer(): GPUBuffer;
+    /** Grows to at least `bytes`. Returns true if the GPU object was replaced. */
+    ensureCapacity(bytes: number): boolean;
+    /** Writes a TypedArray (or a slice of it, in elements) at a byte offset, growing if needed. */
+    write(data: ArrayBufferView & ArrayLike<number>, byteOffset?: number, start?: number, count?: number): void;
+    /** The bind group layout entry for this binding on this tier. */
+    layoutEntry(binding: number, visibility: GPUShaderStageFlags, type?: GPUBufferBindingType): GPUBindGroupLayoutEntry;
+    /** What the bind group binds. Rebuild bind groups when `version` changes. */
+    resource(): GPUBindingResource;
+    /** Uploads the rows written since the last flush (data textures; the rest write through). */
+    flush(): void;
+    destroy(): void;
+}

package/dist/data-store.js

@@ -0,0 +1,105 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { GpuBuffer } from "@aethervtt/shard-gpu";
+import { DATA_TEXTURE_WIDTH } from "@aethervtt/shard-shader";
+const DATA_WIDTH = DATA_TEXTURE_WIDTH;
+let dataTextures;
+async function loadDataTextures() {
+  dataTextures ??= await import("./baseline/data-texture.js");
+}
+function dataEntry(gpu, binding, visibility, kind = "texture", type = "read-only-storage") {
+  if (gpu.tier !== "baseline") return { binding, visibility, buffer: { type } };
+  if (kind === "uniform") return { binding, visibility, buffer: { type: "uniform" } };
+  return { binding, visibility, texture: { sampleType: "uint", viewDimension: "2d" } };
+}
+function releaseDataStores(gpu, owner) {
+  dataTextures?.releaseDataTextures(gpu, owner);
+}
+function flushDataStores(gpu) {
+  dataTextures?.flushDataTextures(gpu);
+}
+class DataStore {
+  label;
+  kind;
+  /** Who its GPU objects count against (`gpu.owner` when it was made). */
+  owner;
+  /** The texture form: the baseline tier's `@data` binding. */
+  textured;
+  gpu;
+  buffer;
+  texture;
+  constructor(gpu, options) {
+    this.gpu = gpu;
+    this.label = options.label;
+    this.owner = gpu.owner;
+    this.kind = options.kind ?? "texture";
+    const size = align16(Math.max(16, options.size ?? 256));
+    this.textured = gpu.tier === "baseline" && this.kind === "texture";
+    if (this.textured) {
+      if (!dataTextures) {
+        throw new ShardError(
+          "render/data-textures-not-loaded",
+          `DataStore "${options.label}" needs the baseline tier's data textures, which aren't loaded`,
+          { hint: "Await loadDataTextures() before making DataStores on a baseline device." }
+        );
+      }
+      this.texture = new dataTextures.DataTexture(gpu, options.label, size);
+      return;
+    }
+    this.buffer = new GpuBuffer(gpu, {
+      label: options.label,
+      usage: (gpu.tier === "baseline" ? GPUBufferUsage.UNIFORM : GPUBufferUsage.STORAGE) | (options.usage ?? 0),
+      size
+    });
+  }
+  /** Bumps whenever the GPU object changes: bind groups made on the old one rebuild. */
+  get version() {
+    return this.buffer ? this.buffer.version : this.texture.currentVersion;
+  }
+  get byteLength() {
+    return this.buffer ? this.buffer.byteLength : this.texture.size;
+  }
+  /**
+   * The buffer, on the tiers that bind one (full, and baseline uniform blocks): for full-tier
+   * passes that read or write it as storage (GPU culling).
+   */
+  get gpuBuffer() {
+    if (!this.buffer) throw new Error(`${this.label} is a data texture on this tier`);
+    return this.buffer.buffer;
+  }
+  /** Grows to at least `bytes`. Returns true if the GPU object was replaced. */
+  ensureCapacity(bytes) {
+    return this.buffer ? this.buffer.ensureCapacity(bytes) : this.texture.ensureCapacity(bytes);
+  }
+  /** Writes a TypedArray (or a slice of it, in elements) at a byte offset, growing if needed. */
+  write(data, byteOffset = 0, start = 0, count) {
+    if (this.buffer) this.buffer.write(data, byteOffset, start, count);
+    else this.texture.write(data, byteOffset, start, count);
+  }
+  /** The bind group layout entry for this binding on this tier. */
+  layoutEntry(binding, visibility, type = "read-only-storage") {
+    return dataEntry(this.gpu, binding, visibility, this.kind, type);
+  }
+  /** What the bind group binds. Rebuild bind groups when `version` changes. */
+  resource() {
+    return this.buffer ? { buffer: this.buffer.buffer } : this.texture.resource();
+  }
+  /** Uploads the rows written since the last flush (data textures; the rest write through). */
+  flush() {
+    this.texture?.flush();
+  }
+  destroy() {
+    this.buffer?.destroy();
+    this.texture?.destroy();
+  }
+}
+function align16(n) {
+  return n + 15 & ~15;
+}
+export {
+  DATA_WIDTH,
+  DataStore,
+  dataEntry,
+  flushDataStores,
+  loadDataTextures,
+  releaseDataStores
+};

package/dist/debug-shaders.js

@@ -37,7 +37,7 @@ struct Line {
   bits: u32,
 }
 
-@group(1) @binding(0) var<storage, read> lines: array<Line>;
+@data @group(1) @binding(0) var<storage, read> lines: array<Line>;
 
 struct LineOutput {
   @builtin(position) clip: vec4f,
@@ -112,7 +112,7 @@ struct Glyph {
   _pad1: u32,
 }
 
-@group(1) @binding(1) var<storage, read> glyphs: array<Glyph>;
+@data @group(1) @binding(1) var<storage, read> glyphs: array<Glyph>;
 @group(1) @binding(3) var atlas: texture_2d<f32>;
 
 struct GlyphOutput {
@@ -167,11 +167,21 @@ struct PickOutput {
 import shard::view::view;
 import shard::mesh::{ instance_at, mesh_vertex_at };
 import shard::pick::types::PickOutput;
+@if(CUTAWAY) import shard::cutaway::cutaway_clip;
 
 struct PickVertex {
   @builtin(position) clip: vec4f,
   @location(0) normal: vec3f,
   @location(1) @interpolate(flat) entity: u32,
+  /**
+   * Clip z and w, interpolated perspective-correct: z / w is the surface's own depth. The
+   * fragment's position.z includes the depth bias ground bands draw with (0057), which would move
+   * a picked point toward the camera.
+   */
+  @location(2) zw: vec2f,
+  /** Where cutaways (0070) test the surface. */
+  @if(CUTAWAY) @location(3) world: vec3f,
+  @if(CUTAWAY) @location(4) @interpolate(flat) flags: u32,
 }
 
 @vertex fn vs(
@@ -190,14 +200,18 @@ struct PickVertex {
   out.clip = view.viewProjNoJitter * vec4f(m.world_position, 1.0);
   out.normal = m.world_normal;
   out.entity = inst.entity;
+  out.zw = out.clip.zw;
+  @if(CUTAWAY) out.world = m.world_position;
+  @if(CUTAWAY) out.flags = m.flags;
   return out;
 }
 
 @fragment fn fs(in: PickVertex, @builtin(front_facing) front: bool) -> PickOutput {
+  @if(CUTAWAY) cutaway_clip(in.world, in.clip.xy, in.flags);
   var out: PickOutput;
   out.id = in.entity;
   let n = normalize(in.normal);
-  out.normal = vec4f(select(-n, n, front), in.clip.z);
+  out.normal = vec4f(select(-n, n, front), in.zw.x / in.zw.y);
   return out;
 }`
 };

package/dist/debug-views.js

@@ -161,8 +161,10 @@ function describeLighting(world) {
       })),
       clusters: {
         grid: [16, 9, 24],
-        maxLightsPerCluster: pv.clusters.latest.maxLightsPerCluster,
-        overflows: pv.clusters.latest.overflows
+        // GPU clustering's stats; baseline bins on the CPU and drops lights past its budget.
+        maxLightsPerCluster: pv.clusters?.latest.maxLightsPerCluster ?? null,
+        overflows: pv.clusters?.latest.overflows ?? 0,
+        baselineLights: pv.baseline ? { packed: pv.baseline.count, dropped: pv.baseline.dropped } : null
       },
       cascades: pv.cascades.count,
       cascadeSplits: [...pv.cascades.splits.subarray(0, pv.cascades.count)]