@aethervtt/shard-render 0.0.1 → 0.2.0

package/dist/testing.js

@@ -3,6 +3,10 @@ import { dirname, join } from "node:path";
 import { deflateSync } from "node:zlib";
 import { Culler } from "./culling.js";
 import { captureView, Gpu, Shaders } from "./plugin.js";
+import {
+  expectScenario,
+  measureScenario
+} from "./scenario.js";
 async function settle(app, frames = 40) {
   const gpu = app.world.resource(Gpu);
   for (let i = 0; i < frames; i++) {
@@ -116,11 +120,45 @@ function compareGolden(dir, name, image) {
   }
   return { mean: sum / expected.length, max, written: false };
 }
+function watchBaseline(gpu) {
+  const found = { computePasses: 0, renderStorage: [] };
+  const device = gpu.device;
+  const createEncoder = device.createCommandEncoder.bind(device);
+  device.createCommandEncoder = (descriptor) => {
+    const encoder = createEncoder(descriptor);
+    const begin = encoder.beginComputePass.bind(encoder);
+    encoder.beginComputePass = (d) => {
+      found.computePasses++;
+      return begin(d);
+    };
+    return encoder;
+  };
+  const createLayout = device.createBindGroupLayout.bind(device);
+  device.createBindGroupLayout = (descriptor) => {
+    for (const e of descriptor.entries) {
+      const render = e.visibility & (GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT);
+      const t = e.buffer?.type;
+      if (render && (t === "storage" || t === "read-only-storage"))
+        found.renderStorage.push(`${descriptor.label ?? "?"}#${e.binding}`);
+    }
+    return createLayout(descriptor);
+  };
+  return found;
+}
+function meanDifference(a, b) {
+  let sum = 0;
+  for (let i = 0; i < a.length; i++) sum += Math.abs(a[i] - b[i]);
+  return sum / a.length;
+}
 export {
   compareGolden,
   comparePng,
+  expectScenario,
+  meanDifference,
+  measureScenario,
   pixel,
   pngBytes,
   renderView,
-  settle
+  settle,
+  watchBaseline
 };

package/dist/tier.d.ts

@@ -0,0 +1,13 @@
+import type { GpuContext } from '@aethervtt/shard-gpu';
+/**
+ * A texture's binding dimension, fixed at creation on baseline (compatibility mode and WebGL2):
+ * spread into the texture descriptor. Nothing on the full tier.
+ */
+export declare function bindingDimension(gpu: GpuContext, dimension: GPUTextureViewDimension): {
+    textureBindingViewDimension?: GPUTextureViewDimension;
+};
+/**
+ * The layout entry for a depth texture read without comparison. On baseline the shader rewrite
+ * reads it as a float texture (naga can't load from depth), so it binds as unfilterable float.
+ */
+export declare function depthReadEntry(gpu: GpuContext, binding: number, visibility: GPUShaderStageFlags, viewDimension?: GPUTextureViewDimension): GPUBindGroupLayoutEntry;

package/dist/tier.js

@@ -0,0 +1,14 @@
+function bindingDimension(gpu, dimension) {
+  return gpu.tier === "baseline" ? { textureBindingViewDimension: dimension } : {};
+}
+function depthReadEntry(gpu, binding, visibility, viewDimension = "2d") {
+  return {
+    binding,
+    visibility,
+    texture: gpu.tier === "baseline" ? { sampleType: "unfilterable-float", viewDimension } : viewDimension === "2d" ? { sampleType: "depth" } : { sampleType: "depth", viewDimension }
+  };
+}
+export {
+  bindingDimension,
+  depthReadEntry
+};

package/dist/timer.d.ts

@@ -11,6 +11,15 @@ export declare class GpuTimer {
     frameMs: number;
     /** Frames measured so far: changes when `frameMs` does. */
     frameSamples: number;
+    /**
+     * Every pass time so far was a whole number of 100 µs: the browser quantizes timestamps
+     * (0074's `gpuQuantized`). Decided after a few dozen passes.
+     */
+    quantized: boolean;
+    private passTimes;
+    private unquantized;
+    /** Each query slot's stamps at the last readback: a slot that still holds them is left over. */
+    private readonly lastStamps;
     private querySet;
     private resolveBuffer;
     private readonly readbacks;
@@ -18,11 +27,19 @@ export declare class GpuTimer {
     private generation;
     private readonly gpu;
     constructor(gpu: GpuContext);
+    /** Destroys the query set; buffers are released with the rest of the app's (0052). */
+    destroy(): void;
     beginFrame(): void;
     /** Timestamp writes for the next pass, or undefined when timing is off or full. */
     allocate(name: string): GPURenderPassTimestampWrites | undefined;
     private pendingCopy;
+    /** Pass `i`'s slot still holds the stamps it had at the last readback: the GPU skipped it. */
+    private stale;
     resolve(encoder: GPUCommandEncoder): void;
-    /** Call after submit. Records timings when the copy lands. */
+    /**
+     * Call after submit. Records timings when the copy lands: aggregates per name, and (during a
+     * capture) GPU-track spans placed from this frame's submit time, since WebGPU's clock isn't the
+     * CPU's (0074).
+     */
     readback(world: World): void;
 }

package/dist/timer.js

@@ -1,17 +1,36 @@
-import { ProfilerResource } from "@aethervtt/shard-core";
+import { ProfilerResource, TRACK } from "@aethervtt/shard-core";
 const MAX_PASSES = 96;
-const STALE_NS = 1000000000n;
 const SPANS = [
   ["gpu:span/post", (n) => n.startsWith("post/") || n === "tonemap"],
   ["gpu:span/ssao", (n) => n === "ssao" || n.startsWith("ssao/")]
 ];
 const READBACK_BUFFERS = 3;
+const QUANTUM_NS = 100000n;
+const QUANTIZED_AFTER = 32;
+const gpuNames = /* @__PURE__ */ new Map();
+function gpuName(node) {
+  let name = gpuNames.get(node);
+  if (name === void 0) {
+    name = `gpu:${node}`;
+    gpuNames.set(node, name);
+  }
+  return name;
+}
 class GpuTimer {
   enabled;
   /** The latest frame's GPU span in ms (first pass start to last pass end), once one landed. */
   frameMs = 0;
   /** Frames measured so far: changes when `frameMs` does. */
   frameSamples = 0;
+  /**
+   * Every pass time so far was a whole number of 100 µs: the browser quantizes timestamps
+   * (0074's `gpuQuantized`). Decided after a few dozen passes.
+   */
+  quantized = false;
+  passTimes = 0;
+  unquantized = false;
+  /** Each query slot's stamps at the last readback: a slot that still holds them is left over. */
+  lastStamps = new BigUint64Array(MAX_PASSES * 2);
   querySet;
   resolveBuffer;
   readbacks = [];
@@ -22,10 +41,17 @@ class GpuTimer {
     this.gpu = gpu;
     this.enabled = gpu.features.has("timestamp-query");
   }
+  /** Destroys the query set; buffers are released with the rest of the app's (0052). */
+  destroy() {
+    this.querySet?.destroy();
+    this.querySet = void 0;
+    this.generation = this.gpu.generation;
+  }
   beginFrame() {
     this.names = [];
     if (!this.enabled || this.generation === this.gpu.generation) return;
     this.generation = this.gpu.generation;
+    this.lastStamps.fill(0n);
     const device = this.gpu.device;
     this.querySet = device.createQuerySet({
       label: "gpu-timer",
@@ -46,7 +72,9 @@ class GpuTimer {
           usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
         }),
         busy: false,
-        names: []
+        names: [],
+        frame: 0,
+        submitAt: 0
       });
     }
   }
@@ -62,6 +90,11 @@ class GpuTimer {
     };
   }
   pendingCopy;
+  /** Pass `i`'s slot still holds the stamps it had at the last readback: the GPU skipped it. */
+  stale(times, i) {
+    const last = this.lastStamps;
+    return times[i * 2] === last[i * 2] && times[i * 2 + 1] === last[i * 2 + 1];
+  }
   resolve(encoder) {
     this.pendingCopy = void 0;
     if (!this.enabled || this.names.length === 0) return;
@@ -74,36 +107,54 @@ class GpuTimer {
     target.names = this.names;
     this.pendingCopy = target;
   }
-  /** Call after submit. Records timings when the copy lands. */
+  /**
+   * Call after submit. Records timings when the copy lands: aggregates per name, and (during a
+   * capture) GPU-track spans placed from this frame's submit time, since WebGPU's clock isn't the
+   * CPU's (0074).
+   */
   readback(world) {
+    const profiler = world.tryResource(ProfilerResource);
+    if (profiler) profiler.gpu.status = this.enabled ? "available" : "unavailable";
     const target = this.pendingCopy;
     if (!target) return;
     this.pendingCopy = void 0;
+    target.frame = profiler?.frame ?? 0;
+    target.submitAt = profiler ? profiler.now() : 0;
     const generation = this.generation;
     target.buffer.mapAsync(GPUMapMode.READ).then(
       () => {
         if (generation !== this.gpu.generation) return;
         const times = new BigUint64Array(target.buffer.getMappedRange());
-        const profiler = world.tryResource(ProfilerResource);
         const totals = /* @__PURE__ */ new Map();
-        let latest = 0n;
-        for (let i = 0; i < target.names.length; i++) {
-          const end = times[i * 2 + 1];
-          if (end > latest) latest = end;
-        }
-        const stale = latest - STALE_NS;
+        const count = target.names.length * 2;
         let first = 0n;
-        let last = 0n;
+        let lastEnd = 0n;
         for (let i = 0; i < target.names.length; i++) {
           const begin = times[i * 2];
           const end = times[i * 2 + 1];
-          if (begin === 0n || end < begin || begin < stale) continue;
+          if (begin === 0n || end < begin || this.stale(times, i)) continue;
           const name = target.names[i];
           totals.set(name, (totals.get(name) ?? 0) + Number(end - begin) / 1e6);
           if (first === 0n || begin < first) first = begin;
-          if (end > last) last = end;
+          if (end > lastEnd) lastEnd = end;
+          if (end > begin) {
+            if ((end - begin) % QUANTUM_NS !== 0n) this.unquantized = true;
+            this.passTimes++;
+          }
+        }
+        if (this.passTimes >= QUANTIZED_AFTER) this.quantized = !this.unquantized;
+        if (profiler) profiler.gpu.quantized = this.quantized;
+        for (const [name, ms] of totals) profiler?.sample(gpuName(name), ms);
+        const at = (stamp) => target.submitAt + Number(stamp - first) / 1e6;
+        if (profiler?.capturing && first !== 0n) {
+          for (let i = 0; i < target.names.length; i++) {
+            const begin = times[i * 2];
+            const end = times[i * 2 + 1];
+            if (begin === 0n || end < begin || this.stale(times, i)) continue;
+            const ms = Number(end - begin) / 1e6;
+            profiler.event(gpuName(target.names[i]), TRACK.gpu, at(begin), ms, target.frame);
+          }
         }
-        for (const [name, ms] of totals) profiler?.record(`gpu:${name}`, ms);
         for (let g = 0; g < SPANS.length; g++) {
           const [label, match] = SPANS[g];
           let a = 0n;
@@ -111,17 +162,19 @@ class GpuTimer {
           for (let i = 0; i < target.names.length; i++) {
             const begin = times[i * 2];
             const end = times[i * 2 + 1];
-            if (begin === 0n || end < begin || begin < stale || !match(target.names[i])) continue;
+            if (begin === 0n || end < begin || this.stale(times, i) || !match(target.names[i]))
+              continue;
             if (a === 0n || begin < a) a = begin;
             if (end > b) b = end;
           }
-          if (b > a) profiler?.record(label, Number(b - a) / 1e6);
+          if (b > a) profiler?.record(label, Number(b - a) / 1e6, TRACK.gpu, at(a), target.frame);
         }
-        if (last > first) {
-          this.frameMs = Number(last - first) / 1e6;
+        if (first !== 0n) {
+          this.frameMs = Number(lastEnd - first) / 1e6;
           this.frameSamples++;
-          profiler?.record("gpu:frame", this.frameMs);
+          profiler?.record("gpu:frame", this.frameMs, TRACK.gpu, target.submitAt, target.frame);
         }
+        for (let k = 0; k < count; k++) this.lastStamps[k] = times[k];
         target.buffer.unmap();
         target.busy = false;
       },

package/dist/variants.d.ts

@@ -0,0 +1,37 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import type { App } from '@aethervtt/shard-runtime';
+/** A kind of manifest entry, and how to show the variants it names. */
+export interface ShaderVariantSource {
+    /** The entry's key: `{ "dice": … }` is run by the source named `dice`. */
+    readonly name: string;
+    readonly description: string;
+    /**
+     * Shows every variant `entry` names for at least a frame, stepping the app until their pipelines
+     * are made (`app.update`, then `Shaders.whenIdle` and `gpu.pipelines.whenIdle`). Returns how many
+     * variants it showed.
+     */
+    show(app: App, entry: unknown): Promise<number>;
+}
+export declare const ShaderVariantSources: import("@aethervtt/shard-core").ResourceDef<Map<string, ShaderVariantSource>>;
+/** Registers a manifest entry kind. Plugins call it in `build`. */
+export declare function addShaderVariantSource(world: World, source: ShaderVariantSource): void;
+/** The manifest's shape. */
+export interface ShaderVariantManifest {
+    variants: Record<string, unknown>[];
+}
+/** Runs one manifest entry through its source. Throws `render/unknown-variant-source` for a key no plugin registered. */
+export declare function showVariants(app: App, entry: Record<string, unknown>): Promise<number>;
+/** A material asset's path (or guid) and parameter overrides. */
+export interface MaterialVariantEntry {
+    path?: string;
+    guid?: string;
+    params?: Record<string, unknown>;
+}
+/**
+ * Shows what `spawn` makes to a camera of its own (an offscreen target, a shadowed sun), stepping
+ * the app until every pipeline it asked for is made, then takes it all away again. For variant
+ * sources: what's drawn is what a bake records.
+ */
+export declare function showToCamera(app: App, spawn: (at: [number, number, number]) => Entity[]): Promise<void>;
+/** `{ "material": { "path": …, "params": … } }`: a material asset, with its parameters set, on a cube. */
+export declare const materialVariants: ShaderVariantSource;

package/dist/variants.js

@@ -0,0 +1,104 @@
+import { assetServer } from "@aethervtt/shard-assets";
+import {
+  defineResource,
+  ShardError
+} from "@aethervtt/shard-core";
+import { cube } from "@aethervtt/shard-mesh";
+import { lookAt, Transform } from "@aethervtt/shard-transform";
+import { Materials, Meshes, RenderTargets } from "./assets.js";
+import { Camera3d } from "./camera.js";
+import { Mesh3d, MeshMaterial } from "./instances.js";
+import { DirectionalLight } from "./lights.js";
+import { Gpu, Shaders } from "./plugin.js";
+import { OffscreenTarget } from "./target.js";
+const ShaderVariantSources = defineResource(
+  "render/ShaderVariantSources",
+  {
+    description: "Kinds of shaders.variants.json entries (0064) and how to show their variants, for `shard shaders bake`.",
+    init: () => /* @__PURE__ */ new Map()
+  }
+);
+function addShaderVariantSource(world, source) {
+  world.initResource(ShaderVariantSources).set(source.name, source);
+}
+function showVariants(app, entry) {
+  const keys = Object.keys(entry);
+  if (keys.length !== 1) {
+    throw new ShardError(
+      "render/variant-entry",
+      `A shaders.variants.json entry has one key, its source: got ${keys.length ? keys.join(", ") : "none"}`
+    );
+  }
+  const name = keys[0];
+  const source = app.world.tryResource(ShaderVariantSources)?.get(name);
+  if (!source) {
+    const known = [...app.world.tryResource(ShaderVariantSources)?.keys() ?? []];
+    throw new ShardError("render/unknown-variant-source", `No shader variant source "${name}"`, {
+      hint: `Known: ${known.join(", ") || "none"}. Plugins register theirs with addShaderVariantSource.`
+    });
+  }
+  return source.show(app, entry[name]);
+}
+const STAGE = [5e4, 0, 5e4];
+async function showToCamera(app, spawn) {
+  const world = app.world;
+  const gpu = world.resource(Gpu);
+  const target = new OffscreenTarget(gpu, { label: "shader-variants", width: 64, height: 64 });
+  const ref = world.resource(RenderTargets).add(target, `render:variants/${STAGE.join(",")}`);
+  const eye = [STAGE[0], STAGE[1] + 2, STAGE[2] + 4];
+  const made = [
+    world.spawn(
+      [Camera3d, { target: ref, order: 90 }],
+      [Transform, { translation: eye, rotation: lookAt(eye, STAGE) }]
+    ),
+    world.spawn(
+      [DirectionalLight, { shadows: true }],
+      [Transform, { translation: STAGE, rotation: lookAt([0, 0, 0], [-0.4, -1, -0.3]) }]
+    ),
+    ...spawn(STAGE)
+  ];
+  try {
+    for (let i = 0; i < 8; i++) {
+      app.update(1 / 60);
+      await world.resource(Shaders).whenIdle();
+      await gpu.pipelines.whenIdle();
+    }
+  } finally {
+    for (const e of made) if (world.isAlive(e)) world.despawn(e);
+    app.update(1 / 60);
+    target.destroy?.();
+  }
+}
+const materialVariants = {
+  name: "material",
+  description: "A material asset by path or guid, with parameter overrides: { path, params? }.",
+  async show(app, entry) {
+    const list = Array.isArray(entry) ? entry : [entry];
+    const world = app.world;
+    for (const m of list) {
+      const ref = m.guid ? { guid: m.guid } : { path: m.path };
+      await assetServer(world).load(ref);
+      const material = world.resource(Materials).get(ref);
+      if (!material) {
+        throw new ShardError("render/variant-material", `No material ${m.guid ?? m.path}`);
+      }
+      if (m.params) material.set(m.params);
+      const mesh = world.resource(Meshes).add(cube({ size: 1 }));
+      await showToCamera(app, (at) => [
+        world.spawn(
+          [Mesh3d, { mesh }],
+          [MeshMaterial, { material: ref }],
+          [Transform, { translation: at }]
+        )
+      ]);
+    }
+    return list.length;
+  }
+};
+export {
+  ShaderVariantSources,
+  addShaderVariantSource,
+  materialVariants,
+  showToCamera,
+  showVariants
+};

package/dist/vfx-draw.d.ts

@@ -0,0 +1,37 @@
+import type { World } from '@aethervtt/shard-core';
+import { GpuBuffer } from '@aethervtt/shard-gpu';
+import { type NodeDescriptor } from './graph.js';
+import type { VfxRecord } from './vfx-state.js';
+export declare const VFX_SHADERS: {
+    'shard::vfx::ribbon': string;
+};
+interface DrawRecord {
+    source: VfxRecord;
+    view: string;
+    vertices: GpuBuffer;
+    uniform: GpuBuffer;
+    data: Float32Array;
+    group: GPUBindGroup | undefined;
+    texture: GPUTextureView | undefined;
+    version: number;
+    generation: number;
+}
+/** Per-world, per-view uniforms: two cameras never overwrite one another before submit. */
+export declare class VfxRenderer {
+    readonly draws: DrawRecord[];
+    private generation;
+    private layout;
+    private pipelines;
+    private white;
+    private whiteView;
+    private sampler;
+    private readonly decal;
+    private readonly records;
+    constructor(records: VfxRecord[], decal: boolean);
+    dispose(): void;
+    prune(world: World): void;
+    private init;
+    node(): NodeDescriptor;
+    private draw;
+}
+export {};