@aethervtt/shard-render 0.1.0 → 0.2.0

package/dist/overlays.js

@@ -15,6 +15,7 @@ import {
 import { DirectionalLight, Lights } from "./lights.js";
 import { defineOverlay, OVERLAYS, registeredOverlays } from "./overlay-registry.js";
 const extraOverlays = registeredOverlays();
+import { drawPerfOverlay } from "./perf-overlay.js";
 import { Views } from "./plugin.js";
 import { Cameras, cameraOf } from "./view.js";
 import {
@@ -35,7 +36,7 @@ function scenePath(world, entity) {
 }
 const DebugOverlays = defineResource("render/DebugOverlays", {
   hostWritable: true,
-  description: "Built-in debug drawings, each drawn through Gizmos: bounds, light volumes, camera frustums, shadow cascades, normals, transform axes, and entity labels.",
+  description: "Built-in debug drawings, each drawn through Gizmos: bounds, light volumes, camera frustums, shadow cascades, normals, transform axes, entity labels, and perf (frame time, top spans, GPU frame).",
   init: () => ({
     bounds: false,
     lights: false,
@@ -44,6 +45,7 @@ const DebugOverlays = defineResource("render/DebugOverlays", {
     normals: false,
     axes: false,
     labels: false,
+    perf: false,
     extra: {},
     filter: { components: [], path: "" },
     name: scenePath
@@ -227,7 +229,7 @@ const drawOverlays = defineSystem({
     g.overlay.clear();
     let extra = false;
     for (const name in o.extra) if (o.extra[name] && extraOverlays.has(name)) extra = true;
-    if (!(o.bounds || o.lights || o.cameras || o.cascades || o.normals || o.axes || o.labels || extra))
+    if (!(o.bounds || o.lights || o.cameras || o.cascades || o.normals || o.axes || o.labels || o.perf || extra))
       return;
     g.beginOverlays();
     try {
@@ -250,6 +252,7 @@ function draw(world, o, g) {
     }
     if (o.lights) drawLights(world, o, g, defs);
     const primary = primaryCamera(world);
+    if (o.perf) drawPerfOverlay(world, g, primary);
     if (o.cameras) {
       for (const [entity, cam] of world.resource(Cameras)) {
         if (entity === primary || !passes(world, o, entity, defs)) continue;

package/dist/perf-overlay.d.ts

@@ -0,0 +1,9 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import type { GizmoStore } from './gizmos.js';
+/** The overlay's text and colours: refreshed four times a second, so it's readable and cheap. */
+export declare function perfOverlayLines(world: World): {
+    lines: string[];
+    colors: number[][];
+};
+/** Draws the perf overlay for the primary camera. Gizmo labels center on their anchor, above it. */
+export declare function drawPerfOverlay(world: World, g: GizmoStore, camera: Entity | undefined): void;

package/dist/perf-overlay.js

@@ -0,0 +1,125 @@
+import { ProfilerResource, spanStats } from "@aethervtt/shard-core";
+import {
+  gpuPassOverlap,
+  isGpuPass,
+  measureSlices,
+  PerfBudgets,
+  PerfScenario,
+  perfBudgetState,
+  Time
+} from "@aethervtt/shard-runtime";
+import { PassCosts } from "./ablation.js";
+import { LABEL_FONT, labelWidth } from "./gizmo-font.js";
+import { Cameras } from "./view.js";
+const LINES = 8;
+const PASS_LINES = 4;
+const REFRESH_S = 0.25;
+const MARGIN = 8;
+const COLOR = [1, 1, 1, 1];
+const HEADER = [0.55, 0.9, 1, 1];
+const GREY = [0.6, 0.6, 0.6, 1];
+const RED = [1, 0.35, 0.3, 1];
+const LABEL_OPTIONS = { depthTest: false };
+const states = /* @__PURE__ */ new WeakMap();
+const pad = (ms) => ms.toFixed(2).padStart(6);
+const percent = (share) => `${Math.round(share * 100)}%`.padStart(4);
+function perfOverlayLines(world) {
+  const now = world.tryResource(Time)?.elapsed ?? 0;
+  let state = states.get(world);
+  if (state && now - state.at < REFRESH_S && now >= state.at) return state;
+  const profiler = world.tryResource(ProfilerResource);
+  const lines = [];
+  const colors = [];
+  const line = (text, color) => {
+    lines.push(text);
+    colors.push(color);
+  };
+  if (profiler) {
+    const frame = spanStats(profiler, "frame");
+    const gpu = spanStats(profiler, "gpu:frame");
+    line(
+      `frame ${frame ? pad(frame.avg) : "     -"} ms  p95 ${frame ? pad(frame.p95) : "     -"}` + (profiler.gpu.status === "unavailable" ? "   gpu n/a" : `   gpu ${gpu ? pad(gpu.avg) : "     -"} ms`),
+      HEADER
+    );
+    const overlapping = gpuPassOverlap(profiler)?.overlapping ?? false;
+    const spans = [];
+    const passes = [];
+    for (const name2 of profiler.names()) {
+      if (name2 === "frame" || name2 === "gpu:frame" || name2.startsWith("schedule/") || name2.startsWith("commands/"))
+        continue;
+      const entry = { name: name2, avg: profiler.timing(name2).avg };
+      if (overlapping && name2.startsWith("gpu:")) {
+        if (isGpuPass(name2)) passes.push(entry);
+      } else spans.push(entry);
+    }
+    spans.sort((a, b) => b.avg - a.avg || (a.name < b.name ? -1 : 1));
+    for (let i = 0; i < Math.min(LINES, spans.length); i++) {
+      line(`${pad(spans[i].avg)} ms  ${spans[i].name}`, COLOR);
+    }
+    if (overlapping) {
+      const ablation = world.tryResource(PassCosts)?.latest;
+      if (ablation && ablation.passes.length > 0) {
+        line("gpu passes by ablation (timestamps overlap)", GREY);
+        const ranked = [...ablation.passes].sort((a, b) => b.ms - a.ms);
+        for (let i = 0; i < Math.min(PASS_LINES, ranked.length); i++) {
+          line(`${pad(ranked[i].ms)} ms  gpu:${ranked[i].pass}  ablated`, COLOR);
+        }
+      } else {
+        line("gpu passes overlapping: perf.ablate ranks them", GREY);
+        passes.sort((a, b) => a.name < b.name ? -1 : 1);
+        for (let i = 0; i < Math.min(PASS_LINES, passes.length); i++) {
+          line(`${pad(passes[i].avg)} ms  ${passes[i].name}  overlapping`, GREY);
+        }
+      }
+    }
+    const name = world.tryResource(PerfScenario)?.name;
+    const scenario = name ? world.tryResource(PerfBudgets)?.budgets.scenarios[name] : void 0;
+    if (name && scenario) {
+      const machine = perfBudgetState(world)?.detection.machine ?? null;
+      line(`scenario ${name}${machine ? ` on ${machine}` : ""}: share of frame / budget`, HEADER);
+      for (const s of measureSlices(profiler, scenario, machine).slices) {
+        const measured = s.measuredShare === null ? "   -" : percent(s.measuredShare);
+        line(
+          `${s.track} ${measured} / ${percent(s.share)}  ${s.slice}`,
+          s.verdict === "over" ? RED : s.verdict === "unmeasured" ? GREY : COLOR
+        );
+      }
+    }
+  }
+  state = { at: now, lines, colors };
+  states.set(world, state);
+  return state;
+}
+const point = new Float32Array(3);
+function unproject(inv, width, height, px, py) {
+  const x = px / width * 2 - 1;
+  const y = 1 - py / height * 2;
+  const z = 0.5;
+  const w = inv[3] * x + inv[7] * y + inv[11] * z + inv[15];
+  point[0] = (inv[0] * x + inv[4] * y + inv[8] * z + inv[12]) / w;
+  point[1] = (inv[1] * x + inv[5] * y + inv[9] * z + inv[13]) / w;
+  point[2] = (inv[2] * x + inv[6] * y + inv[10] * z + inv[14]) / w;
+  return point;
+}
+function drawPerfOverlay(world, g, camera) {
+  if (camera === void 0) return;
+  const cam = world.resource(Cameras).get(camera);
+  if (!cam || cam.width <= 0 || cam.height <= 0) return;
+  const { lines, colors } = perfOverlayLines(world);
+  const step = LABEL_FONT.cellHeight + 4;
+  for (let i = 0; i < lines.length; i++) {
+    const text = lines[i];
+    const px = MARGIN + labelWidth(text) / 2;
+    const py = MARGIN + (i + 1) * step;
+    g.label(
+      unproject(cam.invViewProj, cam.width, cam.height, px, py),
+      text,
+      colors[i],
+      LABEL_OPTIONS
+    );
+  }
+}
+export {
+  drawPerfOverlay,
+  perfOverlayLines
+};

package/dist/plugin.d.ts

@@ -101,6 +101,11 @@ export declare function captureView(world: World, view?: string): Promise<Captur
  * perspective, fog, bloom…), `depth`, G-buffer channels, effect buffers.
  */
 export declare function captureBuffer(world: World, view: string, buffer: string): Promise<CapturedBuffer>;
+/** Every buffer and texture on the device by category: the ledger's total (0055, 0074). */
+export declare function gpuMemory(world: World): {
+    bytes: number;
+    byCategory: Record<string, number>;
+};
 /** What the renderer is doing: graph order, culled nodes, views, pending pipelines. For agents. */
 export declare function describeRender(world: World): {
     order: {
@@ -134,7 +139,12 @@ export declare function describeRender(world: World): {
         taaResets: number;
         originShifts: number;
     };
-    memory: import("./stats.js").GpuMemoryData;
+    memory: {
+        textures: number;
+        textureBytes: number;
+        bytes: number;
+        byCategory: Record<string, number>;
+    };
     recentErrors: {
         code: string;
         message: string;

package/dist/plugin.js

@@ -5,6 +5,7 @@ import {
   defineSystem,
   defineSystemSet,
   Last,
+  ProfilerResource,
   ShardError
 } from "@aethervtt/shard-core";
 import {
@@ -14,9 +15,11 @@ import {
   definePlugin,
   FrameDemand,
   LOADING_DEMAND,
-  LogResource
+  LogResource,
+  PerfProviders
 } from "@aethervtt/shard-runtime";
 import { ShaderLibrary } from "@aethervtt/shard-shader";
+import { PassCosts } from "./ablation.js";
 import { loadDataTextures, releaseDataStores } from "./data-store.js";
 import { checkUnsupportedFeatures, describeFeatures, RenderFeatures } from "./features.js";
 import { RenderGraph } from "./graph.js";
@@ -142,6 +145,7 @@ function renderPlugin(options = {}) {
       // graph and device
       Gpu,
       GpuDeviceLost,
+      PassCosts,
       Graph,
       RenderDescribers,
       RenderFeatures,
@@ -217,6 +221,13 @@ function renderPlugin(options = {}) {
         app.insertResource(Gpu, gpu);
         app.insertResource(Graph, new RenderGraph(gpu));
       });
+      const providers = app.world.initResource(PerfProviders);
+      providers.gpuMemory = gpuMemory;
+      providers.adapter = adapterIdentity;
+      const profiler = app.world.tryResource(ProfilerResource);
+      if (profiler) {
+        profiler.gpu.status = gpu.features.has("timestamp-query") ? "available" : "unavailable";
+      }
       app.setPresenter(presentOn(state));
       const shaders = options.shaders ?? new ShaderLibrary();
       if (!options.shaders) registerEngineShaders(shaders);
@@ -286,6 +297,20 @@ async function captureBuffer(world, view, buffer) {
   }
   return result;
 }
+function adapterIdentity(world) {
+  const info = world.tryResource(Gpu)?.adapter?.info;
+  if (!info) return void 0;
+  return {
+    vendor: info.vendor,
+    architecture: info.architecture,
+    device: info.device,
+    description: info.description
+  };
+}
+function gpuMemory(world) {
+  const memory = world.tryResource(Gpu)?.memory();
+  return memory ? { bytes: memory.bytes, byCategory: { ...memory.byCategory } } : { bytes: 0, byCategory: {} };
+}
 function describeRender(world) {
   const graph = world.tryResource(Graph);
   const gpu = world.tryResource(Gpu);
@@ -308,7 +333,12 @@ function describeRender(world) {
     gpuTimings: gpu.features.has("timestamp-query"),
     stats: Object.fromEntries(world.tryResource(RenderStats) ?? []),
     counters: { ...world.tryResource(RenderCounters) ?? { taaResets: 0, originShifts: 0 } },
-    memory: world.tryResource(GpuMemory) ?? { textures: 0, textureBytes: 0 },
+    // The ledger's total, so it agrees with perf.describe and perf records; and the textures the
+    // forward renderer uploaded, as before.
+    memory: {
+      ...gpuMemory(world),
+      ...world.tryResource(GpuMemory) ?? { textures: 0, textureBytes: 0 }
+    },
     recentErrors: gpu.errors.slice(-5).map((e) => e.toJSON()),
     features: describeFeatures(world),
     health: world.tryResource(RenderHealth) ?? { state: "ok", issues: [] },
@@ -344,6 +374,7 @@ export {
   captureBuffer,
   captureView,
   describeRender,
+  gpuMemory,
   renderOwner,
   renderPlugin
 };

package/dist/post-common.d.ts

@@ -1,6 +1,6 @@
 import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
 import { type ViewGpu } from './forward.js';
-import type { NodeContext } from './graph.js';
+import type { NodeContext, RenderView } from './graph.js';
 import { type CameraData } from './view.js';
 export declare function idOf(o: object): number;
 export declare const F: () => number;
@@ -37,7 +37,7 @@ export declare class PostCache {
     check(gpu: GpuContext): void;
     /** A fullscreen render pipeline: `shard::fullscreen` vertex stage and `root`'s `entry`. */
     render(ctx: NodeContext, key: string, root: string, entry: string, layouts: GPUBindGroupLayout[], targets: GPUColorTargetState[], defines?: Record<string, boolean>): GPURenderPipeline | undefined;
-    compute(ctx: NodeContext, key: string, root: string, entry: string, layouts: GPUBindGroupLayout[]): GPUComputePipeline | undefined;
+    compute(ctx: NodeContext, key: string, root: string, entry: string, layouts: GPUBindGroupLayout[], defines?: Record<string, boolean>): GPUComputePipeline | undefined;
     /** A bind group, rebuilt when `key` (the ids of what it binds) changes. */
     group(gpu: GpuContext, slot: string, key: string, layout: GPUBindGroupLayout, entries: () => GPUBindGroupEntry[]): GPUBindGroup;
     buffer(gpu: GpuContext, name: string, size: number): GpuBuffer;
@@ -50,4 +50,22 @@ export declare function forwardView(ctx: NodeContext): {
 /** A fullscreen pass the node begins itself (raw nodes with several passes). */
 export declare function beginPass(ctx: NodeContext, name: string, view: GPUTextureView, load?: boolean): GPURenderPassEncoder;
 export declare const HDR: GPUColorTargetState[];
+/** Color targets for a post pass that writes `texture`: the chain's format, per view. */
+export declare function targetsFor(texture: GPUTexture): GPUColorTargetState[];
+/**
+ * The format of the post chain's full-resolution ping-pong (post-a, post-b) for a view:
+ * rg11b10ufloat, half the bytes of rgba16float, where the device renders it, the view has no alpha
+ * to carry (0052's transparent views), and the device's rounding is known (`rg11Truncates`);
+ * rgba16float otherwise, and until then.
+ */
+export declare function postFormat(gpu: GpuContext, view: RenderView): GPUTextureFormat;
+/** Whether a pass writing `texture` rounds its output in the shader (the RG11_ROUND define). */
+export declare function roundsRg11(gpu: GpuContext, texture: GPUTexture): boolean;
+/**
+ * Whether the device truncates when it stores rg11b10ufloat (Metal does; the format leaves the
+ * rounding to the device). Post passes writing it then round in the shader (`rg11_round`, the
+ * RG11_ROUND define). Probed once per device, rendering 1 + 0.75 of a step and reading it back;
+ * undefined until the answer lands.
+ */
+export declare function rg11Truncates(gpu: GpuContext): boolean | undefined;
 export declare const scratch: Float32Array<ArrayBuffer>;

package/dist/post-common.js

@@ -66,12 +66,12 @@ class PostCache {
     if (pipeline) this.pipelines.set(key, pipeline);
     return pipeline;
   }
-  compute(ctx, key, root, entry, layouts) {
+  compute(ctx, key, root, entry, layouts, defines) {
     const gpu = ctx.gpu;
     this.check(gpu);
     const cached = this.pipelines.get(key);
     if (cached) return cached;
-    const module = ctx.world.resource(Shaders).module(gpu, { root });
+    const module = ctx.world.resource(Shaders).module(gpu, defines ? { root, defines } : { root });
     if (!module) {
       gpu.pipelines.skipped++;
       return void 0;
@@ -135,6 +135,79 @@ function beginPass(ctx, name, view, load = false) {
   });
 }
 const HDR = [{ format: "rgba16float" }];
+const RG11 = [{ format: "rg11b10ufloat" }];
+function targetsFor(texture) {
+  return texture.format === "rg11b10ufloat" ? RG11 : HDR;
+}
+function postFormat(gpu, view) {
+  const cam = cameraOf(view);
+  if (!gpu.features.has("rg11b10ufloat-renderable") || cam === void 0 || cam.alphaOutput)
+    return "rgba16float";
+  return rg11Truncates(gpu) === void 0 ? "rgba16float" : "rg11b10ufloat";
+}
+function roundsRg11(gpu, texture) {
+  return texture.format === "rg11b10ufloat" && rg11Truncates(gpu) === true;
+}
+const truncates = /* @__PURE__ */ new WeakMap();
+function rg11Truncates(gpu) {
+  const device = gpu.device;
+  const known = truncates.get(device);
+  if (known === "probing") return void 0;
+  if (known !== void 0) return known;
+  truncates.set(device, "probing");
+  probeRg11(device).then(
+    (v) => truncates.set(device, v),
+    // A lost device or a failed map: assume truncation, the safe side (rounding then is exact).
+    () => truncates.set(device, true)
+  );
+  return void 0;
+}
+async function probeRg11(device) {
+  const texture = device.createTexture({
+    label: "post/rg11-probe",
+    size: [1, 1],
+    format: "rg11b10ufloat",
+    usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC
+  });
+  const buffer = device.createBuffer({
+    label: "post/rg11-probe",
+    size: 4,
+    usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
+  });
+  const module = device.createShaderModule({
+    label: "post/rg11-probe",
+    code: `
+@vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {
+  let xy = vec2f(f32((i << 1u) & 2u), f32(i & 2u));
+  return vec4f(xy * 2.0 - 1.0, 0.0, 1.0);
+}
+@fragment fn fs() -> @location(0) vec4f { return vec4f(1.0 + 0.75 / 64.0, 0.0, 0.0, 1.0); }`
+  });
+  const pipeline = await device.createRenderPipelineAsync({
+    label: "post/rg11-probe",
+    layout: "auto",
+    vertex: { module, entryPoint: "vs" },
+    fragment: { module, entryPoint: "fs", targets: [{ format: "rg11b10ufloat" }] }
+  });
+  const encoder = device.createCommandEncoder({ label: "post/rg11-probe" });
+  const pass = encoder.beginRenderPass({
+    colorAttachments: [{ view: texture.createView(), loadOp: "clear", storeOp: "store" }]
+  });
+  pass.setPipeline(pipeline);
+  pass.draw(3);
+  pass.end();
+  encoder.copyTextureToBuffer({ texture }, { buffer, bytesPerRow: 256 }, [1, 1]);
+  device.queue.submit([encoder.finish()]);
+  try {
+    await buffer.mapAsync(GPUMapMode.READ);
+    const red = new Uint32Array(buffer.getMappedRange())[0] & 2047;
+    buffer.unmap();
+    return red === 15 << 6;
+  } finally {
+    texture.destroy();
+    buffer.destroy();
+  }
+}
 const scratch = new Float32Array(64);
 export {
   F,
@@ -144,8 +217,12 @@ export {
   depthTex,
   forwardView,
   idOf,
+  postFormat,
+  rg11Truncates,
+  roundsRg11,
   sampler,
   scratch,
+  targetsFor,
   tex,
   uniform
 };

package/dist/post-nodes.d.ts

@@ -2,6 +2,11 @@ import { type World } from '@aethervtt/shard-core';
 import { type CameraData } from './view.js';
 /** Mip levels of a view's bloom chain: `radius` spreads it from 3 levels to the whole view. */
 export declare function bloomLevels(cam: CameraData): number;
+/**
+ * Bloom's glow parameters for what composites it (the tonemap) and what meters it: intensity, the
+ * chain's level count (one mip per level), mix (1, no threshold) or add (0). Zeros without bloom.
+ */
+export declare function bloomGlow(cam: CameraData, chain: GPUTexture | undefined, out: Float32Array, at: number): void;
 /** Metered EV100 per camera (from the GPU histogram, a frame or two late) and the adapted EV. */
 export interface ExposureState {
     metered: number | undefined;