@aethervtt/shard-render 0.0.1 → 0.2.0

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)]

package/dist/decals-plugin.d.ts

@@ -0,0 +1,5 @@
+import { VfxRenderer } from './vfx-draw.js';
+export declare const DecalGpu: import("@aethervtt/shard-core").ResourceDef<{
+    renderer?: VfxRenderer;
+}>;
+export declare const decalsPlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/decals-plugin.js

@@ -0,0 +1,54 @@
+import { defineResource, defineSystem, Last, PostUpdate } from "@aethervtt/shard-core";
+import { definePlugin, FrameDemand } from "@aethervtt/shard-runtime";
+import { TransformSystems } from "@aethervtt/shard-transform";
+import { Decals, describeDecals, updateDecals } from "./decals.js";
+import { addRenderFeatures } from "./features.js";
+import { Graph, RenderDescribers, RenderSet, Shaders } from "./plugin.js";
+import { registerShaders } from "./shaders.js";
+import { DecalsPath } from "./vfx.js";
+import { VFX_SHADERS, VfxRenderer } from "./vfx-draw.js";
+import { computeVisibility } from "./visibility.js";
+const DecalGpu = defineResource("render/DecalGpu", {
+  init: () => ({})
+});
+const prune = defineSystem({
+  name: "render/decals-prune",
+  run: (_, world) => world.resource(DecalGpu).renderer?.prune(world)
+});
+const decalsPlugin = definePlugin({
+  name: "render/decals",
+  dependencies: ["render/forward"],
+  provides: [Decals, DecalGpu, updateDecals],
+  build(app) {
+    app.world.initResource(DecalsPath);
+    app.world.initResource(Decals);
+    app.world.initResource(DecalGpu);
+    app.addSystems(PostUpdate, updateDecals.after(TransformSystems, computeVisibility));
+    app.addSystems(Last, prune.inSet(RenderSet.Prepare));
+  },
+  ready(app) {
+    const w = app.world, renderer = new VfxRenderer(w.resource(Decals).records, true);
+    w.resource(DecalGpu).renderer = renderer;
+    registerShaders(w.resource(Shaders), VFX_SHADERS);
+    addRenderFeatures(w, {
+      name: "render/decals",
+      description: "Clipped rigid-mesh projected decals.",
+      nodes: ["decals"],
+      baseline: { strategy: "CPU projection and the same vertex/fragment passes" }
+    });
+    w.resource(Graph).addNode("decals", renderer.node());
+    w.initResource(RenderDescribers).set("decals", describeDecals);
+  },
+  dispose(app) {
+    app.world.resource(DecalGpu).renderer?.dispose();
+    const s = app.world.resource(Decals);
+    s.records.length = 0;
+    s.receivers.length = 0;
+    s.receiverByEntity.clear();
+    app.world.tryResource(FrameDemand)?.set("render/decals", false);
+  }
+});
+export {
+  DecalGpu,
+  decalsPlugin
+};

package/dist/decals.d.ts

@@ -0,0 +1,69 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import type { Mesh } from '@aethervtt/shard-mesh';
+import { type VfxRecord } from './vfx-state.js';
+export declare const DECAL_TRIANGLE_BUDGET = 32768;
+export interface DecalRange {
+    start: number;
+    count: number;
+    entity: Entity;
+    layers: number;
+}
+interface Receiver {
+    entity: Entity;
+    matrix: Float64Array;
+    mesh: Mesh | undefined;
+    version: number;
+    mask: number;
+    visible: boolean;
+    unsupported: boolean;
+    layers: number;
+    seen: number;
+}
+export interface DecalRecord extends VfxRecord {
+    inverse: Float64Array;
+    settings: Float64Array;
+    geometryCount: number;
+    receiverRevision: number;
+    rebuilds: number;
+    ranges: DecalRange[];
+    clipA: Float64Array;
+    clipB: Float64Array;
+    worldTriangle: Float64Array;
+}
+export declare const Decals: import("@aethervtt/shard-core").ResourceDef<{
+    records: DecalRecord[];
+    receivers: Receiver[];
+    receiverByEntity: Map<number, Receiver>;
+    frame: number;
+    revision: number;
+    rejected: number;
+}>;
+/** Clips a convex polygon against one axis-aligned half-space. Scratch fits a clipped triangle. */
+export declare function clipPlane(input: Float64Array, count: number, output: Float64Array, axis: number, sign: number, half: number): number;
+/** Cold projection work. Output is all-or-nothing on budget/unsupported errors. */
+export declare function projectDecal(r: DecalRecord, receivers: readonly Receiver[]): void;
+export declare const updateDecals: import("@aethervtt/shard-core").SystemDef<{
+    q: import("@aethervtt/shard-core").Query;
+    receivers: import("@aethervtt/shard-core").Query;
+}>;
+export declare function describeDecals(world: World): {
+    rejected: number;
+    error: string | null;
+    receivers: number;
+    records: {
+        entity: number;
+        kind: "beam" | "decal" | "trail";
+        vertices: number;
+        age: number;
+        opacity: number;
+        error: string | null;
+        visible: boolean;
+        texture: string;
+        playing: boolean;
+        paused: boolean;
+        cpuBytes: number;
+        rebuilds: number;
+        triangles: number;
+    }[];
+};
+export {};