@aethervtt/shard-render 0.0.1 → 0.2.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/crowd.d.ts

@@ -0,0 +1,21 @@
+import { type World } from '@aethervtt/shard-core';
+export interface CrowdOptions {
+    /** Instances (default 200 000). */
+    count?: number;
+    /** Every instance at full detail, no LOD (the playground's `?nolod`). */
+    flat?: boolean;
+}
+/**
+ * The crowd's turntable: 160 m out and 40 m up, looking at the field's centre, `angle` radians
+ * round (the playground turns it 2.86° a second).
+ */
+export declare function crowdCamera(angle: number): {
+    eye: [number, number, number];
+    target: [number, number, number];
+};
+/**
+ * 200k static instances of 20 mesh types over a 600 m field, under a sun with 4 shadow cascades.
+ * Most have 3 LOD levels; every fifth is a small prop hidden past 120 m. The camera is the
+ * caller's (`crowdCamera` places the turntable).
+ */
+export declare function spawnCrowd(world: World, options?: CrowdOptions): void;

package/dist/crowd.js

@@ -0,0 +1,121 @@
+import { quat, Rng } from "@aethervtt/shard-core";
+import {
+  box,
+  capsule,
+  cone,
+  cylinder,
+  plane,
+  sphere,
+  torus
+} from "@aethervtt/shard-mesh";
+import { Transform } from "@aethervtt/shard-transform";
+import { MaterialAsset, Materials, Meshes } from "./assets.js";
+import { Lod, Mesh3d, MeshMaterial, VisibilityRange } from "./instances.js";
+import { DirectionalLight } from "./lights.js";
+function kinds() {
+  const out = [];
+  for (const segments of [8, 12, 16, 24]) {
+    out.push([sphere({ radius: 0.5, segments }), sphere({ radius: 0.5, segments: 6 })]);
+  }
+  for (const y of [0.5, 0.8, 1.2]) {
+    const m = box({ x: 0.8, y, z: 0.8 });
+    out.push([m, m]);
+  }
+  for (const segments of [6, 12, 24]) {
+    out.push([
+      cylinder({ radius: 0.4, height: 1, segments }),
+      cylinder({ radius: 0.4, height: 1, segments: 5 })
+    ]);
+  }
+  for (const segments of [6, 16]) {
+    out.push([
+      cone({ radius: 0.5, height: 1.2, segments }),
+      cone({ radius: 0.5, height: 1.2, segments: 4 })
+    ]);
+  }
+  for (const segments of [8, 16]) {
+    out.push([
+      capsule({ radius: 0.3, height: 1.2, segments }),
+      capsule({ radius: 0.3, height: 1.2, segments: 4, rings: 2 })
+    ]);
+  }
+  for (const tube of [0.2, 0.1]) {
+    out.push([
+      torus({ radius: 0.4, tube }),
+      torus({ radius: 0.4, tube, radialSegments: 4, tubularSegments: 8 })
+    ]);
+  }
+  for (const y of [0.3, 0.6, 1]) {
+    const m = box({ x: 0.5, y, z: 1.2 });
+    out.push([m, m]);
+  }
+  const beam = box({ x: 1.5, y: 0.3, z: 0.3 });
+  out.push([beam, beam]);
+  return out;
+}
+function crowdCamera(angle) {
+  return { eye: [Math.sin(angle) * 160, 40, Math.cos(angle) * 160], target: [0, 0, 0] };
+}
+function spawnCrowd(world, options = {}) {
+  const count = options.count ?? 2e5;
+  const flat = options.flat ?? false;
+  world.spawn(
+    [DirectionalLight, { illuminance: 6e4, shadows: true }],
+    [Transform, { rotation: quat.fromEuler([0, 0, 0, 1], -0.8, 0.7, 0) }]
+  );
+  const meshes = world.resource(Meshes);
+  const materials = world.resource(Materials);
+  const rng = new Rng(11);
+  const stand = meshes.add(box({ x: 0.8, y: 0.8, z: 0.8 }));
+  const types = kinds().map(([hi, lo]) => {
+    const mesh = meshes.add(hi);
+    return {
+      mesh,
+      levels: [
+        { mesh, screenSize: 0.04 },
+        { mesh: meshes.add(lo), screenSize: 0.01 },
+        { mesh: stand, screenSize: 2e-3 }
+      ]
+    };
+  });
+  const looks = Array.from(
+    { length: 8 },
+    () => materials.add(
+      new MaterialAsset({
+        baseColor: [rng.range(0.2, 0.9), rng.range(0.2, 0.9), rng.range(0.2, 0.9), 1],
+        roughness: rng.range(0.2, 0.9)
+      })
+    )
+  );
+  world.spawn(
+    [Mesh3d, { mesh: meshes.add(plane({ size: 700 })) }],
+    [MeshMaterial, { material: looks[0] }],
+    Transform
+  );
+  for (let i = 0; i < count; i++) {
+    const s = rng.range(0.6, 1.8);
+    const kind = types[i % types.length];
+    const common = [
+      [MeshMaterial, { material: looks[i % looks.length] }],
+      [
+        Transform,
+        {
+          translation: [rng.range(-300, 300), s * 0.5, rng.range(-300, 300)],
+          rotation: quat.fromEuler([0, 0, 0, 1], 0, rng.float() * 6.28, 0),
+          scale: [s, s, s]
+        }
+      ]
+    ];
+    if (flat) {
+      world.spawn([Mesh3d, { mesh: kind.mesh }], ...common);
+    } else if (i % 5 === 0) {
+      world.spawn([Mesh3d, { mesh: kind.mesh }], [VisibilityRange, { end: 120 }], ...common);
+    } else {
+      world.spawn([Mesh3d, { mesh: kind.mesh }], [Lod, { levels: kind.levels }], ...common);
+    }
+  }
+}
+export {
+  crowdCamera,
+  spawnCrowd
+};

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.