@aethervtt/shard-render 0.0.1 → 0.2.0

package/dist/ablation.d.ts

@@ -0,0 +1,74 @@
+import { type World } from '@aethervtt/shard-core';
+/**
+ * Per-pass GPU cost by ablation (0075). On tile-based GPUs passes overlap and a pass's timestamps
+ * include waiting for earlier work, so per-pass times add up to more than the frame. `gpu:frame`
+ * (first pass start to last pass end) stays true, so a pass's cost is how much `gpu:frame` drops
+ * with the pass disabled.
+ */
+export interface AblationOptions {
+    /** Render-graph nodes to measure, each on its own. */
+    passes: readonly string[];
+    /** Frames measured per pass and round (the median is kept). Default 120. */
+    frames?: number;
+    /** Rounds, each measuring every pass and the baseline; the median over rounds is kept. Default 5. */
+    rounds?: number;
+    /** Frames dropped after each change, while timings of the previous state land. Default 4. */
+    settle?: number;
+    /** Also measure every pass disabled at once. */
+    together?: boolean;
+    /**
+     * Names in `passes` that stand for several nodes, disabled together (0075's scenario tests ablate
+     * a slice: every node whose `gpu:<node>` its key covers).
+     */
+    groups?: Readonly<Record<string, readonly string[]>>;
+}
+export interface PassCost {
+    /** The node, or every node joined with '+' for `together`. */
+    pass: string;
+    /** Median over rounds of baseline `gpu:frame` minus `gpu:frame` with the pass disabled, in ms. */
+    ms: number;
+    /** Each round's difference. */
+    rounds: number[];
+}
+export interface AblationResult {
+    /** Median `gpu:frame` with every pass enabled, in ms. */
+    frameMs: number;
+    passes: PassCost[];
+    /** Every pass disabled at once, with `together`. */
+    together?: PassCost;
+    frames: number;
+    rounds: number;
+    /** GPU frame timings read, all states together. */
+    samples: number;
+}
+export interface PassCostsData {
+    /**
+     * The latest ablation in this app, and when it finished (`Time.elapsed`, s). The `perf` overlay
+     * and the playground HUD rank passes by it where their timestamps overlap (0075).
+     */
+    latest: (AblationResult & {
+        at: number;
+    }) | undefined;
+}
+/** The latest `perf.ablate` result, where the overlay, the HUD and `perf.describe` read it. */
+export declare const PassCosts: import("@aethervtt/shard-core").ResourceDef<PassCostsData>;
+/** How a measurement drives the app: what to disable, and one frame's `gpu:frame`. */
+export interface AblationDriver {
+    disable(passes: readonly string[]): void;
+    /** Renders a frame and resolves its `gpu:frame` in ms, or undefined when none landed. */
+    frame(): Promise<number | undefined>;
+}
+/**
+ * The measurement, apart from any app: each round measures the baseline, every pass disabled in
+ * turn (in reverse order on odd rounds), and the baseline again; a pass's difference in a round is
+ * the mean of the two baselines minus its median. Interleaving rounds cancels thermal drift, as
+ * `structure/src/cutaway.test.ts` does. Restores every pass before it returns or throws.
+ */
+export declare function runAblation(driver: AblationDriver, options: AblationOptions): Promise<AblationResult>;
+/**
+ * Ablates render-graph passes in a running app: `frame` produces one frame (rendering without
+ * advancing time, or waiting for the loop). Reads `gpu:frame` from the graph's `GpuTimer`, so the
+ * device needs `timestamp-query` (`render/gpu-timing-unavailable` otherwise). Unknown passes throw
+ * `render/unknown-node`.
+ */
+export declare function ablatePasses(world: World, options: AblationOptions, frame: () => Promise<void> | void): Promise<AblationResult>;

package/dist/ablation.js

@@ -0,0 +1,117 @@
+import { defineResource, ShardError } from "@aethervtt/shard-core";
+import { PerfProviders, Time } from "@aethervtt/shard-runtime";
+import { Gpu, Graph } from "./plugin.js";
+const PassCosts = defineResource("render/PassCosts", {
+  description: "The latest ablation's per-pass GPU costs (0075): what ranks passes where their timestamps overlap.",
+  init: () => ({ latest: void 0 })
+});
+function keep(world, result) {
+  const costs = world.initResource(PassCosts);
+  costs.latest = { ...result, at: world.tryResource(Time)?.elapsed ?? 0 };
+  const sections = world.initResource(PerfProviders).sections;
+  if (!sections.has("ablation")) {
+    sections.set("ablation", (w) => {
+      const latest = w.tryResource(PassCosts)?.latest;
+      if (!latest) return void 0;
+      return {
+        at: latest.at,
+        frameMs: latest.frameMs,
+        passes: [...latest.passes].sort((a, b) => b.ms - a.ms).map((p) => ({ pass: p.pass, ms: p.ms })),
+        ...latest.together ? { together: latest.together.ms } : {}
+      };
+    });
+  }
+}
+const median = (values) => {
+  if (values.length === 0) return Number.NaN;
+  const sorted = [...values].sort((a, b) => a - b);
+  const mid = sorted.length >> 1;
+  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+};
+async function runAblation(driver, options) {
+  const frames = options.frames ?? 120;
+  const rounds = options.rounds ?? 5;
+  const settle = options.settle ?? 4;
+  const sets = options.passes.map((p) => [p]);
+  if (options.together && options.passes.length > 1) sets.push(options.passes);
+  let samples = 0;
+  const measure = async (disabled) => {
+    driver.disable(disabled);
+    for (let i = 0; i < settle; i++) await driver.frame();
+    const times = [];
+    for (let i = 0; i < frames; i++) {
+      const ms = await driver.frame();
+      if (ms !== void 0) times.push(ms);
+    }
+    samples += times.length;
+    return median(times);
+  };
+  const diffs = sets.map(() => []);
+  const baselines = [];
+  try {
+    for (let round = 0; round < rounds; round++) {
+      const before = await measure([]);
+      const order = sets.map((_, i) => i);
+      if (round % 2 === 1) order.reverse();
+      const off = /* @__PURE__ */ new Map();
+      for (const i of order) off.set(i, await measure(sets[i]));
+      const after = await measure([]);
+      const base = (before + after) / 2;
+      baselines.push(base);
+      for (let i = 0; i < sets.length; i++) diffs[i].push(base - off.get(i));
+    }
+  } finally {
+    driver.disable([]);
+  }
+  const costs = sets.map(
+    (set, i) => ({ pass: set.join("+"), ms: median(diffs[i]), rounds: diffs[i] })
+  );
+  const together = options.together && options.passes.length > 1 ? costs.pop() : void 0;
+  return {
+    frameMs: median(baselines),
+    passes: costs,
+    ...together ? { together } : {},
+    frames,
+    rounds,
+    samples
+  };
+}
+async function ablatePasses(world, options, frame) {
+  const graph = world.resource(Graph);
+  const gpu = world.resource(Gpu);
+  if (!graph.timer.enabled) {
+    throw new ShardError("render/gpu-timing-unavailable", "This device can't time GPU passes", {
+      hint: "Ablation reads gpu:frame, which needs the 'timestamp-query' feature."
+    });
+  }
+  if (options.passes.length === 0) {
+    throw new ShardError("render/unknown-node", "No passes to ablate", {
+      hint: `Name render graph nodes: ${graph.nodeNames().join(", ")}.`
+    });
+  }
+  const groups = options.groups;
+  const nodesOf = (passes) => groups ? passes.flatMap((p) => groups[p] ?? [p]) : passes;
+  graph.ablate(nodesOf(options.passes));
+  graph.ablate([]);
+  const timer = graph.timer;
+  const driver = {
+    disable: (passes) => graph.ablate(nodesOf(passes)),
+    async frame() {
+      const seen = timer.frameSamples;
+      await frame();
+      for (let i = 0; i < 8 && timer.frameSamples === seen; i++) {
+        await gpu.device.queue.onSubmittedWorkDone();
+        await new Promise((resolve) => setTimeout(resolve, 0));
+      }
+      return timer.frameSamples === seen ? void 0 : timer.frameMs;
+    }
+  };
+  const result = await runAblation(driver, options);
+  keep(world, result);
+  return result;
+}
+export {
+  PassCosts,
+  ablatePasses,
+  runAblation
+};

package/dist/assets.d.ts

@@ -12,6 +12,7 @@ export declare const StandardMaterial: import("@aethervtt/shard-core").Component
     emissive: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
     emissiveLuminance: import("@aethervtt/shard-core").FieldType<number, "f32">;
     doubleSided: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    deferUntilReady: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
     alphaMode: import("@aethervtt/shard-core").FieldType<"additive" | "alpha" | "mask" | "opaque" | "premultiplied", "u8">;
     alphaCutoff: import("@aethervtt/shard-core").FieldType<number, "f32">;
     normalScale: import("@aethervtt/shard-core").FieldType<number, "f32">;
@@ -94,6 +95,8 @@ export declare const Materials: import("@aethervtt/shard-core").ResourceDef<Asse
 export declare const RenderTargets: import("@aethervtt/shard-core").ResourceDef<AssetStore<RenderTarget, "RenderTarget">>;
 /** Meshes load from binary artifacts (`encodeMesh`); a reload updates the mesh in place. */
 export declare const MeshAsset: import("@aethervtt/shard-assets").AssetTypeDef<Mesh>;
+/** What a mesh that failed to load shows (0061): a 1 m beveled box, drawn with the missing material. */
+export declare function missingMesh(): Mesh;
 /** Materials load from material JSON (any type); a reload bumps the material's version. */
 export declare const MaterialAssetType: import("@aethervtt/shard-assets").AssetTypeDef<MaterialAsset>;
 /**

package/dist/assets.js

@@ -5,7 +5,7 @@ import {
   defineSchema,
   ShardError
 } from "@aethervtt/shard-core";
-import { decodeMesh } from "@aethervtt/shard-mesh";
+import { bevelBox, decodeMesh } from "@aethervtt/shard-mesh";
 import {
   allMaterialTypes,
   findMaterialType,
@@ -103,8 +103,20 @@ const RenderTargets = defineResource(
 const MeshAsset = defineAssetType("Mesh", {
   store: Meshes,
   load: (artifact) => decodeMesh(artifact.bytes),
-  update: (existing, next) => existing.update(next.data())
+  update: (existing, next) => existing.update(next.data()),
+  fallback: () => missingMesh(),
+  cost: (mesh) => ({ triangles: Math.floor(mesh.drawCount / 3), bytes: meshBytes(mesh) })
 });
+function missingMesh() {
+  const mesh = bevelBox({ x: 1, y: 1, z: 1 });
+  mesh.missing = true;
+  return mesh;
+}
+function meshBytes(mesh) {
+  let bytes = mesh.positions.byteLength + (mesh.indices?.byteLength ?? 0);
+  for (const a of [mesh.normals, mesh.uvs, mesh.uvs1, mesh.tangents]) bytes += a?.byteLength ?? 0;
+  return bytes;
+}
 const MaterialAssetType = defineAssetType("Material", {
   store: Materials,
   // Texture paths resolve to guids here, so the renderer can look them up directly.
@@ -115,6 +127,8 @@ const MaterialAssetType = defineAssetType("Material", {
     };
     const errors = validateMaterial(artifact.json, { resolveAsset });
     if (errors.length > 0) {
+      const color = readableBaseColor(artifact.json);
+      if (color) readableColors.set(ctx.guid, color);
       const first = errors[0];
       throw new ShardError("assets/load-failed", `${ctx.path}: ${first.message}`, {
         path: first.path,
@@ -127,8 +141,34 @@ const MaterialAssetType = defineAssetType("Material", {
   update: (existing, next) => {
     existing.type = next.type;
     existing.set(next.value);
+  },
+  references: (material) => handlesIn(material.value),
+  // A material that failed to load draws as the standard one, in its own base color if readable.
+  fallback: ({ guid }) => {
+    const baseColor = readableColors.get(guid);
+    readableColors.delete(guid);
+    return new MaterialAsset(baseColor ? { baseColor } : {});
   }
 });
+function* handlesIn(value) {
+  if (value === null || typeof value !== "object" || ArrayBuffer.isView(value)) return;
+  if (Array.isArray(value)) {
+    for (const v of value) yield* handlesIn(v);
+    return;
+  }
+  if (typeof value.guid === "string") yield value;
+  for (const v of Object.values(value)) yield* handlesIn(v);
+}
+const readableColors = /* @__PURE__ */ new Map();
+function readableBaseColor(json) {
+  const raw = json?.baseColor;
+  if (raw === void 0) return void 0;
+  try {
+    return [...StandardMaterial.deserialize({ baseColor: raw }).baseColor];
+  } catch {
+    return void 0;
+  }
+}
 const MaterialImporter = defineImporter({
   name: "data/material",
   version: 2,
@@ -209,5 +249,6 @@ export {
   materialFields,
   materialFromJson,
   materialTypeOf,
+  missingMesh,
   validateMaterial
 };

package/dist/atmosphere-nodes.d.ts

@@ -12,6 +12,11 @@ interface CameraGpu {
     transmittance: GPUTexture | undefined;
     /** The frame the sky-view and froxels were last computed. */
     computed: number;
+    /**
+     * Whether this frame's uniform holds the atmospheres (it's zeros until their LUTs exist): a bake
+     * waits for it, or the LUTs computed this frame would bake a black sky.
+     */
+    packed: boolean;
     generation: number;
     seen: number;
 }
@@ -34,6 +39,8 @@ export declare class AtmosphereGpu {
     frame: number;
     readonly pipelines: Map<string, GPUComputePipeline | GPURenderPipeline>;
     layouts: Record<string, GPUBindGroupLayout> | undefined;
+    /** The baseline tier's passes (0064): fragment passes, loaded only on a baseline device. */
+    baseline: typeof import('./baseline/atmosphere.js') | undefined;
     private readonly groups;
     ensure(gpu: GpuContext): void;
     /** A layer for a record: its own, a free one, or the least recently used. */
@@ -42,6 +49,8 @@ export declare class AtmosphereGpu {
     group(gpu: GpuContext, slot: string, key: string, layout: GPUBindGroupLayout, entries: () => GPUBindGroupEntry[]): GPUBindGroup;
 }
 export declare const AtmosphereGpuResource: import("@aethervtt/shard-core").ResourceDef<AtmosphereGpu>;
+/** Writes a record's parameters (and the camera's origin in it) at `o`. */
+export declare function packParams(rec: AtmosphereRecord, out: Float32Array, o: number, origin: Float64Array | undefined, oi: number): void;
 /**
  * Gives every listed atmosphere a LUT layer and uploads each camera's AtmosphereView uniform, and
  * its sky-view and froxel textures at the right sizes.