@aethervtt/shard-render 0.0.1

package/dist/plugin.d.ts

@@ -0,0 +1,111 @@
+import { type World } from '@aethervtt/shard-core';
+import { type GpuContext } from '@aethervtt/shard-gpu';
+import { type Plugin } from '@aethervtt/shard-runtime';
+import { type ShaderBake, ShaderLibrary } from '@aethervtt/shard-shader';
+import { type CapturedBuffer, type CapturedImage, RenderGraph, type RenderView } from './graph.js';
+import { type RenderTarget } from './target.js';
+export declare const Gpu: import("@aethervtt/shard-core").ResourceDef<GpuContext>;
+export declare const Graph: import("@aethervtt/shard-core").ResourceDef<RenderGraph>;
+export declare const Shaders: import("@aethervtt/shard-core").ResourceDef<ShaderLibrary>;
+export declare const Views: import("@aethervtt/shard-core").ResourceDef<{
+    list: RenderView[];
+}>;
+export declare const Window: import("@aethervtt/shard-core").ResourceDef<RenderTarget>;
+export declare const GpuDeviceLost: import("@aethervtt/shard-core").EventDef<{
+    reason: string;
+    message: string;
+}>;
+/**
+ * The frame's render work, in `Last`, in this order. Plugins add systems to these sets:
+ * Begin clears per-frame state, Extract reads the world, Prepare uploads, Queue builds draw lists,
+ * Upload writes what the queue produced, Graph runs the render graph and submits.
+ */
+export declare const RenderSet: {
+    readonly Begin: import("@aethervtt/shard-core").SystemSetDef;
+    readonly Extract: import("@aethervtt/shard-core").SystemSetDef;
+    readonly Prepare: import("@aethervtt/shard-core").SystemSetDef;
+    readonly Queue: import("@aethervtt/shard-core").SystemSetDef;
+    readonly Upload: import("@aethervtt/shard-core").SystemSetDef;
+    readonly Graph: import("@aethervtt/shard-core").SystemSetDef;
+};
+export interface RenderPluginOptions {
+    /** Render into this canvas. Omit for headless (views use offscreen targets). */
+    canvas?: HTMLCanvasElement | OffscreenCanvas;
+    /** An existing GPU context (e.g. Dawn in Node). Otherwise one is created in `ready`. */
+    gpu?: GpuContext;
+    /**
+     * Headless stand-in for the window: cameras without a target render here. Used by the CLI for
+     * screenshots. Ignored when there's a canvas.
+     */
+    target?: RenderTarget;
+    features?: GPUFeatureName[];
+    /** An existing shader library to share (e.g. a preview rendering the game's own shaders). */
+    shaders?: ShaderLibrary;
+    /**
+     * Shader variants linked ahead of time (`Shaders.bake()` after a run, saved as JSON). With every
+     * variant baked, WESL never loads (spec 0056).
+     */
+    shaderBake?: ShaderBake;
+    /**
+     * Adds a 'window' view each frame when there's a canvas and no extract system added a view.
+     * Default true. Camera plugins turn this off by adding their own views.
+     */
+    windowView?: boolean;
+}
+/**
+ * Extra sections for `describeRender`, keyed by name. Plugins add theirs (lighting, post effects),
+ * so the renderer's description grows with what's installed.
+ */
+export declare const RenderDescribers: import("@aethervtt/shard-core").ResourceDef<Map<string, (world: World) => unknown>>;
+export declare const RenderOptions: import("@aethervtt/shard-core").ResourceDef<Required<Pick<RenderPluginOptions, "windowView">>>;
+export declare function renderPlugin(options?: RenderPluginOptions): Plugin;
+/** A screenshot of a view (default: the window) after the next frame renders it. */
+export declare function captureView(world: World, view?: string): Promise<CapturedImage>;
+/**
+ * Any texture of a view after the next frame renders it, as floats: `hdr` (in cd/m²: the
+ * pre-exposure is divided out), `post-hdr` (the same after the HDR post effects: aerial
+ * perspective, fog, bloom…), `depth`, G-buffer channels, effect buffers.
+ */
+export declare function captureBuffer(world: World, view: string, buffer: string): Promise<CapturedBuffer>;
+/** What the renderer is doing: graph order, culled nodes, views, pending pipelines. For agents. */
+export declare function describeRender(world: World): {
+    order: {
+        name: string;
+        kind: "compute" | "raw" | "render";
+        reads: string[];
+        writes: string[];
+    }[];
+    culled: string[];
+    perView: {
+        [k: string]: {
+            order: string[];
+            culled: string[];
+        };
+    };
+    pooledTextures: number;
+    views: {
+        name: string;
+        target: string;
+        size: number[];
+        renderSize: number[];
+        order: number;
+    }[];
+    pipelinesCompiling: number;
+    drawsSkipped: number;
+    gpuTimings: boolean;
+    stats: {
+        [k: string]: import("./stats.js").ViewStats;
+    };
+    counters: {
+        taaResets: number;
+        originShifts: number;
+    };
+    memory: import("./stats.js").GpuMemoryData;
+    recentErrors: {
+        code: string;
+        message: string;
+        hint?: string;
+        path?: string;
+        details?: unknown[];
+    }[];
+} & Record<string, unknown>;

package/dist/plugin.js

@@ -0,0 +1,182 @@
+import {
+  defineEvent,
+  defineResource,
+  defineSystem,
+  defineSystemSet,
+  Last,
+  ShardError
+} from "@aethervtt/shard-core";
+import { createGpuContext } from "@aethervtt/shard-gpu";
+import { definePlugin, LogResource } from "@aethervtt/shard-runtime";
+import { ShaderLibrary } from "@aethervtt/shard-shader";
+import { RenderGraph } from "./graph.js";
+import { registerEngineShaders } from "./shaders.js";
+import { GpuMemory, RenderCounters, RenderStats } from "./stats.js";
+import { WindowTarget } from "./target.js";
+const Gpu = defineResource("render/Gpu", {
+  description: "The GPU device, caches, and canvas."
+});
+const Graph = defineResource("render/Graph", {
+  description: "Render graph nodes, run for every view each frame."
+});
+const Shaders = defineResource("render/Shaders", {
+  description: "WESL shader modules: engine (shard::), plugins, and project (project::)."
+});
+const Views = defineResource("render/Views", {
+  description: "Views to render this frame. Rebuilt every frame by extract systems."
+});
+const Window = defineResource("render/Window", {
+  description: "Where cameras without a target render: the canvas swapchain, or an offscreen target when headless."
+});
+const GpuDeviceLost = defineEvent(
+  "render/GpuDeviceLost",
+  {
+    description: "The GPU device was lost; the renderer is recreating it."
+  }
+);
+const RenderSet = {
+  Begin: defineSystemSet("render/Begin"),
+  Extract: defineSystemSet("render/Extract"),
+  Prepare: defineSystemSet("render/Prepare"),
+  Queue: defineSystemSet("render/Queue"),
+  Upload: defineSystemSet("render/Upload"),
+  Graph: defineSystemSet("render/Graph")
+};
+const WINDOW_VIEW = "window";
+const begin = defineSystem({
+  name: "render/begin-frame",
+  description: "Clears the frame view list.",
+  run: (_, world) => {
+    world.resource(Views).list.length = 0;
+    world.resource(Gpu).pipelines.skipped = 0;
+  }
+});
+const execute = defineSystem({
+  name: "render/execute-graph",
+  description: "Runs the render graph for every view and submits.",
+  setup: () => ({ recovering: { value: false } }),
+  run: ({ recovering }, world) => {
+    if (recovering.value) return;
+    const views = world.resource(Views).list;
+    const window = world.tryResource(Window);
+    const options = world.resource(RenderOptions);
+    if (views.length === 0 && window && options.windowView) {
+      views.push({ name: WINDOW_VIEW, target: window, order: 0, data: {} });
+    }
+    if (views.length === 0) return;
+    world.resource(Graph).execute(world, views);
+  }
+});
+const RenderDescribers = defineResource(
+  "render/Describers",
+  { description: "Sections plugins add to render.describe.", init: () => /* @__PURE__ */ new Map() }
+);
+const RenderOptions = defineResource("render/Options");
+function renderPlugin(options = {}) {
+  return definePlugin({
+    name: "render",
+    provides: [
+      // graph and device
+      Gpu,
+      GpuDeviceLost,
+      Graph,
+      RenderDescribers,
+      RenderOptions,
+      Shaders,
+      Views,
+      Window
+    ],
+    dependencies: ["core/time"],
+    build(app) {
+      app.insertResource(Views, { list: [] }).insertResource(RenderOptions, { windowView: options.windowView ?? true }).configureSets(
+        Last,
+        RenderSet.Extract.after(RenderSet.Begin),
+        RenderSet.Prepare.after(RenderSet.Extract),
+        RenderSet.Queue.after(RenderSet.Prepare),
+        RenderSet.Upload.after(RenderSet.Queue),
+        RenderSet.Graph.after(RenderSet.Upload)
+      ).addSystems(Last, begin.inSet(RenderSet.Begin), execute.inSet(RenderSet.Graph));
+    },
+    async ready(app) {
+      const gpu = options.gpu ?? await createGpuContext({ canvas: options.canvas, features: options.features });
+      app.insertResource(Gpu, gpu);
+      app.insertResource(Graph, new RenderGraph(gpu));
+      const shaders = options.shaders ?? new ShaderLibrary();
+      if (!options.shaders) registerEngineShaders(shaders);
+      if (options.shaderBake) shaders.preload(options.shaderBake);
+      app.insertResource(Shaders, shaders);
+      if (gpu.context) app.insertResource(Window, new WindowTarget(gpu));
+      else if (options.target) app.insertResource(Window, options.target);
+      const log = app.world.tryResource(LogResource);
+      if (log) gpu.onError((error) => log.error(error));
+      gpu.onDeviceLost((info) => {
+        app.world.send(GpuDeviceLost, info);
+        void gpu.recreate();
+      });
+    }
+  });
+}
+function captureView(world, view = WINDOW_VIEW) {
+  return world.resource(Graph).capture(view);
+}
+async function captureBuffer(world, view, buffer) {
+  const graph = world.resource(Graph);
+  const result = await graph.capture(view, buffer);
+  if (!("format" in result)) {
+    const data = new Float32Array(result.data.length);
+    for (let i = 0; i < data.length; i++) data[i] = result.data[i] / 255;
+    return { width: result.width, height: result.height, format: "rgba8unorm", data };
+  }
+  if (buffer === "hdr" || buffer === "scene-color" || buffer === "post-hdr") {
+    const exposure = graph.lastViewData(view)?.camera?.exposure;
+    if (exposure) {
+      const d = result.data;
+      for (let i = 0; i < d.length; i++) if (i % 4 !== 3) d[i] = d[i] / exposure;
+    }
+  }
+  return result;
+}
+function describeRender(world) {
+  const graph = world.tryResource(Graph);
+  const gpu = world.tryResource(Gpu);
+  if (!graph || !gpu) {
+    throw new ShardError("render/not-ready", "The renderer has not initialized yet", {
+      hint: "Await app.init() so the render plugin can create the GPU device."
+    });
+  }
+  const base = {
+    ...graph.describe(),
+    views: world.resource(Views).list.map((v) => ({
+      name: v.name,
+      target: v.target.label,
+      size: [v.target.width, v.target.height],
+      renderSize: [v.width ?? v.target.width, v.height ?? v.target.height],
+      order: v.order
+    })),
+    pipelinesCompiling: gpu.pipelines.pending,
+    drawsSkipped: gpu.pipelines.skipped,
+    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 },
+    recentErrors: gpu.errors.slice(-5).map((e) => e.toJSON())
+  };
+  const sections = {};
+  for (const [name, fn] of world.tryResource(RenderDescribers) ?? []) sections[name] = fn(world);
+  return Object.assign(base, sections);
+}
+export {
+  Gpu,
+  GpuDeviceLost,
+  Graph,
+  RenderDescribers,
+  RenderOptions,
+  RenderSet,
+  Shaders,
+  Views,
+  Window,
+  captureBuffer,
+  captureView,
+  describeRender,
+  renderPlugin
+};

package/dist/pool.d.ts

@@ -0,0 +1,19 @@
+import type { GpuContext } from '@aethervtt/shard-gpu';
+/**
+ * Transient textures, reused across frames. Textures with the same format, size, usage, and sample
+ * count come from the same free list. Aliasing different resources within a frame is a later
+ * optimization; the API won't change for it.
+ */
+export declare class TexturePool {
+    private readonly entries;
+    private readonly gpu;
+    private frame;
+    private generation;
+    constructor(gpu: GpuContext);
+    /** Total textures currently held (in use or free). */
+    get size(): number;
+    beginFrame(): void;
+    acquire(descriptor: GPUTextureDescriptor & {
+        size: [number, number];
+    }): GPUTexture;
+}

package/dist/pool.js

@@ -0,0 +1,43 @@
+const EXPIRY_FRAMES = 60;
+class TexturePool {
+  entries = [];
+  gpu;
+  frame = 0;
+  generation = -1;
+  constructor(gpu) {
+    this.gpu = gpu;
+  }
+  /** Total textures currently held (in use or free). */
+  get size() {
+    return this.entries.length;
+  }
+  beginFrame() {
+    this.frame++;
+    if (this.generation !== this.gpu.generation) {
+      this.entries.length = 0;
+      this.generation = this.gpu.generation;
+    }
+    for (let i = this.entries.length - 1; i >= 0; i--) {
+      const entry = this.entries[i];
+      if (this.frame - entry.lastUsed > EXPIRY_FRAMES) {
+        entry.texture.destroy();
+        this.entries.splice(i, 1);
+      }
+    }
+  }
+  acquire(descriptor) {
+    const key = `${descriptor.format}|${descriptor.size[0]}x${descriptor.size[1]}|${descriptor.usage}|${descriptor.sampleCount ?? 1}|${descriptor.mipLevelCount ?? 1}`;
+    for (const entry of this.entries) {
+      if (entry.key === key && entry.lastUsed !== this.frame) {
+        entry.lastUsed = this.frame;
+        return entry.texture;
+      }
+    }
+    const texture = this.gpu.device.createTexture(descriptor);
+    this.entries.push({ texture, key, lastUsed: this.frame });
+    return texture;
+  }
+}
+export {
+  TexturePool
+};

package/dist/post-common.d.ts

@@ -0,0 +1,51 @@
+import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
+import { type ViewGpu } from './forward.js';
+import type { NodeContext } from './graph.js';
+import { type CameraData } from './view.js';
+export declare function idOf(o: object): number;
+export declare const F: () => number;
+export declare const tex: (binding: number, sampleType?: GPUTextureSampleType) => {
+    binding: number;
+    visibility: number;
+    texture: {
+        sampleType: GPUTextureSampleType;
+    };
+};
+export declare const uniform: (binding: number, visibility?: number) => {
+    binding: number;
+    visibility: number;
+    buffer: {
+        type: 'uniform';
+    };
+};
+export declare const sampler: (binding: number) => {
+    binding: number;
+    visibility: number;
+    sampler: {
+        type: 'filtering';
+    };
+};
+/** Per-node caches: pipelines by key, bind groups by slot, uniform buffers by view. */
+export declare class PostCache {
+    private generation;
+    private readonly pipelines;
+    private readonly groups;
+    private readonly buffers;
+    private linear;
+    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;
+    /** 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;
+    sampler(gpu: GpuContext): GPUSampler;
+}
+export declare function forwardView(ctx: NodeContext): {
+    cam: CameraData;
+    pv: ViewGpu;
+} | undefined;
+/** 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[];
+export declare const scratch: Float32Array<ArrayBuffer>;

package/dist/post-common.js

@@ -0,0 +1,148 @@
+import { GpuBuffer } from "@aethervtt/shard-gpu";
+import { ForwardStateResource } from "./forward.js";
+import { Shaders } from "./plugin.js";
+import { cameraOf } from "./view.js";
+const textureIds = /* @__PURE__ */ new WeakMap();
+let nextId = 1;
+function idOf(o) {
+  let id = textureIds.get(o);
+  if (id === void 0) {
+    id = nextId++;
+    textureIds.set(o, id);
+  }
+  return id;
+}
+const F = () => GPUShaderStage.FRAGMENT;
+const tex = (binding, sampleType = "float") => ({
+  binding,
+  visibility: F(),
+  texture: { sampleType }
+});
+const uniform = (binding, visibility = F()) => ({
+  binding,
+  visibility,
+  buffer: { type: "uniform" }
+});
+const sampler = (binding) => ({
+  binding,
+  visibility: F(),
+  sampler: { type: "filtering" }
+});
+class PostCache {
+  generation = -1;
+  pipelines = /* @__PURE__ */ new Map();
+  groups = /* @__PURE__ */ new Map();
+  buffers = /* @__PURE__ */ new Map();
+  linear;
+  check(gpu) {
+    if (this.generation === gpu.generation) return;
+    this.generation = gpu.generation;
+    this.pipelines.clear();
+    this.groups.clear();
+    this.buffers.clear();
+    this.linear = void 0;
+  }
+  /** A fullscreen render pipeline: `shard::fullscreen` vertex stage and `root`'s `entry`. */
+  render(ctx, key, root, entry, layouts, targets, defines) {
+    const gpu = ctx.gpu;
+    this.check(gpu);
+    const cached = this.pipelines.get(key);
+    if (cached) return cached;
+    const shaders = ctx.world.resource(Shaders);
+    const fs = shaders.module(gpu, { root, defines });
+    const vs = shaders.module(gpu, { root: "shard::fullscreen" });
+    if (!fs || !vs) {
+      gpu.pipelines.skipped++;
+      return void 0;
+    }
+    const pipeline = gpu.pipelines.render({
+      label: key,
+      layout: gpu.layouts.pipelineLayout({ label: key, bindGroupLayouts: layouts }),
+      vertex: { module: vs, entryPoint: "vs" },
+      fragment: { module: fs, entryPoint: entry, targets }
+    });
+    if (pipeline) this.pipelines.set(key, pipeline);
+    return pipeline;
+  }
+  compute(ctx, key, root, entry, layouts) {
+    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 });
+    if (!module) {
+      gpu.pipelines.skipped++;
+      return void 0;
+    }
+    const pipeline = gpu.pipelines.compute({
+      label: key,
+      layout: gpu.layouts.pipelineLayout({ label: key, bindGroupLayouts: layouts }),
+      compute: { module, entryPoint: entry }
+    });
+    if (pipeline) this.pipelines.set(key, pipeline);
+    return pipeline;
+  }
+  /** A bind group, rebuilt when `key` (the ids of what it binds) changes. */
+  group(gpu, slot, key, layout, entries) {
+    this.check(gpu);
+    let g = this.groups.get(slot);
+    if (!g || g.key !== key) {
+      g = { key, group: gpu.device.createBindGroup({ label: slot, layout, entries: entries() }) };
+      this.groups.set(slot, g);
+    }
+    return g.group;
+  }
+  buffer(gpu, name, size) {
+    this.check(gpu);
+    let b = this.buffers.get(name);
+    if (!b) {
+      b = new GpuBuffer(gpu, { label: name, usage: GPUBufferUsage.UNIFORM, size });
+      this.buffers.set(name, b);
+    }
+    return b;
+  }
+  sampler(gpu) {
+    this.check(gpu);
+    this.linear ??= gpu.device.createSampler({
+      label: "post/linear",
+      magFilter: "linear",
+      minFilter: "linear",
+      addressModeU: "clamp-to-edge",
+      addressModeV: "clamp-to-edge"
+    });
+    return this.linear;
+  }
+}
+function forwardView(ctx) {
+  const cam = cameraOf(ctx.view);
+  const pv = ctx.world.resource(ForwardStateResource).views.get(ctx.view.name);
+  return cam && pv ? { cam, pv } : void 0;
+}
+function beginPass(ctx, name, view, load = false) {
+  return ctx.encoder.beginRenderPass({
+    label: `${ctx.view.name}/${name}`,
+    colorAttachments: [
+      {
+        view,
+        loadOp: load ? "load" : "clear",
+        clearValue: { r: 0, g: 0, b: 0, a: 0 },
+        storeOp: "store"
+      }
+    ],
+    timestampWrites: ctx.timestamps(name)
+  });
+}
+const HDR = [{ format: "rgba16float" }];
+const scratch = new Float32Array(64);
+export {
+  F,
+  HDR,
+  PostCache,
+  beginPass,
+  forwardView,
+  idOf,
+  sampler,
+  scratch,
+  tex,
+  uniform
+};

package/dist/post-nodes.d.ts

@@ -0,0 +1,39 @@
+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;
+/** Metered EV100 per camera (from the GPU histogram, a frame or two late) and the adapted EV. */
+export interface ExposureState {
+    metered: number | undefined;
+    /** Histogram readings landed so far. Each lands a few frames after its own, when the GPU gets to it. */
+    readings: number;
+    /** Readbacks issued for this camera, one per metered frame (numbered from 1). */
+    submitted: number;
+    /** Which readback `metered` came from. Older readings that land late are ignored. */
+    reading: number;
+    ev: number;
+    started: boolean;
+}
+/** Histogram readbacks in flight per camera. A frame whose readbacks are all still mapping isn't metered. */
+export declare const METER_READBACKS = 3;
+export declare const ExposureMeters: import("@aethervtt/shard-core").ResourceDef<Map<number, ExposureState>>;
+/**
+ * The mean EV of a histogram, ignoring the darkest 10% and brightest 2% of the weight so a few
+ * dark or blown-out pixels don't swing the exposure.
+ */
+export declare function histogramEv(bins: Uint32Array): number | undefined;
+/**
+ * Moves each AutoExposure camera's Exposure.ev100 toward its metered EV (minus compensation,
+ * within bounds) at its adaptation speed. Starts from the camera's own exposure.
+ */
+export declare const adaptExposure: import("@aethervtt/shard-core").SystemDef<{
+    q: import("@aethervtt/shard-core").Query;
+}>;
+/** Graph node names of the post chain, in order (for describe and tests). */
+export declare const POST_NODES: readonly [readonly ['post/fog', 1], readonly ['post/taa', 2], readonly ['post/motion-blur', 4], readonly ['post/dof', 8], readonly ['post/bloom', 16], readonly ['post/exposure', 32], readonly ['post/fxaa', 64]];
+/** Adds the prepass, SSAO, and the post chain to the graph. */
+export declare function addPostNodes(world: World): void;
+/** The post section of `render.describe`: per view, active effects in order with GPU time. */
+export declare function describePost(world: World): {
+    views: Record<string, unknown>;
+};