@aethervtt/shard-render 0.0.1

package/dist/stats.js

@@ -0,0 +1,18 @@
+import { defineResource } from "@aethervtt/shard-core";
+const RenderStats = defineResource("render/Stats", {
+  description: "Per-view counts from the last frame: visible, culled, hidden, pending, draw calls.",
+  init: () => /* @__PURE__ */ new Map()
+});
+const GpuMemory = defineResource("render/GpuMemory", {
+  description: "GPU memory used by uploaded textures.",
+  init: () => ({ textures: 0, textureBytes: 0 })
+});
+const RenderCounters = defineResource("render/Counters", {
+  description: "Running totals since start: TAA history resets and floating-origin shifts followed.",
+  init: () => ({ taaResets: 0, originShifts: 0 })
+});
+export {
+  GpuMemory,
+  RenderCounters,
+  RenderStats
+};

package/dist/target.d.ts

@@ -0,0 +1,55 @@
+import type { GpuContext } from '@aethervtt/shard-gpu';
+/** Where a view renders: the window's swapchain or an offscreen texture. */
+export interface RenderTarget {
+    readonly label: string;
+    readonly format: GPUTextureFormat;
+    readonly width: number;
+    readonly height: number;
+    /** Cameras showing on it render at the RenderScale and are upscaled (0051). The window does. */
+    readonly renderScale?: boolean;
+    /**
+     * Its pixels per CSS pixel (the display's devicePixelRatio for the window; default 1). Screen
+     * densities in "pixels" (terrain LOD, the MSAA default) are measured in CSS pixels (0051).
+     */
+    readonly pixelRatio?: number;
+    /** The texture to render into this frame. */
+    texture(): GPUTexture;
+}
+/** The canvas swapchain. Resizes with the canvas. */
+export declare class WindowTarget implements RenderTarget {
+    readonly label = "window";
+    readonly renderScale = true;
+    private readonly gpu;
+    constructor(gpu: GpuContext);
+    get format(): GPUTextureFormat;
+    get width(): number;
+    get pixelRatio(): number;
+    get height(): number;
+    texture(): GPUTexture;
+}
+export interface OffscreenTargetOptions {
+    label: string;
+    width: number;
+    height: number;
+    format?: GPUTextureFormat;
+    /** Follow the RenderScale like the window (0051). Default false. */
+    renderScale?: boolean;
+    /** Pixels per CSS pixel, for a target standing in for a high-density display. Default 1. */
+    pixelRatio?: number;
+}
+/** A texture render target: headless runs, screenshots, render-to-texture, second cameras. */
+export declare class OffscreenTarget implements RenderTarget {
+    readonly label: string;
+    readonly format: GPUTextureFormat;
+    readonly renderScale: boolean;
+    readonly pixelRatio: number;
+    width: number;
+    height: number;
+    private current;
+    private generation;
+    private readonly gpu;
+    constructor(gpu: GpuContext, options: OffscreenTargetOptions);
+    resize(width: number, height: number): void;
+    texture(): GPUTexture;
+    destroy(): void;
+}

package/dist/target.js

@@ -0,0 +1,70 @@
+class WindowTarget {
+  label = "window";
+  renderScale = true;
+  gpu;
+  constructor(gpu) {
+    this.gpu = gpu;
+  }
+  get format() {
+    return this.gpu.format;
+  }
+  get width() {
+    return this.gpu.canvas?.width ?? 1;
+  }
+  get pixelRatio() {
+    return this.gpu.pixelRatio;
+  }
+  get height() {
+    return this.gpu.canvas?.height ?? 1;
+  }
+  texture() {
+    this.gpu.resize();
+    return this.gpu.context.getCurrentTexture();
+  }
+}
+class OffscreenTarget {
+  label;
+  format;
+  renderScale;
+  pixelRatio;
+  width;
+  height;
+  current;
+  generation = -1;
+  gpu;
+  constructor(gpu, options) {
+    this.gpu = gpu;
+    this.label = options.label;
+    this.width = options.width;
+    this.height = options.height;
+    this.format = options.format ?? "rgba8unorm";
+    this.renderScale = options.renderScale ?? false;
+    this.pixelRatio = options.pixelRatio ?? 1;
+  }
+  resize(width, height) {
+    if (width === this.width && height === this.height) return;
+    this.width = width;
+    this.height = height;
+    this.current?.destroy();
+    this.current = void 0;
+  }
+  texture() {
+    if (!this.current || this.generation !== this.gpu.generation) {
+      this.generation = this.gpu.generation;
+      this.current = this.gpu.device.createTexture({
+        label: this.label,
+        size: [this.width, this.height],
+        format: this.format,
+        usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_SRC
+      });
+    }
+    return this.current;
+  }
+  destroy() {
+    this.current?.destroy();
+  }
+}
+export {
+  OffscreenTarget,
+  WindowTarget
+};

package/dist/testing.d.ts

@@ -0,0 +1,34 @@
+import type { App } from '@aethervtt/shard-runtime';
+import type { CapturedImage } from './graph.js';
+/** Renders frames until shaders and pipelines are compiled and nothing is skipped. */
+export declare function settle(app: App, frames?: number): Promise<void>;
+/** Settles, then captures a view. */
+export declare function renderView(app: App, view: string): Promise<CapturedImage>;
+export declare function pixel(image: {
+    width: number;
+    data: ArrayLike<number>;
+}, x: number, y: number): number[];
+/** RGBA8 → PNG bytes (sync, zlib), for debugging output. */
+export declare function pngBytes(data: Uint8Array, width: number, height: number): Uint8Array;
+/** Expected | actual | difference × 4, scaled up by `scale` (nearest). */
+export declare function comparePng(expected: Uint8Array, image: {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}, scale: number): Uint8Array;
+export interface GoldenResult {
+    /** Mean absolute difference per channel, in 8-bit levels. */
+    mean: number;
+    max: number;
+    /** Whether the golden was just written (first run or SHARD_UPDATE_GOLDEN). */
+    written: boolean;
+}
+/**
+ * Compares an image with `<dir>/__golden__/<name>.rgba`. Writes it when missing (or when
+ * SHARD_UPDATE_GOLDEN is set), so a new golden appears on the first run.
+ */
+export declare function compareGolden(dir: string, name: string, image: {
+    width: number;
+    height: number;
+    data: Uint8Array;
+}): GoldenResult;

package/dist/testing.js

@@ -0,0 +1,126 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { deflateSync } from "node:zlib";
+import { Culler } from "./culling.js";
+import { captureView, Gpu, Shaders } from "./plugin.js";
+async function settle(app, frames = 40) {
+  const gpu = app.world.resource(Gpu);
+  for (let i = 0; i < frames; i++) {
+    app.update(1 / 60);
+    await app.world.resource(Shaders).whenIdle();
+    await gpu.pipelines.whenIdle();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    if (i >= 3 && gpu.pipelines.skipped === 0 && gpu.pipelines.pending === 0) {
+      await app.world.tryResource(Culler)?.whenIdle();
+      app.update(1 / 60);
+      await gpu.pipelines.whenIdle();
+      if (gpu.pipelines.skipped === 0) return;
+    }
+  }
+}
+async function renderView(app, view) {
+  await settle(app);
+  const shot = captureView(app.world, view);
+  app.update(1 / 60);
+  return shot;
+}
+function pixel(image, x, y) {
+  const o = (y * image.width + x) * 4;
+  return [image.data[o], image.data[o + 1], image.data[o + 2], image.data[o + 3]];
+}
+const CRC = new Uint32Array(256).map((_, n) => {
+  let c = n;
+  for (let k = 0; k < 8; k++) c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+  return c >>> 0;
+});
+function pngBytes(data, width, height) {
+  const raw = Buffer.alloc((width * 4 + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (width * 4 + 1)] = 0;
+    Buffer.from(data.buffer, data.byteOffset + y * width * 4, width * 4).copy(
+      raw,
+      y * (width * 4 + 1) + 1
+    );
+  }
+  const crc = (b) => {
+    let c = 4294967295;
+    for (const x of b) c = CRC[(c ^ x) & 255] ^ c >>> 8;
+    return (c ^ 4294967295) >>> 0;
+  };
+  const chunk = (type, body) => {
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(body.length);
+    const td = Buffer.concat([Buffer.from(type), body]);
+    const c = Buffer.alloc(4);
+    c.writeUInt32BE(crc(td));
+    return Buffer.concat([len, td, c]);
+  };
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 6;
+  return Buffer.concat([
+    Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]),
+    chunk("IHDR", ihdr),
+    chunk("IDAT", deflateSync(raw)),
+    chunk("IEND", Buffer.alloc(0))
+  ]);
+}
+function comparePng(expected, image, scale) {
+  const { width, height } = image;
+  const gap = 2;
+  const W = (width * 3 + gap * 2) * scale;
+  const H = height * scale;
+  const out = new Uint8Array(W * H * 4);
+  for (let y = 0; y < H; y++) {
+    for (let x = 0; x < W; x++) {
+      const panel = Math.floor(x / scale / (width + gap));
+      const px = Math.floor(x / scale) - panel * (width + gap);
+      const o = (y * W + x) * 4;
+      out[o + 3] = 255;
+      if (px >= width) continue;
+      const s = (Math.floor(y / scale) * width + px) * 4;
+      for (let c = 0; c < 3; c++) {
+        const e = expected[s + c];
+        const a = image.data[s + c];
+        out[o + c] = panel === 0 ? e : panel === 1 ? a : Math.min(255, Math.abs(e - a) * 4);
+      }
+    }
+  }
+  return pngBytes(out, W, H);
+}
+function compareGolden(dir, name, image) {
+  const file = join(dir, "__golden__", `${name}.rgba`);
+  const out = process.env.SHARD_GOLDEN_OUT;
+  if (out) {
+    mkdirSync(out, { recursive: true });
+    writeFileSync(join(out, `${name}.png`), pngBytes(image.data, image.width, image.height));
+  }
+  if (!existsSync(file) || process.env.SHARD_UPDATE_GOLDEN) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, image.data);
+    return { mean: 0, max: 0, written: true };
+  }
+  const expected = new Uint8Array(readFileSync(file));
+  if (out && expected.length === image.data.length) {
+    writeFileSync(join(out, `${name}.compare.png`), comparePng(expected, image, 4));
+  }
+  if (expected.length !== image.data.length) return { mean: 255, max: 255, written: false };
+  let sum = 0;
+  let max = 0;
+  for (let i = 0; i < expected.length; i++) {
+    const d = Math.abs(expected[i] - image.data[i]);
+    sum += d;
+    if (d > max) max = d;
+  }
+  return { mean: sum / expected.length, max, written: false };
+}
+export {
+  compareGolden,
+  comparePng,
+  pixel,
+  pngBytes,
+  renderView,
+  settle
+};

package/dist/timer.d.ts

@@ -0,0 +1,28 @@
+import { type World } from '@aethervtt/shard-core';
+import type { GpuContext } from '@aethervtt/shard-gpu';
+/**
+ * Per-pass GPU timings with `timestamp-query`. Each render/compute pass writes begin and end
+ * timestamps; results are copied to a small ring of readback buffers and recorded into the profiler
+ * as `gpu:<node>` a frame or two later. Without the feature, everything here is a no-op.
+ */
+export declare class GpuTimer {
+    readonly enabled: boolean;
+    /** The latest frame's GPU span in ms (first pass start to last pass end), once one landed. */
+    frameMs: number;
+    /** Frames measured so far: changes when `frameMs` does. */
+    frameSamples: number;
+    private querySet;
+    private resolveBuffer;
+    private readonly readbacks;
+    private names;
+    private generation;
+    private readonly gpu;
+    constructor(gpu: GpuContext);
+    beginFrame(): void;
+    /** Timestamp writes for the next pass, or undefined when timing is off or full. */
+    allocate(name: string): GPURenderPassTimestampWrites | undefined;
+    private pendingCopy;
+    resolve(encoder: GPUCommandEncoder): void;
+    /** Call after submit. Records timings when the copy lands. */
+    readback(world: World): void;
+}

package/dist/timer.js

@@ -0,0 +1,136 @@
+import { ProfilerResource } 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;
+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;
+  querySet;
+  resolveBuffer;
+  readbacks = [];
+  names = [];
+  generation = -1;
+  gpu;
+  constructor(gpu) {
+    this.gpu = gpu;
+    this.enabled = gpu.features.has("timestamp-query");
+  }
+  beginFrame() {
+    this.names = [];
+    if (!this.enabled || this.generation === this.gpu.generation) return;
+    this.generation = this.gpu.generation;
+    const device = this.gpu.device;
+    this.querySet = device.createQuerySet({
+      label: "gpu-timer",
+      type: "timestamp",
+      count: MAX_PASSES * 2
+    });
+    this.resolveBuffer = device.createBuffer({
+      label: "gpu-timer/resolve",
+      size: MAX_PASSES * 2 * 8,
+      usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC
+    });
+    this.readbacks.length = 0;
+    for (let i = 0; i < READBACK_BUFFERS; i++) {
+      this.readbacks.push({
+        buffer: device.createBuffer({
+          label: `gpu-timer/readback-${i}`,
+          size: MAX_PASSES * 2 * 8,
+          usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
+        }),
+        busy: false,
+        names: []
+      });
+    }
+  }
+  /** Timestamp writes for the next pass, or undefined when timing is off or full. */
+  allocate(name) {
+    if (!this.enabled || !this.querySet || this.names.length >= MAX_PASSES) return void 0;
+    const i = this.names.length;
+    this.names.push(name);
+    return {
+      querySet: this.querySet,
+      beginningOfPassWriteIndex: i * 2,
+      endOfPassWriteIndex: i * 2 + 1
+    };
+  }
+  pendingCopy;
+  resolve(encoder) {
+    this.pendingCopy = void 0;
+    if (!this.enabled || this.names.length === 0) return;
+    const target = this.readbacks.find((r) => !r.busy);
+    if (!target) return;
+    const count = this.names.length * 2;
+    encoder.resolveQuerySet(this.querySet, 0, count, this.resolveBuffer, 0);
+    encoder.copyBufferToBuffer(this.resolveBuffer, 0, target.buffer, 0, count * 8);
+    target.busy = true;
+    target.names = this.names;
+    this.pendingCopy = target;
+  }
+  /** Call after submit. Records timings when the copy lands. */
+  readback(world) {
+    const target = this.pendingCopy;
+    if (!target) return;
+    this.pendingCopy = void 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;
+        let first = 0n;
+        let last = 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;
+          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;
+        }
+        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;
+          let b = 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 || !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 (last > first) {
+          this.frameMs = Number(last - first) / 1e6;
+          this.frameSamples++;
+          profiler?.record("gpu:frame", this.frameMs);
+        }
+        target.buffer.unmap();
+        target.busy = false;
+      },
+      () => {
+        target.busy = false;
+      }
+    );
+  }
+}
+export {
+  GpuTimer
+};

package/dist/view.d.ts

@@ -0,0 +1,117 @@
+import { type Entity } from '@aethervtt/shard-core';
+import type { RenderView } from './graph.js';
+import { type DrawList } from './instances.js';
+import { type PixelPerfectLayout } from './pixel-perfect.js';
+import { type PostSettings } from './post.js';
+export declare const TONEMAP_CURVES: readonly ['aces', 'agx', 'pbr-neutral', 'reinhard', 'none'];
+export type TonemapCurve = (typeof TONEMAP_CURVES)[number];
+/** The curve for cameras without a Tonemapping component. */
+export declare const DEFAULT_CURVE: TonemapCurve;
+export declare const Tonemapping: import("@aethervtt/shard-core").ComponentDef<{
+    readonly curve: import("@aethervtt/shard-core").FieldType<"aces" | "agx" | "none" | "pbr-neutral" | "reinhard", "u8">;
+    readonly dither: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+}>;
+export declare const RenderPath: import("@aethervtt/shard-core").ComponentDef<{
+    readonly mode: import("@aethervtt/shard-core").FieldType<"deferred" | "forward", "u8">;
+}>;
+/** Present when deferredPlugin is installed: cameras with RenderPath deferred use the G-buffer. */
+export declare const DeferredPath: import("@aethervtt/shard-core").ResourceDef<{
+    installed: true;
+}>;
+/** Camera data a view carries for the passes that draw it. */
+export interface CameraData {
+    entity: Entity;
+    /** World → view. */
+    view: Float32Array;
+    proj: Float32Array;
+    viewProj: Float32Array;
+    invViewProj: Float32Array;
+    /** viewProj without the TAA jitter (motion vectors). Same as viewProj without TAA. */
+    viewProjNoJitter: Float32Array;
+    /** Last frame's unjittered viewProj (motion vectors, TAA). */
+    prevViewProj: Float32Array;
+    position: Float32Array;
+    /** Unit vector the camera looks along (-Z of its transform). */
+    forward: Float32Array;
+    frustum: Float32Array;
+    orthographic: boolean;
+    near: number;
+    /** Far plane for orthographic; 0 for perspective (infinite). */
+    far: number;
+    fovY: number;
+    orthoHeight: number;
+    aspect: number;
+    /** Render resolution (0051): the size of the view's scene textures. */
+    width: number;
+    height: number;
+    /** Display resolution: the target's size, which screen overlays (UI, screen text) draw at. */
+    displayWidth: number;
+    displayHeight: number;
+    /**
+     * The target's pixels per CSS pixel (devicePixelRatio on the window, else 1). Pixel thresholds
+     * meant for the eye (terrain LOD) use `displayHeight / pixelRatio`: the same on every display
+     * and at every render scale.
+     */
+    pixelRatio: number;
+    /** Scene luminance → pre-exposed HDR. */
+    exposure: number;
+    ev100: number;
+    /** Linear clear color, as displayed before the tonemap curve. */
+    clear: GPUColor;
+    msaa: number;
+    curve: number;
+    dither: boolean;
+    /** Culled draws of this camera, rebuilt each frame. */
+    draws: DrawList;
+    /** Blended draws, back to front. */
+    transparent: DrawList;
+    /** Deferred views: opaque draws the G-buffer can't take (custom lighting), drawn forward. */
+    forwardOnly: DrawList;
+    /** Renders through the G-buffer (RenderPath deferred). */
+    deferred: boolean;
+    /** G-buffer channel to show for a capture (-1: none), also forcing a G-buffer in forward views. */
+    gbufferDebug: number;
+    /** LOD level per instance slot for this camera (CPU culling), and the slot capacity it needs. */
+    lodState: Uint8Array;
+    lodCapacity: number;
+    /** A frozen culling frustum and eye (debug view 'culling'): culling stays put as you fly. */
+    frozenFrustum: Float32Array | undefined;
+    frozenPosition: Float32Array | undefined;
+    /** Frames this camera has rendered. */
+    frames: number;
+    /** Debug view: 0 off, 1 light-cluster heat map, 2 cascades tinted by index, 3 LOD levels. */
+    debug: number;
+    /** Post-processing effects and their settings, from the camera's components. */
+    post: PostSettings;
+    /** Set for PixelPerfect cameras: the low-resolution target and how it scales up. */
+    pixelPerfect: PixelPerfectLayout | undefined;
+}
+export declare const Cameras: import("@aethervtt/shard-core").ResourceDef<Map<number, CameraData>>;
+/** Global render settings the camera extraction applies to every view. */
+export interface ViewSettingsValue {
+    /** MSAA samples for forward cameras without an Antialiasing component. */
+    msaa: number;
+    /**
+     * Displays this dense or denser (pixels per CSS pixel) skip that default MSAA: their pixels are
+     * too small for stair-stepping to show, and 4 samples of a Retina frame cost about a third of
+     * it. 0: always use `msaa`. An Antialiasing component still wins.
+     */
+    msaaMaxPixelRatio: number;
+}
+export declare const ViewSettings: import("@aethervtt/shard-core").ResourceDef<ViewSettingsValue>;
+/** Whether a camera renders below (or above) its target's resolution and needs the upscale. */
+export declare function isScaled(cam: CameraData): boolean;
+/** Picks the aliases for a view from its camera data. Other plugins (FXAA) replace this. */
+export declare function viewAliases(cam: CameraData): Readonly<Record<string, string>>;
+export declare const extractCameras: import("@aethervtt/shard-core").SystemDef<{
+    q: import("@aethervtt/shard-core").Query;
+}>;
+/**
+ * The floating origin moved by `offset` (spec 0040): last frame's camera now lives in the new frame,
+ * so reprojection (motion vectors, TAA) lines up instead of seeing a cell-sized jump. A point `p` in
+ * the new frame was `p − offset` in the old one, so the old view-projection gains `translate(−offset)`.
+ * `viewProjNoJitter` becomes next extraction's `prevViewProj`; a frozen culling frustum moves too.
+ */
+export declare function shiftCameraHistory(cam: CameraData, x: number, y: number, z: number): void;
+/** The camera data of a view, if it's a camera view. */
+export declare function cameraOf(view: RenderView): CameraData | undefined;