@aethervtt/shard-render 0.0.1 → 0.1.0

package/dist/shadow-catcher.js

@@ -0,0 +1,133 @@
+import { t } from "@aethervtt/shard-core";
+import { definePlugin } from "@aethervtt/shard-runtime";
+import { defineMaterial } from "./materials.js";
+import { Shaders } from "./plugin.js";
+import { registerShaders } from "./shaders.js";
+const SHADOW_CATCHER_SHADERS = {
+  "shard::pbr::catcher": `
+import shard::view::view;
+import shard::pbr::types::VertexOutput;
+import shard::pbr::lights::{ lights, clusters, cluster_bits, next_light, directional, light_falloff, LIGHT_SPOT, NO_SHADOW, CLUSTER_COUNT, MAX_PER_CLUSTER };
+import shard::pbr::shadows::{ directional_shadow, spot_shadow, point_shadow };
+import shard::pbr::lighting::cluster_of;
+
+const FLAG_RECEIVER: u32 = 4u;
+
+fn brightest(c: vec3f) -> f32 { return max(c.r, max(c.g, c.b)); }
+
+/**
+ * How much of the shadow-casting light reaches the surface: the light of every shadow-casting
+ * light with shadows, over that light without them. 1 when none cast shadows, or when the mesh
+ * doesn't receive them. Shadow catchers (and the dice tray, 0054) turn 1 \u2212 this into alpha.
+ */
+fn shadow_visibility(in: VertexOutput) -> f32 {
+  if ((in.flags & FLAG_RECEIVER) == 0u) { return 1.0; }
+  let n = normalize(in.world_normal);
+  let p = in.world_position;
+  let view_depth = -(view.view * vec4f(p, 1.0)).z;
+  var lit = 0.0;
+  var total = 0.0;
+  for (var i = 0u; i < directional.count; i++) {
+    let light = directional.lights[i];
+    if (light.shadowed == 0u) { continue; }
+    let e = max(dot(n, normalize(light.direction)), 0.0) * brightest(light.color);
+    total += e;
+    lit += e * directional_shadow(p, n, view_depth, in.clip.xy);
+  }
+  let cluster = cluster_of(in.clip, view_depth);
+  // Baseline (0064): the cluster's bits; keep the body in step with the loop below.
+  @if(BASELINE) if (cluster >= 0) {
+    var mask = cluster_bits[cluster];
+    var index = 0u;
+    while (next_light(&mask, &index)) {
+      let light = lights[index];
+      if (light.shadow == NO_SHADOW) { continue; }
+      let to_light = light.position - p;
+      let d2 = max(dot(to_light, to_light), 1e-4);
+      let d = sqrt(d2);
+      let l = to_light / d;
+      var attenuation = light_falloff(light, d, d2);
+      if (light.kind == LIGHT_SPOT) {
+        let spot = clamp(dot(-l, light.direction) * light.spot_scale + light.spot_offset, 0.0, 1.0);
+        attenuation *= spot * spot;
+      }
+      let e = max(dot(n, l), 0.0) * attenuation * brightest(light.color);
+      if (e <= 0.0) { continue; }
+      var shadow = 1.0;
+      if (light.kind == LIGHT_SPOT) {
+        shadow = spot_shadow(light.shadow, p, n, light.position, light.shadow_bias, light.shadow_normal_bias, light.shadow_softness, in.clip.xy);
+      } else {
+        shadow = point_shadow(light.shadow, p, n, light.shadow_bias, light.shadow_normal_bias, light.shadow_softness, in.clip.xy);
+      }
+      total += e;
+      lit += e * shadow;
+    }
+  }
+  @if(!BASELINE) if (cluster >= 0) {
+    let count = clusters[cluster];
+    let base = CLUSTER_COUNT + u32(cluster) * MAX_PER_CLUSTER;
+    for (var k = 0u; k < count; k++) {
+      let light = lights[clusters[base + k]];
+      if (light.shadow == NO_SHADOW) { continue; }
+      let to_light = light.position - p;
+      let d2 = max(dot(to_light, to_light), 1e-4);
+      let d = sqrt(d2);
+      let l = to_light / d;
+      var attenuation = light_falloff(light, d, d2);
+      if (light.kind == LIGHT_SPOT) {
+        let spot = clamp(dot(-l, light.direction) * light.spot_scale + light.spot_offset, 0.0, 1.0);
+        attenuation *= spot * spot;
+      }
+      let e = max(dot(n, l), 0.0) * attenuation * brightest(light.color);
+      if (e <= 0.0) { continue; }
+      var shadow = 1.0;
+      if (light.kind == LIGHT_SPOT) {
+        shadow = spot_shadow(light.shadow, p, n, light.position, light.shadow_bias, light.shadow_normal_bias, light.shadow_softness, in.clip.xy);
+      } else {
+        shadow = point_shadow(light.shadow, p, n, light.shadow_bias, light.shadow_normal_bias, light.shadow_softness, in.clip.xy);
+      }
+      total += e;
+      lit += e * shadow;
+    }
+  }
+  return select(1.0, lit / total, total > 0.0);
+}`,
+  "shard::material::shadow_catcher": `
+import shard::pbr::types::VertexOutput;
+import shard::pbr::catcher::shadow_visibility;
+import material::shadow_catcher::ShadowCatcher;
+
+/** No color; alpha opacity \xD7 (1 \u2212 visibility) over every shadow-casting light. */
+override fn shade(in: VertexOutput) -> vec4f {
+  return vec4f(0.0, 0.0, 0.0, ShadowCatcher.opacity * (1.0 - shadow_visibility(in)));
+}`
+};
+const ShadowCatcher = defineMaterial("render/ShadowCatcher", {
+  extends: "none",
+  blend: "premultiplied",
+  fields: {
+    opacity: t.f32({
+      default: 0.6,
+      min: 0,
+      max: 1,
+      description: "Alpha of full shadow. Partial shadow (penumbra, one of two lights) is less."
+    })
+  },
+  shader: "shard::material::shadow_catcher",
+  description: "Invisible except for the shadows it receives: under a camera clearing to alpha 0 they fall on the page (a dice tray floor). Give its mesh NotShadowCaster."
+});
+const shadowCatcherPlugin = definePlugin({
+  name: "render/shadow-catcher",
+  dependencies: ["render/forward"],
+  provides: [ShadowCatcher],
+  build() {
+  },
+  ready(app) {
+    registerShaders(app.world.resource(Shaders), SHADOW_CATCHER_SHADERS);
+  }
+});
+export {
+  SHADOW_CATCHER_SHADERS,
+  ShadowCatcher,
+  shadowCatcherPlugin
+};

package/dist/shadows.d.ts

@@ -1,7 +1,7 @@
 import { type World } from '@aethervtt/shard-core';
 import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
 import type { NodeContext } from './graph.js';
-import { type DrawList } from './instances.js';
+import { type DrawList, type InstanceStore } from './instances.js';
 import { type LightRecord, type LightStore } from './lights.js';
 import { type MaterialPipelines } from './material-pipelines.js';
 import type { CameraData } from './view.js';
@@ -15,10 +15,28 @@ export declare function pointTanHalf(size: number): number;
 export interface ShadowViewDraw {
     viewProj: Float32Array;
     frustum: Float32Array;
+    /** What casters are culled against: the frustum, but open toward the light for cascades. */
+    cullPlanes: Float32Array;
     draws: DrawList;
     /** Dynamic offset of this view's matrix in the frame's shadow uniforms. */
     offset: number;
+    /** Whether its layer holds a complete draw (0055: cached shadows keep it). */
+    drawn: boolean;
+    /** The matrix and `InstanceStore.shadowEpoch` it was drawn with. */
+    drawnViewProj: Float32Array;
+    drawnEpoch: number;
+    /** Set by the queue: draw it this frame. */
+    redraw: boolean;
 }
+/**
+ * Whether a shadow view must draw this frame (0055). Views of `shadowUpdate: 'always'` lights
+ * always do. A cached view draws when its layer isn't complete, its matrix changed (the light or
+ * the cascade's fit moved), what casts shadows changed (`shadowEpoch`), poses deform, or a
+ * caster inside its cull planes moved.
+ */
+export declare function shadowRedraw(view: ShadowViewDraw, cached: boolean, store: InstanceStore): boolean;
+/** Records that a shadow view's layer now holds a complete draw of this frame's state. */
+export declare function markShadowDrawn(view: ShadowViewDraw, store: InstanceStore): void;
 /** A camera's cascades: fitted each frame, one depth layer each. */
 export declare class Cascades {
     count: number;
@@ -98,11 +116,17 @@ export declare class ShadowPassUniforms {
     bindGroup: GPUBindGroup | undefined;
     private bound;
     private readonly gpu;
+    /** What the buffer holds, so unchanged shadow views write nothing (0055). */
+    private sent;
+    private sentCount;
+    private sentVersion;
+    private sentGeneration;
     constructor(gpu: GpuContext);
     reset(): void;
     /** Adds a view matrix; returns its dynamic offset. */
     push(viewProj: Float32Array): number;
     upload(layout: GPUBindGroupLayout, globals: GpuBuffer): void;
+    private unchanged;
 }
 export declare function shadowViewLayout(gpu: GpuContext): GPUBindGroupLayout;
 /**

package/dist/shadows.js

@@ -2,7 +2,11 @@ import { defineResource, frustum, mat4 } from "@aethervtt/shard-core";
 import { GpuBuffer } from "@aethervtt/shard-gpu";
 import { Culler } from "./culling.js";
 import { GpuAssetsResource } from "./gpu-assets.js";
-import { createDrawList, InstanceFlags, Instances } from "./instances.js";
+import {
+  createDrawList,
+  InstanceFlags,
+  Instances
+} from "./instances.js";
 import { setShadowIndex } from "./lights.js";
 import {
   materialVariant,
@@ -10,6 +14,7 @@ import {
   variantBlend,
   variantCull
 } from "./material-pipelines.js";
+import { bindingDimension } from "./tier.js";
 const MAX_CASCADES = 4;
 const MAX_SHADOWED_SPOTS = 8;
 const MAX_SHADOWED_POINTS = 4;
@@ -31,7 +36,30 @@ function pointTanHalf(size) {
 }
 const VIEW_STRIDE = 256;
 function shadowView() {
-  return { viewProj: mat4.create(), frustum: frustum.create(), draws: createDrawList(), offset: 0 };
+  return {
+    viewProj: mat4.create(),
+    frustum: frustum.create(),
+    cullPlanes: frustum.create(),
+    draws: createDrawList(),
+    offset: 0,
+    drawn: false,
+    drawnViewProj: mat4.create(),
+    drawnEpoch: -1,
+    redraw: true
+  };
+}
+function shadowRedraw(view, cached, store) {
+  if (!cached || !view.drawn || view.drawnEpoch !== store.shadowEpoch || store.deforming)
+    return true;
+  const a = view.viewProj;
+  const b = view.drawnViewProj;
+  for (let i = 0; i < 16; i++) if (a[i] !== b[i]) return true;
+  return store.movedCasterIn(view.cullPlanes);
+}
+function markShadowDrawn(view, store) {
+  view.drawn = true;
+  view.drawnViewProj.set(view.viewProj);
+  view.drawnEpoch = store.shadowEpoch;
 }
 class Cascades {
   count = 0;
@@ -46,11 +74,13 @@ class Cascades {
   ensureTexture(gpu, size, label) {
     if (!this.texture || this.size !== size || this.generation !== gpu.generation) {
       this.texture?.destroy();
+      for (const view of this.views) view.drawn = false;
       this.texture = gpu.device.createTexture({
         label: `${label}/cascades`,
         size: [size, size, MAX_CASCADES],
         format: "depth32float",
-        usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC
+        usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC,
+        ...bindingDimension(gpu, "2d-array")
       });
       this.size = size;
       this.generation = gpu.generation;
@@ -160,6 +190,7 @@ function fitCascades(cascades, cam, sun, size, cull) {
     set(4, -basis[6], -basis[7], -basis[8], lz + radius);
     set(5, 0, 0, 0, 1);
     const view = cascades.views[i];
+    view.cullPlanes.set(p);
     const any = cull(view, p, scratchBox);
     let zNear = lz - radius;
     if (any) {
@@ -228,15 +259,18 @@ class LocalShadows {
       label,
       size: [size, size, layers],
       format: "depth32float",
-      usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC
+      usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC,
+      ...bindingDimension(gpu, "2d-array")
     });
     if (fresh || !this.spotTexture || spotLayers > this.spotLayers) {
       this.spotTexture?.destroy();
+      for (const view of this.spotViews) view.drawn = false;
       this.spotLayers = Math.max(spotLayers, fresh ? 1 : this.spotLayers);
       this.spotTexture = make("shadows/spots", this.spotLayers);
     }
     if (fresh || !this.pointTexture || pointLayers > this.pointLayers) {
       this.pointTexture?.destroy();
+      for (const view of this.pointViews) view.drawn = false;
       this.pointLayers = Math.max(pointLayers, fresh ? 6 : this.pointLayers);
       this.pointTexture = make("shadows/points", this.pointLayers);
     }
@@ -317,6 +351,7 @@ function fitLocalShadows(shadows, size) {
     const view = shadows.spotViews[i];
     mat4.multiply(view.viewProj, scratchProj, scratchView);
     frustum.fromViewProjection(view.frustum, view.viewProj);
+    view.cullPlanes.set(view.frustum);
     shadows.spotParams[i * 4] = tanHalf2;
     shadows.spotParams[i * 4 + 1] = near;
   }
@@ -335,6 +370,7 @@ function fitLocalShadows(shadows, size) {
       const view = shadows.pointViews[i * 6 + f];
       mat4.multiply(view.viewProj, scratchProj, scratchView);
       frustum.fromViewProjection(view.frustum, view.viewProj);
+      view.cullPlanes.set(view.frustum);
     }
   }
 }
@@ -377,6 +413,11 @@ class ShadowPassUniforms {
   bindGroup;
   bound = "";
   gpu;
+  /** What the buffer holds, so unchanged shadow views write nothing (0055). */
+  sent = new Float32Array(0);
+  sentCount = 0;
+  sentVersion = -1;
+  sentGeneration = -1;
   constructor(gpu) {
     this.gpu = gpu;
     this.buffer = new GpuBuffer(gpu, {
@@ -400,7 +441,15 @@ class ShadowPassUniforms {
     return this.count++ * VIEW_STRIDE;
   }
   upload(layout, globals) {
-    if (this.count > 0) this.buffer.write(this.data, 0, 0, this.count * VIEW_STRIDE / 4);
+    const floats = this.count * VIEW_STRIDE / 4;
+    if (this.count > 0 && !this.unchanged(floats)) {
+      this.buffer.write(this.data, 0, 0, floats);
+      if (this.sent.length < this.data.length) this.sent = new Float32Array(this.data.length);
+      this.sent.set(this.data.subarray(0, floats));
+      this.sentCount = this.count;
+      this.sentVersion = this.buffer.version;
+      this.sentGeneration = this.gpu.generation;
+    }
     const key = `${this.buffer.version}/${globals.version}/${this.gpu.generation}`;
     if (!this.bindGroup || this.bound !== key) {
       this.bindGroup = this.gpu.device.createBindGroup({
@@ -414,6 +463,15 @@ class ShadowPassUniforms {
       this.bound = key;
     }
   }
+  unchanged(floats) {
+    if (this.sentCount < this.count) return false;
+    if (this.sentVersion !== this.buffer.version || this.sentGeneration !== this.gpu.generation)
+      return false;
+    const data = this.data;
+    const sent = this.sent;
+    for (let i = 0; i < floats; i++) if (data[i] !== sent[i]) return false;
+    return true;
+  }
 }
 function shadowViewLayout(gpu) {
   return gpu.layouts.bindGroupLayout({
@@ -472,7 +530,8 @@ function drawShadowCasters(ctx, target, view, offset, uniforms, pipelines, shado
   const draws = view.draws;
   for (let d = 0; d < draws.length; d++) {
     const item = draws.items[d];
-    const material = item.batch.material;
+    const fallback = pipelines.failing(item.batch.material.type);
+    const material = fallback ? pipelines.proxy(item.batch.material) : item.batch.material;
     const type = material.type;
     const variant = materialVariant(material);
     const masked = type.standard && variantBlend(variant) === "mask";
@@ -481,21 +540,38 @@ function drawShadowCasters(ctx, target, view, offset, uniforms, pipelines, shado
     if (!pipeline) {
       const module = pipelines.module(world, gpu, type, 8, "shard::pbr::shadow", void 0);
       if (!module) {
-        gpu.pipelines.skipped++;
+        if (!fallback && pipelines.failing(type)) d--;
+        else gpu.pipelines.skipped++;
+        continue;
+      }
+      pipeline = pipelines.create(
+        gpu,
+        key,
+        {
+          label: `shadow/${type.name}/${masked ? "mask" : "opaque"}/${variantCull(variant)}`,
+          layout: gpu.layouts.pipelineLayout({
+            label: `shadow/${type.name}`,
+            bindGroupLayouts: [shadowView2, assets.layoutOf(type), store.layout]
+          }),
+          vertex: { module, entryPoint: "vs", buffers: SHADOW_BUFFERS },
+          fragment: masked ? { module, entryPoint: "fs_mask", targets: [] } : void 0,
+          primitive: {
+            topology: "triangle-list",
+            cullMode: variantCull(variant),
+            frontFace: "ccw"
+          },
+          depthStencil: {
+            format: "depth32float",
+            depthWriteEnabled: true,
+            depthCompare: "greater"
+          }
+        },
+        type
+      );
+      if (!pipeline) {
+        if (!fallback && pipelines.failing(type)) d--;
         continue;
       }
-      pipeline = pipelines.create(gpu, key, {
-        label: `shadow/${type.name}/${masked ? "mask" : "opaque"}/${variantCull(variant)}`,
-        layout: gpu.layouts.pipelineLayout({
-          label: `shadow/${type.name}`,
-          bindGroupLayouts: [shadowView2, assets.layoutOf(type), store.layout]
-        }),
-        vertex: { module, entryPoint: "vs", buffers: SHADOW_BUFFERS },
-        fragment: masked ? { module, entryPoint: "fs_mask", targets: [] } : void 0,
-        primitive: { topology: "triangle-list", cullMode: variantCull(variant), frontFace: "ccw" },
-        depthStencil: { format: "depth32float", depthWriteEnabled: true, depthCompare: "greater" }
-      });
-      if (!pipeline) continue;
     }
     const mat = assets.material(world, material);
     if (!mat?.bindGroup) continue;
@@ -555,8 +631,10 @@ export {
   drawShadowCasters,
   fitCascades,
   fitLocalShadows,
+  markShadowDrawn,
   packShadowData,
   pointTanHalf,
+  shadowRedraw,
   shadowViewLayout,
   sliceSphere
 };

package/dist/standard-fields.d.ts

@@ -15,6 +15,7 @@ export declare const STANDARD_FIELDS: {
     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">;

package/dist/standard-fields.js

@@ -42,6 +42,11 @@ const STANDARD_FIELDS = {
     description: "Emitted luminance. 0 = not emissive."
   }),
   doubleSided: t.bool({ description: "Draw back faces too (no culling)." }),
+  deferUntilReady: t.bool({
+    // The asset layer reads it; shaders don't.
+    gpu: false,
+    description: "Baseline tier (0064): while a texture it binds waits for a copy in its slot's color space, skip its draws instead of showing the slot's loading fallback."
+  }),
   alphaMode: t.enum(["opaque", "mask", "alpha", "additive", "premultiplied"], {
     description: "opaque ignores alpha; mask discards pixels below alphaCutoff; alpha blends (transparent, drawn after opaque, sorted back to front); additive adds light (glows); premultiplied expects color already multiplied by alpha."
   }),

package/dist/standard.js

@@ -1,5 +1,6 @@
 import { definePlugin } from "@aethervtt/shard-runtime";
 import { atmospherePlugin } from "./atmosphere-plugin.js";
+import { cutawayPlugin } from "./cutaway-plugin.js";
 import { deferredPlugin } from "./deferred-plugin.js";
 import { renderDescribePlugin } from "./describe-plugin.js";
 import { dynamicResolutionPlugin } from "./dynamic-resolution.js";
@@ -7,10 +8,15 @@ import { environmentPlugin } from "./environment-plugin.js";
 import { forwardCorePlugin } from "./forward.js";
 import { fxaaPlugin } from "./fxaa.js";
 import { gizmosPlugin } from "./gizmos-plugin.js";
+import { interiorPlugin } from "./interior-plugin.js";
+import { lensPlugin } from "./lens-plugin.js";
+import { outlinePlugin } from "./outline-plugin.js";
 import { pickingPlugin } from "./picking-plugin.js";
 import { pixelPerfectPlugin } from "./pixel-perfect-plugin.js";
 import { postPlugin } from "./post-plugin.js";
+import { shadowCatcherPlugin } from "./shadow-catcher.js";
 import { skinningPlugin } from "./skinning-plugin.js";
+import { viewVisibilityPlugin } from "./view-visibility-plugin.js";
 function forwardPlugin(options = {}) {
   return definePlugin({
     name: "render/standard",
@@ -26,6 +32,12 @@ function forwardPlugin(options = {}) {
         deferredPlugin,
         skinningPlugin,
         pixelPerfectPlugin,
+        lensPlugin,
+        outlinePlugin,
+        cutawayPlugin,
+        viewVisibilityPlugin,
+        interiorPlugin,
+        shadowCatcherPlugin,
         dynamicResolutionPlugin,
         renderDescribePlugin
       );

package/dist/stats.d.ts

@@ -1,3 +1,4 @@
+import { type GpuUploads, type UploadCategory } from '@aethervtt/shard-gpu';
 export interface ViewStats {
     visible: number;
     culled: number;
@@ -8,7 +9,50 @@ export interface ViewStats {
     /** Pipeline changes in the opaque pass (sorting keeps these near the number of material types). */
     pipelineSwitches?: number;
 }
-export declare const RenderStats: import("@aethervtt/shard-core").ResourceDef<Map<string, ViewStats>>;
+/** What one frame (or a window of frames) wrote to the GPU and rebuilt (0055). */
+export interface FrameRecord {
+    /** Bytes written, by what they were for. */
+    bytes: Record<UploadCategory, number>;
+    /** Scene data: every byte but `view` (camera and per-frame uniforms). */
+    sceneBytes: number;
+    /** Buffers and textures created. */
+    created: number;
+    /** Structure chunks rebuilt (0055). */
+    chunksRebuilt: number;
+    /** Meshes uploaded to the GPU: new ones, and ones whose data changed. */
+    meshesRebuilt: number;
+    /** Shadow maps (cascades and local shadow views) drawn. */
+    shadowMapsRendered: number;
+}
+/** Counts a system adds to during a frame; they land in `lastFrame` when the frame is submitted. */
+export interface FrameCounts {
+    chunksRebuilt: number;
+    meshesRebuilt: number;
+    shadowMapsRendered: number;
+}
+/** Frames `RenderStatsMap.recent` sums over. */
+export declare const RECENT_FRAMES = 60;
+/**
+ * Per-view counts from the last frame (a Map by view name), plus what the last frame wrote to the
+ * GPU and rebuilt (`lastFrame`) and the sum over the last 60 rendered frames (`recent`).
+ */
+export declare class RenderStatsMap extends Map<string, ViewStats> {
+    readonly lastFrame: FrameRecord;
+    readonly recent: FrameRecord;
+    /** Counted during the frame being built. */
+    readonly current: FrameCounts;
+    /** Frames recorded. */
+    frames: number;
+    private readonly ring;
+    private readonly row;
+    private readonly seen;
+    /**
+     * Closes a frame: `uploads` is the owner's running total (`gpu.uploads(owner)`); the difference
+     * since the last call is this frame's. Allocates nothing.
+     */
+    endFrame(uploads: GpuUploads | undefined): void;
+}
+export declare const RenderStats: import("@aethervtt/shard-core").ResourceDef<RenderStatsMap>;
 export interface GpuMemoryData {
     /** Textures uploaded by the forward renderer. */
     textures: number;

package/dist/stats.js

@@ -1,7 +1,93 @@
 import { defineResource } from "@aethervtt/shard-core";
+import {
+  UPLOAD_CATEGORIES,
+  Upload
+} from "@aethervtt/shard-gpu";
+const RECENT_FRAMES = 60;
+const FIELDS = UPLOAD_CATEGORIES.length + 4;
+function frameRecord() {
+  const bytes = {};
+  for (const c of UPLOAD_CATEGORIES) bytes[c] = 0;
+  return {
+    bytes,
+    sceneBytes: 0,
+    created: 0,
+    chunksRebuilt: 0,
+    meshesRebuilt: 0,
+    shadowMapsRendered: 0
+  };
+}
+class RenderStatsMap extends Map {
+  lastFrame = frameRecord();
+  recent = frameRecord();
+  /** Counted during the frame being built. */
+  current = { chunksRebuilt: 0, meshesRebuilt: 0, shadowMapsRendered: 0 };
+  /** Frames recorded. */
+  frames = 0;
+  ring = new Float64Array(RECENT_FRAMES * FIELDS);
+  row = new Float64Array(FIELDS);
+  seen = new Float64Array(UPLOAD_CATEGORIES.length + 1);
+  /**
+   * Closes a frame: `uploads` is the owner's running total (`gpu.uploads(owner)`); the difference
+   * since the last call is this frame's. Allocates nothing.
+   */
+  endFrame(uploads) {
+    const row = this.row;
+    const seen = this.seen;
+    const n = UPLOAD_CATEGORIES.length;
+    for (let i = 0; i < n; i++) {
+      const total = uploads ? uploads.bytes[i] : seen[i];
+      row[i] = total - seen[i];
+      seen[i] = total;
+    }
+    const created = uploads ? uploads.created : seen[n];
+    row[n] = created - seen[n];
+    seen[n] = created;
+    const cur = this.current;
+    row[n + 1] = cur.chunksRebuilt;
+    row[n + 2] = cur.meshesRebuilt;
+    row[n + 3] = cur.shadowMapsRendered;
+    cur.chunksRebuilt = cur.meshesRebuilt = cur.shadowMapsRendered = 0;
+    const ring = this.ring;
+    const slot = this.frames % RECENT_FRAMES * FIELDS;
+    this.frames++;
+    const last = this.lastFrame;
+    const recent = this.recent;
+    let lastScene = 0;
+    let recentScene = 0;
+    for (let i = 0; i < FIELDS; i++) {
+      const sum = recentField(recent, i) - ring[slot + i] + row[i];
+      ring[slot + i] = row[i];
+      setField(last, i, row[i]);
+      setField(recent, i, sum);
+      if (i < n && i !== Upload.view) {
+        lastScene += row[i];
+        recentScene += sum;
+      }
+    }
+    last.sceneBytes = lastScene;
+    recent.sceneBytes = recentScene;
+  }
+}
+function recentField(r, i) {
+  const n = UPLOAD_CATEGORIES.length;
+  if (i < n) return r.bytes[UPLOAD_CATEGORIES[i]];
+  if (i === n) return r.created;
+  if (i === n + 1) return r.chunksRebuilt;
+  if (i === n + 2) return r.meshesRebuilt;
+  return r.shadowMapsRendered;
+}
+function setField(r, i, v) {
+  const n = UPLOAD_CATEGORIES.length;
+  if (i < n) r.bytes[UPLOAD_CATEGORIES[i]] = v;
+  else if (i === n) r.created = v;
+  else if (i === n + 1) r.chunksRebuilt = v;
+  else if (i === n + 2) r.meshesRebuilt = v;
+  else r.shadowMapsRendered = v;
+}
 const RenderStats = defineResource("render/Stats", {
-  description: "Per-view counts from the last frame: visible, culled, hidden, pending, draw calls.",
-  init: () => /* @__PURE__ */ new Map()
+  description: "Per-view counts from the last frame (visible, culled, hidden, pending, draw calls), and what the last frame and the last 60 wrote to the GPU and rebuilt.",
+  init: () => new RenderStatsMap()
 });
 const GpuMemory = defineResource("render/GpuMemory", {
   description: "GPU memory used by uploaded textures.",
@@ -13,6 +99,8 @@ const RenderCounters = defineResource("render/Counters", {
 });
 export {
   GpuMemory,
+  RECENT_FRAMES,
   RenderCounters,
-  RenderStats
+  RenderStats,
+  RenderStatsMap
 };