@aethervtt/shard-render 0.0.1

package/dist/display-nodes.js

@@ -0,0 +1,189 @@
+import { Textures } from "@aethervtt/shard-texture";
+import { GpuAssetsResource } from "./gpu-assets.js";
+import { RenderPhase } from "./graph.js";
+import { Graph } from "./plugin.js";
+import { PostEffect } from "./post.js";
+import { idOf, PostCache, sampler, scratch, tex, uniform } from "./post-common.js";
+import { RenderScale } from "./render-scale.js";
+import { cameraOf } from "./view.js";
+function whiteBalance(temperature, tint, out) {
+  const t1 = temperature * 100 / 60;
+  const t2 = tint * 100 / 60;
+  const x = 0.31271 - t1 * (t1 < 0 ? 0.1 : 0.05);
+  const y = 2.87 * x - 3 * x * x - 0.27509507 + t2 * 0.05;
+  const X = x / y;
+  const Z = (1 - x - y) / y;
+  const L = 0.7328 * X + 0.4296 - 0.1624 * Z;
+  const M = -0.7036 * X + 1.6975 + 61e-4 * Z;
+  const S = 3e-3 * X + 0.0136 + 0.9834 * Z;
+  out[0] = 0.949237 / L;
+  out[1] = 1.03542 / M;
+  out[2] = 1.08728 / S;
+  return out;
+}
+function tonemapNode() {
+  const cache = new PostCache();
+  let layout;
+  let layoutGen = -1;
+  let white;
+  const u = new Uint32Array(scratch.buffer);
+  const balance = new Float32Array(3);
+  return {
+    kind: "render",
+    phase: RenderPhase.Tonemap,
+    enabled: (view) => cameraOf(view) !== void 0,
+    reads: ["post-hdr"],
+    writes: ["ldr"],
+    color: [{ resource: "ldr", clear: { r: 0, g: 0, b: 0, a: 1 } }],
+    run: (ctx) => {
+      const gpu = ctx.gpu;
+      const cam = cameraOf(ctx.view);
+      if (!layout || layoutGen !== gpu.generation) {
+        layoutGen = gpu.generation;
+        layout = gpu.layouts.bindGroupLayout({
+          label: "tonemap",
+          entries: [tex(0, "unfilterable-float"), uniform(1), tex(2), sampler(3)]
+        });
+        white = gpu.device.createTexture({
+          label: "tonemap/no-lut",
+          size: [1, 1],
+          format: "rgba8unorm",
+          usage: GPUTextureUsage.TEXTURE_BINDING
+        });
+      }
+      const format = ctx.texture("ldr").format;
+      const srgb = format.endsWith("-srgb");
+      const pipeline = cache.render(
+        ctx,
+        `tonemap/${format}`,
+        "shard::post::tonemap",
+        "fs",
+        [layout],
+        [{ format }],
+        {
+          SRGB_TARGET: srgb
+        }
+      );
+      if (!pipeline) return;
+      const post = cam.post;
+      const g = post.grading;
+      let flags = 0;
+      if (post.effects & PostEffect.Grading) flags |= 1;
+      if (post.effects & PostEffect.Vignette) flags |= 2;
+      let lut;
+      if (post.effects & PostEffect.Grading && g.lut) {
+        const texture = ctx.world.resource(Textures).get(g.lut);
+        const gt = texture ? ctx.world.resource(GpuAssetsResource).texture(texture) : void 0;
+        if (gt) {
+          lut = gt.linear;
+          flags |= 4;
+        }
+      }
+      scratch.fill(0, 0, 32);
+      u[0] = cam.curve;
+      u[1] = cam.dither ? 1 : 0;
+      u[2] = flags;
+      whiteBalance(g.temperature, g.tint, balance);
+      scratch[4] = balance[0];
+      scratch[5] = balance[1];
+      scratch[6] = balance[2];
+      scratch[8] = g.saturation;
+      scratch[9] = g.contrast;
+      scratch.set(g.lift, 12);
+      scratch.set(g.gamma, 16);
+      scratch.set(g.gain, 20);
+      scratch[24] = post.vignette.intensity;
+      scratch[25] = post.vignette.smoothness;
+      scratch[26] = cam.width / Math.max(1, cam.height);
+      scratch[28] = 1 / cam.width;
+      scratch[29] = 1 / cam.height;
+      const params = cache.buffer(gpu, `${ctx.view.name}/tonemap`, 128);
+      params.write(scratch, 0, 0, 32);
+      const hdr = ctx.texture("post-hdr");
+      const lutView = lut ?? white.createView();
+      const group = cache.group(
+        gpu,
+        `${ctx.view.name}/tonemap`,
+        `${idOf(hdr)}/${params.version}/${lut ? idOf(lut) : 0}`,
+        layout,
+        () => [
+          { binding: 0, resource: hdr.createView() },
+          { binding: 1, resource: { buffer: params.buffer } },
+          { binding: 2, resource: lutView },
+          { binding: 3, resource: cache.sampler(gpu) }
+        ]
+      );
+      const pass = ctx.renderPass;
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, group);
+      pass.draw(3);
+    }
+  };
+}
+const upscaleScratch = new Float32Array(4);
+function upscaleNode() {
+  const cache = new PostCache();
+  let layout;
+  let layoutGen = -1;
+  return {
+    kind: "render",
+    phase: RenderPhase.Display + 10,
+    enabled: (view) => view.width !== void 0 && cameraOf(view) !== void 0,
+    reads: ["display"],
+    writes: ["view-target"],
+    color: [{ resource: "view-target", clear: { r: 0, g: 0, b: 0, a: 1 } }],
+    run: (ctx) => {
+      const gpu = ctx.gpu;
+      if (!layout || layoutGen !== gpu.generation) {
+        layoutGen = gpu.generation;
+        layout = gpu.layouts.bindGroupLayout({
+          label: "upscale",
+          entries: [tex(0), sampler(1), uniform(2)]
+        });
+      }
+      const input = ctx.texture("display");
+      const target = ctx.texture("view-target");
+      const format = target.format;
+      const pipeline = cache.render(
+        ctx,
+        `upscale/${format}`,
+        "shard::post::upscale",
+        "fs",
+        [layout],
+        [{ format }]
+      );
+      if (!pipeline) return;
+      const settings = ctx.world.tryResource(RenderScale);
+      upscaleScratch[0] = 1 / target.width;
+      upscaleScratch[1] = 1 / target.height;
+      upscaleScratch[2] = Math.min(1, Math.max(0, settings?.sharpen ?? 0));
+      const params = cache.buffer(gpu, `${ctx.view.name}/upscale`, 16);
+      params.write(upscaleScratch, 0, 0, 4);
+      const group = cache.group(
+        gpu,
+        `${ctx.view.name}/upscale`,
+        `${idOf(input)}/${params.version}`,
+        layout,
+        () => [
+          { binding: 0, resource: input.createView() },
+          { binding: 1, resource: cache.sampler(gpu) },
+          { binding: 2, resource: { buffer: params.buffer } }
+        ]
+      );
+      const pass = ctx.renderPass;
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, group);
+      pass.draw(3);
+    }
+  };
+}
+function addDisplayNodes(world) {
+  const graph = world.resource(Graph);
+  graph.declare({ name: "display", format: "view" });
+  graph.addNode("tonemap", tonemapNode());
+  graph.addNode("post/upscale", upscaleNode());
+}
+export {
+  addDisplayNodes,
+  whiteBalance
+};

package/dist/dynamic-resolution.d.ts

@@ -0,0 +1,47 @@
+import { type RenderScaleValue } from './render-scale.js';
+/** What the controller reads from the GPU timer. */
+export interface FrameTimings {
+    readonly enabled: boolean;
+    readonly frameMs: number;
+    readonly frameSamples: number;
+}
+/**
+ * Dynamic resolution. With GPU timings it steps straight toward the budget (cost ∝ scale²); on
+ * the frame interval alone it drops on overruns, undoes a run of drops that didn't help at all
+ * (CPU-bound), and probes upward, backing off after failed probes. Vsync makes the interval move
+ * in whole refresh periods, so a single drop often shows nothing: runs of drops are judged together.
+ */
+export declare class RenderScaleController {
+    private ema;
+    private samples;
+    private cooldown;
+    private under;
+    private lastSample;
+    /** Frame mode: the measurement and scale before the current run of drops (0: none). */
+    private runEma;
+    private runFrom;
+    /** Frame mode: the interval found CPU-bound; overruns no worse than it are left alone. */
+    private cpuEma;
+    /** Frame mode: the scale before an upward probe, while it's being verified. */
+    private probeFrom;
+    private probeAge;
+    private probeWait;
+    private hold;
+    /**
+     * One frame. `skip`: pipelines are compiling, so the frame says nothing about steady cost.
+     * `displayMs`: one refresh of the display, the budget when `targetMs` is 0.
+     */
+    update(s: RenderScaleValue, dt: number, timings: FrameTimings, skip: boolean, displayMs?: number): void;
+    private gpuStep;
+    private frameStep;
+    private set;
+    private reset;
+}
+export declare const updateRenderScale: import("@aethervtt/shard-core").SystemDef<{
+    controller: RenderScaleController;
+}>;
+/**
+ * Dynamic resolution (spec 0051): RenderScale in auto mode moves the scale to hold the frame
+ * budget. Without it, the scale stays where it's set.
+ */
+export declare const dynamicResolutionPlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/dynamic-resolution.js

@@ -0,0 +1,191 @@
+import { defineSystem, Last } from "@aethervtt/shard-core";
+import { DisplayRate, definePlugin, Time } from "@aethervtt/shard-runtime";
+import { Gpu, Graph, RenderSet } from "./plugin.js";
+import {
+  HIGHEST,
+  LOWEST,
+  RenderScale,
+  SCALE_STEP,
+  STEPS
+} from "./render-scale.js";
+import { extractCameras } from "./view.js";
+const snapDown = (s) => Math.floor(s * STEPS + 1e-6) / STEPS;
+const snap = (s) => Math.round(s * STEPS) / STEPS;
+const clamp = (v, lo, hi) => Math.min(hi, Math.max(lo, v));
+const SETTLE_SAMPLES = 10;
+const COOLDOWN = 0.3;
+class RenderScaleController {
+  ema = 0;
+  samples = 0;
+  cooldown = 0;
+  under = 0;
+  lastSample = -1;
+  /** Frame mode: the measurement and scale before the current run of drops (0: none). */
+  runEma = 0;
+  runFrom = 0;
+  /** Frame mode: the interval found CPU-bound; overruns no worse than it are left alone. */
+  cpuEma = 0;
+  /** Frame mode: the scale before an upward probe, while it's being verified. */
+  probeFrom = 0;
+  probeAge = 0;
+  probeWait = 3;
+  hold = 0;
+  /**
+   * One frame. `skip`: pipelines are compiling, so the frame says nothing about steady cost.
+   * `displayMs`: one refresh of the display, the budget when `targetMs` is 0.
+   */
+  update(s, dt, timings, skip, displayMs = 1e3 / 60) {
+    const lo = clamp(s.min, LOWEST, HIGHEST);
+    const hi = clamp(s.max, lo, HIGHEST);
+    s.budgetMs = s.targetMs > 0 ? s.targetMs : Math.max(displayMs, 1e3 / Math.max(1, s.maxHz));
+    if (s.mode !== "auto" || s.windowViews === 0) {
+      s.signal = "none";
+      this.reset();
+      return;
+    }
+    const clamped = clamp(snap(s.scale), lo, hi);
+    if (clamped !== s.scale) this.set(s, clamped);
+    const gpu = timings.enabled && timings.frameSamples > 0;
+    s.signal = gpu ? "gpu" : "frame";
+    if (this.cooldown > 0) {
+      this.cooldown -= dt;
+      this.lastSample = timings.frameSamples;
+      return;
+    }
+    if (skip || dt >= 0.2) return;
+    let sample;
+    if (gpu) {
+      if (timings.frameSamples === this.lastSample) return;
+      this.lastSample = timings.frameSamples;
+      sample = timings.frameMs;
+    } else {
+      sample = dt * 1e3;
+    }
+    this.ema = this.samples === 0 ? sample : this.ema * 0.9 + sample * 0.1;
+    this.samples++;
+    s.measuredMs = this.ema;
+    if (this.samples < SETTLE_SAMPLES) return;
+    if (gpu) this.gpuStep(s, lo, hi, dt);
+    else this.frameStep(s, lo, hi, dt);
+  }
+  gpuStep(s, lo, hi, dt) {
+    const t = s.budgetMs;
+    const ema = this.ema;
+    if (ema > t * 0.95) {
+      this.under = 0;
+      const next = Math.max(
+        lo,
+        Math.min(snapDown(s.scale * Math.sqrt(0.8 * t / ema)), s.scale - SCALE_STEP)
+      );
+      if (next < s.scale) this.set(s, next);
+    } else if (s.scale < hi && ema * ((s.scale + SCALE_STEP) / s.scale) ** 2 < t * 0.8) {
+      this.under += dt;
+      if (this.under < 1) return;
+      const want = snapDown(s.scale * Math.sqrt(0.8 * t / ema));
+      const next = Math.min(hi, s.scale + 0.1, Math.max(want, s.scale + SCALE_STEP));
+      this.set(s, snap(next));
+    } else {
+      this.under = 0;
+    }
+  }
+  frameStep(s, lo, hi, dt) {
+    const t = s.budgetMs;
+    const ema = this.ema;
+    if (this.hold > 0) {
+      this.hold -= dt;
+      return;
+    }
+    if (this.probeFrom > 0) {
+      if (ema > t * 1.15) {
+        const back = this.probeFrom;
+        this.probeFrom = 0;
+        this.probeWait = Math.min(this.probeWait * 2, 30);
+        this.set(s, back);
+        return;
+      }
+      this.probeAge += dt;
+      if (this.probeAge >= 2) {
+        this.probeFrom = 0;
+        this.probeWait = 3;
+      }
+    }
+    if (ema > t * 1.15) {
+      this.under = 0;
+      if (this.cpuEma > 0 && ema < this.cpuEma * 1.1) return;
+      if (this.runEma === 0) {
+        this.runEma = ema;
+        this.runFrom = s.scale;
+      } else if (s.scale < this.runFrom && (s.scale <= this.runFrom * 0.71 + 1e-6 || s.scale <= lo) && ema > this.runEma * 0.95) {
+        const from = this.runFrom;
+        this.cpuEma = this.runEma;
+        this.runEma = 0;
+        this.set(s, from);
+        this.hold = 10;
+        return;
+      }
+      if (s.scale <= lo) return;
+      this.probeFrom = 0;
+      this.set(s, snap(Math.max(lo, s.scale - 2 * SCALE_STEP)));
+    } else if (ema <= t * 1.05) {
+      this.runEma = 0;
+      this.cpuEma = 0;
+      this.under += dt;
+      if (this.under >= this.probeWait && s.scale < hi && this.probeFrom === 0) {
+        this.probeFrom = s.scale;
+        this.probeAge = 0;
+        this.set(s, snap(Math.min(hi, s.scale + SCALE_STEP)));
+      }
+    } else {
+      this.under = 0;
+    }
+  }
+  set(s, scale) {
+    s.scale = scale;
+    this.ema = 0;
+    this.samples = 0;
+    this.under = 0;
+    this.cooldown = COOLDOWN;
+  }
+  reset() {
+    this.ema = 0;
+    this.samples = 0;
+    this.under = 0;
+    this.cooldown = 0;
+    this.runEma = 0;
+    this.cpuEma = 0;
+    this.probeFrom = 0;
+    this.probeWait = 3;
+    this.hold = 0;
+  }
+}
+const updateRenderScale = defineSystem({
+  name: "render/update-render-scale",
+  description: "Dynamic resolution: moves RenderScale.scale to hold the frame budget (auto mode).",
+  setup: () => ({ controller: new RenderScaleController() }),
+  run: ({ controller }, world) => {
+    const s = world.tryResource(RenderScale);
+    const gpu = world.tryResource(Gpu);
+    const graph = world.tryResource(Graph);
+    if (!s || !gpu || !graph) return;
+    const display = world.tryResource(DisplayRate)?.periodMs;
+    controller.update(
+      s,
+      world.resource(Time).delta,
+      graph.timer,
+      gpu.pipelines.pending > 0,
+      display
+    );
+  }
+});
+const dynamicResolutionPlugin = definePlugin({
+  name: "render/dynamic-resolution",
+  dependencies: ["render/forward"],
+  build(app) {
+    app.addSystems(Last, updateRenderScale.inSet(RenderSet.Extract).before(extractCameras));
+  }
+});
+export {
+  RenderScaleController,
+  dynamicResolutionPlugin,
+  updateRenderScale
+};

package/dist/environment-plugin.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Image-based lighting and skies (spec 0019): EnvironmentMap and DefaultEnvironment prefiltered on
+ * the GPU, Skybox backgrounds, and ProceduralSky (drawn by atmospherePlugin). Without it, cameras
+ * are lit by AmbientLight alone.
+ */
+export declare const environmentPlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/environment-plugin.js

@@ -0,0 +1,44 @@
+import { Last } from "@aethervtt/shard-core";
+import { definePlugin } from "@aethervtt/shard-runtime";
+import {
+  DefaultEnvironment,
+  describeEnvironment,
+  EnvironmentMap,
+  ProceduralSky,
+  prepareEnvironments,
+  runEnvironmentWork,
+  Skybox
+} from "./environment.js";
+import { ENVIRONMENT_SHADERS } from "./environment-shaders.js";
+import { ForwardStateResource, isCamera, skyNode } from "./forward.js";
+import { RenderPhase } from "./graph.js";
+import { Graph, RenderDescribers, RenderSet, Shaders } from "./plugin.js";
+import { registerShaders } from "./shaders.js";
+const environmentPlugin = definePlugin({
+  name: "render/environment",
+  dependencies: ["render/forward"],
+  provides: [DefaultEnvironment, EnvironmentMap, ProceduralSky, Skybox],
+  build(app) {
+    app.world.initResource(DefaultEnvironment);
+    app.addSystems(Last, prepareEnvironments.inSet(RenderSet.Prepare));
+  },
+  ready(app) {
+    const world = app.world;
+    registerShaders(world.resource(Shaders), ENVIRONMENT_SHADERS);
+    world.initResource(RenderDescribers).set("environment", (w) => describeEnvironment(w));
+    const graph = world.resource(Graph);
+    graph.addNode("environment", {
+      kind: "raw",
+      phase: RenderPhase.Setup,
+      enabled: isCamera,
+      // Atmosphere environments bake from the atmosphere LUTs.
+      reads: ["atmosphere-luts"],
+      writes: ["environment"],
+      run: runEnvironmentWork
+    });
+    graph.addNode("sky", skyNode(world.resource(ForwardStateResource)));
+  }
+});
+export {
+  environmentPlugin
+};

package/dist/environment-shaders.d.ts

@@ -0,0 +1,2 @@
+/** WGSL for environments: prefiltering (compute), IBL, and the environment-map background. */
+export declare const ENVIRONMENT_SHADERS: Record<string, string>;