@aethervtt/shard-render 0.0.1 → 0.1.0

package/dist/baseline/textures.d.ts

@@ -0,0 +1,97 @@
+import { type World } from '@aethervtt/shard-core';
+import type { GpuContext } from '@aethervtt/shard-gpu';
+import { Texture } from '@aethervtt/shard-texture';
+import type { GpuTexture } from '../gpu-assets.js';
+/** What a baseline texture asks of the asset layer that owns it. */
+export interface TwinHost {
+    readonly gpu: GpuContext;
+    /** Reload the texture's artifact (its bytes come back, and its version bumps). */
+    reload(texture: Texture): void;
+    /** The loading fallback's view of this kind, shown while a twin waits. */
+    fallback(srgb: boolean, array: boolean): GPUTextureView;
+    /** A twin started waiting for its bytes (`ready` false), or was made (`ready` true). */
+    twin(texture: Texture, kind: string, ready: boolean): void;
+    /** Development builds: the texture's usage doesn't match the slot reading it. */
+    mismatch(texture: Texture, kind: string): void;
+}
+/** A twin that waited for its bytes: which texture and view, and how long it took. */
+export interface TwinWait {
+    texture: string;
+    kind: string;
+    since: number;
+    ms: number | undefined;
+}
+/** What the asset layer lends its baseline textures. */
+export interface TwinSource {
+    readonly gpu: GpuContext;
+    readonly world: World | undefined;
+    /** The asset guid of an imported texture. */
+    guidOf(texture: Texture): string | undefined;
+    /** Reloads the texture's artifact, once at a time. */
+    reload(texture: Texture): void;
+    /** The loading fallback: a solid white texture. */
+    white(): GpuTexture;
+}
+/**
+ * The twin bookkeeping of one asset layer: reloads, the loading fallback, the waits
+ * `render.describe` lists, and the dev-build `render/texture-color-space-mismatch` log.
+ */
+export declare class Twins implements TwinHost {
+    readonly gpu: GpuContext;
+    /** Pending twins, and the last 32 finished. */
+    readonly waits: TwinWait[];
+    private readonly source;
+    private readonly mismatched;
+    constructor(source: TwinSource);
+    reload(texture: Texture): void;
+    fallback(srgb: boolean, array: boolean): GPUTextureView;
+    twin(texture: Texture, kind: string, ready: boolean): void;
+    mismatch(texture: Texture, kind: string): void;
+    /** `render.describe → twins`: pending twins with how long they've waited, and recent ones. */
+    describe(): {
+        pending: {
+            texture: string;
+            kind: string;
+            waitedMs: number;
+        }[];
+        recent: {
+            texture: string;
+            kind: string;
+            waitedMs: number;
+        }[];
+    };
+}
+/**
+ * A texture on the baseline tier: the primary copy, and the twins slots asked for. The views are
+ * getters, so a twin is made (or requested) only when something binds it.
+ */
+export declare class BaselineTexture implements GpuTexture {
+    readonly texture: GPUTexture;
+    readonly version: number;
+    readonly generation: number;
+    bytes: number;
+    private readonly source;
+    private readonly host;
+    private readonly primarySrgb;
+    private readonly primaryDimension;
+    private readonly views;
+    private readonly pending;
+    /** Twins made, destroyed with the primary. */
+    readonly twins: GPUTexture[];
+    constructor(host: TwinHost, source: Texture);
+    get linear(): GPUTextureView;
+    get srgb(): GPUTextureView;
+    get arrayLinear(): GPUTextureView | undefined;
+    get arraySrgb(): GPUTextureView | undefined;
+    /** The primary and every twin. */
+    destroy(): void;
+    /**
+     * Whether a slot reading it this way waits for a twin's bytes (and shows the loading fallback).
+     * Asking requests the twin, as binding it would: material preparation asks for deferred draws.
+     */
+    waiting(wantSrgb: boolean, array: boolean): boolean;
+    private keyFor;
+    private view;
+}
+/** Solid 1×1 textures for empty slots, as baseline textures that keep their bytes. */
+export declare function solidTexture(host: TwinHost, rgba: readonly number[]): BaselineTexture;

package/dist/baseline/textures.js

@@ -0,0 +1,203 @@
+import { ShardError } from "@aethervtt/shard-core";
+import { DevMode, LogResource } from "@aethervtt/shard-runtime";
+import { FORMAT_INFO, Texture } from "@aethervtt/shard-texture";
+class Twins {
+  gpu;
+  /** Pending twins, and the last 32 finished. */
+  waits = [];
+  source;
+  mismatched = /* @__PURE__ */ new Set();
+  constructor(source) {
+    this.source = source;
+    this.gpu = source.gpu;
+  }
+  reload(texture) {
+    this.source.reload(texture);
+  }
+  fallback(srgb, array) {
+    const white = this.source.white();
+    return array ? srgb ? white.arraySrgb : white.arrayLinear : srgb ? white.srgb : white.linear;
+  }
+  twin(texture, kind, ready) {
+    const name = this.source.guidOf(texture) ?? texture.format;
+    const waits = this.waits;
+    const i = waits.findIndex((w) => w.texture === name && w.kind === kind && w.ms === void 0);
+    if (!ready) {
+      if (i === -1) waits.push({ texture: name, kind, since: performance.now(), ms: void 0 });
+    } else if (i !== -1) {
+      waits[i].ms = performance.now() - waits[i].since;
+    } else if (waits.length < 256) {
+      waits.push({ texture: name, kind, since: performance.now(), ms: 0 });
+    }
+    while (waits.filter((w) => w.ms !== void 0).length > 32) {
+      waits.splice(
+        waits.findIndex((w) => w.ms !== void 0),
+        1
+      );
+    }
+  }
+  mismatch(texture, kind) {
+    const world = this.source.world;
+    if (!world?.tryResource(DevMode)?.enabled) return;
+    const name = this.source.guidOf(texture);
+    if (name === void 0 || this.mismatched.has(`${name}|${kind}`)) return;
+    this.mismatched.add(`${name}|${kind}`);
+    world.tryResource(LogResource)?.error(
+      new ShardError(
+        "render/texture-color-space-mismatch",
+        `A ${texture.usage} texture is read as ${kind.split("/")[0]}: the baseline tier keeps a second copy of it`,
+        { path: name, hint: "Set its usage to match the slot in its .meta, and the copy goes." }
+      )
+    );
+  }
+  /** `render.describe → twins`: pending twins with how long they've waited, and recent ones. */
+  describe() {
+    const now = performance.now();
+    const pending = [];
+    const recent = [];
+    for (const w of this.waits) {
+      if (w.ms === void 0)
+        pending.push({ texture: w.texture, kind: w.kind, waitedMs: now - w.since });
+      else recent.push({ texture: w.texture, kind: w.kind, waitedMs: w.ms });
+    }
+    return { pending, recent };
+  }
+}
+const DIMENSION = { plain: "2d", array: "2d-array", cube: "cube" };
+const DIMENSIONS = ["2d", "2d-array", "cube"];
+function keyOf(srgb, dimension) {
+  return (srgb ? 1 : 0) + DIMENSIONS.indexOf(dimension) * 2;
+}
+function kindOf(key) {
+  return `${key & 1 ? "srgb" : "linear"}/${DIMENSIONS[key >> 1]}`;
+}
+function create(gpu, texture, format, dimension) {
+  const info = FORMAT_INFO[texture.format];
+  const layers = texture.faces * texture.layers;
+  const handle = gpu.device.createTexture({
+    label: `texture/${format}${dimension === "2d" ? "" : `/${dimension}`}`,
+    size: { width: texture.width, height: texture.height, depthOrArrayLayers: layers },
+    format,
+    mipLevelCount: texture.mipCount,
+    usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+    textureBindingViewDimension: dimension
+  });
+  for (let level = 0; texture.levels && level < texture.mipCount; level++) {
+    const w = Math.max(1, texture.width >> level);
+    const h = Math.max(1, texture.height >> level);
+    const blocksWide = Math.ceil(w / info.block);
+    const blocksHigh = Math.ceil(h / info.block);
+    gpu.device.queue.writeTexture(
+      { texture: handle, mipLevel: level },
+      texture.levels[level],
+      { bytesPerRow: blocksWide * info.bytes, rowsPerImage: blocksHigh },
+      {
+        width: blocksWide * info.block,
+        height: blocksHigh * info.block,
+        depthOrArrayLayers: layers
+      }
+    );
+  }
+  return handle;
+}
+class BaselineTexture {
+  texture;
+  version;
+  generation;
+  bytes;
+  source;
+  host;
+  primarySrgb;
+  primaryDimension;
+  views = /* @__PURE__ */ new Map();
+  pending = /* @__PURE__ */ new Set();
+  /** Twins made, destroyed with the primary. */
+  twins = [];
+  constructor(host, source) {
+    this.host = host;
+    this.source = source;
+    this.version = source.version;
+    this.generation = host.gpu.generation;
+    this.bytes = source.byteSize;
+    const info = FORMAT_INFO[source.format];
+    this.primarySrgb = source.usage === "color" && info.srgbView !== void 0;
+    this.primaryDimension = source.faces === 6 ? DIMENSION.cube : source.layers > 1 ? DIMENSION.array : DIMENSION.plain;
+    const format = this.primarySrgb ? info.srgbView : source.format;
+    this.texture = create(host.gpu, source, format, this.primaryDimension);
+    this.views.set(
+      keyOf(this.primarySrgb, this.primaryDimension),
+      this.texture.createView({ dimension: this.primaryDimension })
+    );
+  }
+  get linear() {
+    return this.view(false, false);
+  }
+  get srgb() {
+    return this.view(true, false);
+  }
+  get arrayLinear() {
+    return this.source.faces === 1 ? this.view(false, true) : void 0;
+  }
+  get arraySrgb() {
+    return this.source.faces === 1 ? this.view(true, true) : void 0;
+  }
+  /** The primary and every twin. */
+  destroy() {
+    this.texture.destroy();
+    for (const t of this.twins) t.destroy();
+  }
+  /**
+   * Whether a slot reading it this way waits for a twin's bytes (and shows the loading fallback).
+   * Asking requests the twin, as binding it would: material preparation asks for deferred draws.
+   */
+  waiting(wantSrgb, array) {
+    this.view(wantSrgb, array);
+    return this.pending.has(this.keyFor(wantSrgb, array));
+  }
+  keyFor(wantSrgb, array) {
+    const srgb = wantSrgb && FORMAT_INFO[this.source.format].srgbView !== void 0;
+    const dimension = array ? DIMENSION.array : this.primaryDimension === DIMENSION.array ? DIMENSION.array : this.primaryDimension;
+    return keyOf(srgb, dimension);
+  }
+  view(wantSrgb, array) {
+    const key = this.keyFor(wantSrgb, array);
+    const ready = this.views.get(key);
+    if (ready) return ready;
+    const srgb = (key & 1) === 1;
+    const dimension = DIMENSIONS[key >> 1];
+    const info = FORMAT_INFO[this.source.format];
+    if (srgb !== this.primarySrgb) this.host.mismatch(this.source, kindOf(key));
+    if (!this.source.levels) {
+      if (!this.pending.has(key)) {
+        this.pending.add(key);
+        this.host.twin(this.source, kindOf(key), false);
+        this.host.reload(this.source);
+      }
+      return this.host.fallback(srgb, dimension === DIMENSION.array);
+    }
+    const format = srgb ? info.srgbView : this.source.format;
+    const twin = create(this.host.gpu, this.source, format, dimension);
+    this.twins.push(twin);
+    this.bytes += this.source.byteSize;
+    const view = twin.createView({ dimension });
+    this.views.set(key, view);
+    this.pending.delete(key);
+    this.host.twin(this.source, kindOf(key), true);
+    return view;
+  }
+}
+function solidTexture(host, rgba) {
+  const texture = Texture.create({
+    width: 1,
+    height: 1,
+    mips: [new Uint8Array(rgba)],
+    cpu: true,
+    usage: "data"
+  });
+  return new BaselineTexture(host, texture);
+}
+export {
+  BaselineTexture,
+  Twins,
+  solidTexture
+};

package/dist/camera.d.ts

@@ -41,6 +41,7 @@ export declare const Camera3d: import("@aethervtt/shard-core").ComponentDef<{
     readonly clearColor: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
     readonly target: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"RenderTarget"> | null, "object">;
     readonly active: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly layers: import("@aethervtt/shard-core").FieldType<number, "u16">;
 }>;
 export type Camera3dValue = Infer<typeof Camera3d>;
 export declare const PhysicalCamera: import("@aethervtt/shard-core").ComponentDef<{
@@ -65,6 +66,7 @@ export declare function camera2d(options?: {
     readonly clearColor: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
     readonly target: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"RenderTarget"> | null, "object">;
     readonly active: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly layers: import("@aethervtt/shard-core").FieldType<number, "u16">;
 }>, {
     readonly projection: 'orthographic';
     readonly orthoHeight: number;

package/dist/camera.js

@@ -77,6 +77,10 @@ const Camera3d = defineComponent(
     active: t.bool({
       default: true,
       description: "Renders when true. An inactive camera keeps its settings and transform but draws nothing."
+    }),
+    layers: t.u16({
+      default: 65535,
+      description: "Render layers this camera draws (0057): a renderable draws if its RenderLayers mask shares a bit. Default: all."
     })
   },
   {

package/dist/culling-shaders.js

@@ -37,6 +37,13 @@ struct CullView {
   lod_camera: u32,
   args_base: u32,
   visible_base: u32,
+  /** Render layers the view draws (0057). */
+  layers: u32,
+  /** Its hidden set's first word in lod_state, past the LOD entries (0070), or NO_HIDDEN. */
+  @if(HIDDEN) hidden_base: u32,
+  @if(!HIDDEN) _pad0: u32,
+  _pad1: u32,
+  _pad2: u32,
 }
 
 struct Params {
@@ -67,12 +74,15 @@ struct Deform {
 }
 @group(0) @binding(8) var<storage, read> deforms: array<Deform>;
 
+@if(HIDDEN) const NO_HIDDEN: u32 = 0xffffffffu;
+
 const NO_BATCH: u32 = 0xffffffffu;
 const LOD_BIT: u32 = 0x80000000u;
 const LOD_UNSET: u32 = 0xffu;
 const FLAG_VISIBLE: u32 = 1u;
 const FLAG_CASTER: u32 = 2u;
 const FLAG_RANGE: u32 = 8u;
+const FLAG_SHADOW_ONLY: u32 = 128u;
 const FLAG_SKINNED: u32 = 32u;
 const VIEW_CASTERS: u32 = 1u;
 const VIEW_UPDATE_LOD: u32 = 2u;
@@ -155,8 +165,17 @@ fn cull(@builtin(global_invocation_id) id: vec3u) {
   let inst = instances[s];
   if (inst.batch == NO_BATCH) { return; }
   var mask = FLAG_VISIBLE;
-  if ((view.flags & VIEW_CASTERS) != 0u) { mask |= FLAG_CASTER; }
-  if ((inst.flags & mask) != mask) { return; }
+  var flags = inst.flags;
+  if ((view.flags & VIEW_CASTERS) != 0u) {
+    mask |= FLAG_CASTER;
+    // Hidden meshes that still cast (ShadowWhenHidden, 0067).
+    if ((flags & FLAG_SHADOW_ONLY) != 0u) { flags |= FLAG_VISIBLE; }
+  }
+  if ((flags & mask) != mask) { return; }
+  // Render layers (0057) ride in flags bits 8\u201323.
+  if ((((inst.flags >> 8u) & 0xffffu) & view.layers) == 0u) { return; }
+  // Hidden from this view (ViewVisibility, 0070): a bit per slot.
+  @if(HIDDEN) if (view.hidden_base != NO_HIDDEN && (lod_state[view.hidden_base + (s >> 5u)] & (1u << (s & 31u))) != 0u) { return; }
   var b = inst.batch;
   var lod = false;
   var lod_set: LodSet;

package/dist/culling.d.ts

@@ -1,6 +1,7 @@
 import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
 import type { NodeContext } from './graph.js';
 import { type CullParams, type DrawList, type InstanceStore } from './instances.js';
+import type { HiddenSets } from './view-visibility-plugin.js';
 /**
  * GPU culling: one compute pass per frame culls every instance slot against every draw view
  * (cameras first, which choose LOD levels, then shadow views, which reuse them), writing indirect
@@ -11,6 +12,8 @@ export declare class GpuCuller {
     readonly supported: boolean;
     /** Turn off to force CPU culling (tests, debugging). */
     enabled: boolean;
+    /** Views this frame with a hidden set (0070): the cull links its HIDDEN variant. */
+    private hiddenViews;
     private readonly views;
     private viewCount;
     private cameraViews;
@@ -58,8 +61,12 @@ export declare class GpuCuller {
      * batches into `forwardOnly`.
      */
     add(store: InstanceStore, list: DrawList, params: CullParams, lodCamera: number, forwardOnly?: DrawList): number;
-    /** Uploads the frame's view, batch, and LOD tables, and sizes the buffers. */
-    prepare(store: InstanceStore): void;
+    /**
+     * Uploads the frame's view, batch, and LOD tables, and sizes the buffers. Hidden sets (0070)
+     * ride in the LOD state buffer after its entries: the cull's storage bindings are at WebGPU's
+     * guaranteed 8 per stage.
+     */
+    prepare(store: InstanceStore, hidden?: HiddenSets): void;
     private slotCount;
     private slotCapacity;
     /** Encodes the cull: reset arguments, cull camera views, then shadow views. */
@@ -75,6 +82,8 @@ export declare const Culler: import("@aethervtt/shard-core").ResourceDef<GpuCull
  * members of blended batches, so it costs what's transparent, not what exists.
  */
 export declare function cullTransparent(store: InstanceStore, list: DrawList, params: CullParams, forward: Float32Array): void;
+/** The CPU ground list (0057) of a view the GPU culls. */
+export declare function cullGround(store: InstanceStore, list: DrawList, params: CullParams, overlay?: DrawList): void;
 /**
  * The CPU-side visible set of a view as slots (tests compare it with the GPU's). Pass
  * `mask = 0xffffffff` to keep the LOD level in the top bits.

package/dist/culling.js

@@ -7,8 +7,9 @@ import {
   SLOT_MASK
 } from "./instances.js";
 import { Shaders } from "./plugin.js";
+import { NO_HIDDEN } from "./view-visibility.js";
 const ARGS_WORDS = 5;
-const VIEW_FLOATS = 32;
+const VIEW_FLOATS = 36;
 const BATCH_WORDS = 8;
 const LOD_WORDS = 20;
 const VIEW_CASTERS = 1;
@@ -21,6 +22,8 @@ class GpuCuller {
   supported;
   /** Turn off to force CPU culling (tests, debugging). */
   enabled = true;
+  /** Views this frame with a hidden set (0070): the cull links its HIDDEN variant. */
+  hiddenViews = 0;
   views = [];
   viewCount = 0;
   cameraViews = 0;
@@ -59,7 +62,7 @@ class GpuCuller {
   pending = /* @__PURE__ */ new Set();
   constructor(gpu) {
     this.gpu = gpu;
-    this.supported = gpu.features.has("indirect-first-instance");
+    this.supported = gpu.tier === "full" && gpu.features.has("indirect-first-instance");
     const storage = GPUBufferUsage.STORAGE;
     this.viewBuffer = new GpuBuffer(gpu, { label: "cull/views", usage: storage, size: 4096 });
     this.batchBuffer = new GpuBuffer(gpu, { label: "cull/batches", usage: storage, size: 2048 });
@@ -82,6 +85,7 @@ class GpuCuller {
   beginFrame() {
     this.viewCount = 0;
     this.cameraViews = 0;
+    this.hiddenViews = 0;
   }
   /** The LOD state row of a camera (cameras choose; their shadow views reuse the choice). */
   lodCamera(entity) {
@@ -110,7 +114,9 @@ class GpuCuller {
         hasEye: false,
         lodScale: 1,
         flags: 0,
-        lodCamera: 0
+        lodCamera: 0,
+        layers: 4294967295,
+        hiddenBase: NO_HIDDEN
       };
       this.views.push(view);
     }
@@ -122,6 +128,9 @@ class GpuCuller {
     if (params.eye) view.eye.set(params.eye);
     view.lodScale = params.lodScale;
     view.lodCamera = lodCamera;
+    view.layers = params.layers ?? 4294967295;
+    view.hiddenBase = params.hiddenBase ?? NO_HIDDEN;
+    if (view.hiddenBase !== NO_HIDDEN) this.hiddenViews++;
     view.flags = (params.require & InstanceFlags.Caster ? VIEW_CASTERS : 0) | (params.updateLod ? VIEW_UPDATE_LOD : 0) | (params.orthographic ? VIEW_ORTHO : 0) | (params.planes ? 0 : VIEW_NO_PLANES);
     if (params.updateLod) this.cameraViews = v + 1;
     list.cullView = v;
@@ -136,7 +145,8 @@ class GpuCuller {
     let n = 0;
     let m = 0;
     for (const batch of store.sorted) {
-      if (batch.count === 0 || batch.transparent || !store.anyVisible(batch)) continue;
+      if (batch.count === 0 || batch.transparent || batch.ground || !store.anyVisible(batch))
+        continue;
       if (!batch.ready) {
         list.pending += batch.count;
         continue;
@@ -157,9 +167,22 @@ class GpuCuller {
     if (forwardOnly) forwardOnly.length = m;
     return v;
   }
-  /** Uploads the frame's view, batch, and LOD tables, and sizes the buffers. */
-  prepare(store) {
+  /**
+   * Uploads the frame's view, batch, and LOD tables, and sizes the buffers. Hidden sets (0070)
+   * ride in the LOD state buffer after its entries: the cull's storage bindings are at WebGPU's
+   * guaranteed 8 per stage.
+   */
+  prepare(store, hidden) {
     if (this.viewCount === 0) return;
+    const lodCams = Math.max(1, this.lodCameras.size);
+    const hiddenWords = hidden && hidden.sets.size > 0 ? hidden.data.length : 0;
+    if (this.lodStateCapacity !== store.capacity * lodCams || this.lodState.byteLength < (this.lodStateCapacity + hiddenWords) * 4) {
+      this.lodStateCapacity = store.capacity * lodCams;
+      this.lodState.ensureCapacity((this.lodStateCapacity + hiddenWords) * 4);
+      const fill = new Uint32Array(this.lodStateCapacity).fill(LOD_UNSET);
+      this.lodState.write(fill);
+    }
+    if (hiddenWords > 0) hidden.upload(this.lodState, this.lodStateCapacity * 4);
     const batches = store.batches;
     this.batchCount = batches.length;
     if (this.batchData.length < batches.length * BATCH_WORDS) {
@@ -182,7 +205,7 @@ class GpuCuller {
       this.batchData[o + 4] = batch.mesh.drawCount;
       this.batchData[o + 5] = batch.mesh.indexed ? 1 + batch.mesh.baseVertex : 0;
       this.batchData[o + 6] = batch.region;
-      this.batchData[o + 7] = (batch.transparent ? BATCH_TRANSPARENT : 0) | (batch.ready ? 0 : BATCH_NOT_READY);
+      this.batchData[o + 7] = (batch.transparent || batch.ground ? BATCH_TRANSPARENT : 0) | (batch.ready ? 0 : BATCH_NOT_READY);
     }
     this.regionSize = Math.max(1, region);
     this.batchBuffer.write(this.batchData, 0, 0, Math.max(1, batches.length) * BATCH_WORDS);
@@ -220,6 +243,8 @@ class GpuCuller {
       this.viewU32[o + 29] = view.lodCamera;
       this.viewU32[o + 30] = v * batches.length;
       this.viewU32[o + 31] = v * this.regionSize;
+      this.viewU32[o + 32] = view.layers;
+      this.viewU32[o + 33] = view.hiddenBase === NO_HIDDEN ? NO_HIDDEN : this.lodStateCapacity + view.hiddenBase;
       for (const list of [view.list, view.forwardOnly]) {
         if (!list) continue;
         for (let d = 0; d < list.length; d++) {
@@ -232,12 +257,6 @@ class GpuCuller {
     this.viewBuffer.write(this.viewData, 0, 0, this.viewCount * VIEW_FLOATS);
     this.args.ensureCapacity(Math.max(1, this.viewCount * batches.length) * ARGS_WORDS * 4);
     this.visible.ensureCapacity(this.viewCount * this.regionSize * 4);
-    const lodCams = Math.max(1, this.lodCameras.size);
-    if (this.lodStateCapacity !== store.capacity * lodCams) {
-      this.lodStateCapacity = store.capacity * lodCams;
-      const fill = new Uint32Array(this.lodStateCapacity).fill(LOD_UNSET);
-      this.lodState.write(fill);
-    }
     this.frameViews = this.views.slice(0, this.viewCount);
     this.slotCount = store.high;
     this.slotCapacity = store.capacity;
@@ -249,7 +268,8 @@ class GpuCuller {
     if (this.viewCount === 0) return;
     const gpu = ctx.gpu;
     const world = ctx.world;
-    const module = world.resource(Shaders).module(gpu, { root: "shard::cull" });
+    const hidden = this.hiddenViews > 0;
+    const module = world.resource(Shaders).module(gpu, hidden ? HIDDEN_REQUEST : CULL_REQUEST);
     if (!module) {
       gpu.pipelines.skipped++;
       return;
@@ -257,12 +277,12 @@ class GpuCuller {
     const layout = cullLayout(gpu);
     const pipelineLayout = gpu.layouts.pipelineLayout({ label: "cull", bindGroupLayouts: [layout] });
     const reset = gpu.pipelines.compute({
-      label: "cull/reset",
+      label: hidden ? "cull/reset/hidden" : "cull/reset",
       layout: pipelineLayout,
       compute: { module, entryPoint: "reset" }
     });
     const cull = gpu.pipelines.compute({
-      label: "cull/instances",
+      label: hidden ? "cull/instances/hidden" : "cull/instances",
       layout: pipelineLayout,
       compute: { module, entryPoint: "cull" }
     });
@@ -309,7 +329,7 @@ class GpuCuller {
             label: "cull",
             layout,
             entries: [
-              { binding: 0, resource: { buffer: store.instanceBuffer.buffer } },
+              { binding: 0, resource: { buffer: store.instanceBuffer.gpuBuffer } },
               { binding: 1, resource: { buffer: this.batchBuffer.buffer } },
               { binding: 2, resource: { buffer: this.lodBuffer.buffer } },
               { binding: 3, resource: { buffer: this.viewBuffer.buffer } },
@@ -317,7 +337,7 @@ class GpuCuller {
               { binding: 5, resource: { buffer: this.visible.buffer } },
               { binding: 6, resource: { buffer: this.lodState.buffer } },
               { binding: 7, resource: { buffer: params.buffer } },
-              { binding: 8, resource: { buffer: store.deform.recordBuffer.buffer } }
+              { binding: 8, resource: { buffer: store.deform.recordBuffer.gpuBuffer } }
             ]
           })
         )
@@ -434,6 +454,8 @@ class GpuCuller {
     while (this.pending.size > 0) await Promise.all(this.pending);
   }
 }
+const CULL_REQUEST = { root: "shard::cull" };
+const HIDDEN_REQUEST = { root: "shard::cull", defines: { HIDDEN: true } };
 function cullLayout(gpu) {
   const C = GPUShaderStage.COMPUTE;
   const read = (binding) => ({
@@ -467,6 +489,9 @@ const Culler = defineResource("render/Culler", {
 function cullTransparent(store, list, params, forward) {
   store.cullTransparentMembers(list, params, forward);
 }
+function cullGround(store, list, params, overlay) {
+  store.cullGroundMembers(list, params, overlay);
+}
 function visibleSlots(store, list, mask = SLOT_MASK) {
   const out = /* @__PURE__ */ new Set();
   for (let d = 0; d < list.length; d++) {
@@ -492,6 +517,7 @@ async function readVisibleSlots(gpu, culler, list, mask = SLOT_MASK) {
 export {
   Culler,
   GpuCuller,
+  cullGround,
   cullTransparent,
   readVisibleSlots,
   visibleSlots

package/dist/cutaway-plugin.d.ts

@@ -0,0 +1,48 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import { GpuBuffer } from '@aethervtt/shard-gpu';
+export declare const CUTAWAY_SHADERS: Record<string, string>;
+/** A camera's reveal points as uploaded, and the bind group over them. */
+interface CutawayCamera {
+    data: Float32Array;
+    buffer: GpuBuffer | undefined;
+    bindGroup: GPUBindGroup | undefined;
+    /** The device generation and buffer version the bind group was made for. */
+    boundGeneration: number;
+    boundVersion: number;
+    /** Points in use (at most MAX_REVEAL_POINTS). */
+    count: number;
+    /** Points the component listed. */
+    listed: number;
+    frame: number;
+    /** Too many points was reported for this camera. */
+    warned: boolean;
+    /** The device generation its buffer was last written on (a new device loses the contents). */
+    written: number;
+    /** Per batch index: 1 when a point can cut one of its Cutaway instances this frame. */
+    cuts: Uint8Array;
+}
+export interface CutawayState {
+    cameras: Map<Entity, CutawayCamera>;
+    frame: number;
+    layout: {
+        layout: GPUBindGroupLayout;
+        generation: number;
+    } | undefined;
+}
+export declare const CutawayCameras: import("@aethervtt/shard-core").ResourceDef<CutawayState>;
+/**
+ * Packs each camera's CutawayView into its uniform, with each point's line of sight from the
+ * camera. Only a camera whose values changed uploads (a camera moving changes the lines); a still
+ * frame writes nothing and allocates nothing.
+ */
+export declare const extractCutaways: import("@aethervtt/shard-core").SystemDef<{
+    q: import("@aethervtt/shard-core").Query;
+}>;
+/** render.describe's cutaways section: per camera, its reveal points, radius, margin and edge. */
+export declare function describeCutaways(world: World): Record<string, unknown>;
+/**
+ * Cutaways (0070): Cutaway renderables open around a camera's CutawayView points, in every camera
+ * pass and no shadow pass. Cameras without reveal points draw the plain variants.
+ */
+export declare const cutawayPlugin: import("@aethervtt/shard-runtime").Plugin;
+export {};