@aethervtt/shard-render 0.1.0 → 0.2.1

package/dist/decals-plugin.js

@@ -0,0 +1,54 @@
+import { defineResource, defineSystem, Last, PostUpdate } from "@aethervtt/shard-core";
+import { definePlugin, FrameDemand } from "@aethervtt/shard-runtime";
+import { TransformSystems } from "@aethervtt/shard-transform";
+import { Decals, describeDecals, updateDecals } from "./decals.js";
+import { addRenderFeatures } from "./features.js";
+import { Graph, RenderDescribers, RenderSet, Shaders } from "./plugin.js";
+import { registerShaders } from "./shaders.js";
+import { DecalsPath } from "./vfx.js";
+import { VFX_SHADERS, VfxRenderer } from "./vfx-draw.js";
+import { computeVisibility } from "./visibility.js";
+const DecalGpu = defineResource("render/DecalGpu", {
+  init: () => ({})
+});
+const prune = defineSystem({
+  name: "render/decals-prune",
+  run: (_, world) => world.resource(DecalGpu).renderer?.prune(world)
+});
+const decalsPlugin = definePlugin({
+  name: "render/decals",
+  dependencies: ["render/forward"],
+  provides: [Decals, DecalGpu, updateDecals],
+  build(app) {
+    app.world.initResource(DecalsPath);
+    app.world.initResource(Decals);
+    app.world.initResource(DecalGpu);
+    app.addSystems(PostUpdate, updateDecals.after(TransformSystems, computeVisibility));
+    app.addSystems(Last, prune.inSet(RenderSet.Prepare));
+  },
+  ready(app) {
+    const w = app.world, renderer = new VfxRenderer(w.resource(Decals).records, true);
+    w.resource(DecalGpu).renderer = renderer;
+    registerShaders(w.resource(Shaders), VFX_SHADERS);
+    addRenderFeatures(w, {
+      name: "render/decals",
+      description: "Clipped rigid-mesh projected decals.",
+      nodes: ["decals"],
+      baseline: { strategy: "CPU projection and the same vertex/fragment passes" }
+    });
+    w.resource(Graph).addNode("decals", renderer.node());
+    w.initResource(RenderDescribers).set("decals", describeDecals);
+  },
+  dispose(app) {
+    app.world.resource(DecalGpu).renderer?.dispose();
+    const s = app.world.resource(Decals);
+    s.records.length = 0;
+    s.receivers.length = 0;
+    s.receiverByEntity.clear();
+    app.world.tryResource(FrameDemand)?.set("render/decals", false);
+  }
+});
+export {
+  DecalGpu,
+  decalsPlugin
+};

package/dist/decals.d.ts

@@ -0,0 +1,69 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import type { Mesh } from '@aethervtt/shard-mesh';
+import { type VfxRecord } from './vfx-state.js';
+export declare const DECAL_TRIANGLE_BUDGET = 32768;
+export interface DecalRange {
+    start: number;
+    count: number;
+    entity: Entity;
+    layers: number;
+}
+interface Receiver {
+    entity: Entity;
+    matrix: Float64Array;
+    mesh: Mesh | undefined;
+    version: number;
+    mask: number;
+    visible: boolean;
+    unsupported: boolean;
+    layers: number;
+    seen: number;
+}
+export interface DecalRecord extends VfxRecord {
+    inverse: Float64Array;
+    settings: Float64Array;
+    geometryCount: number;
+    receiverRevision: number;
+    rebuilds: number;
+    ranges: DecalRange[];
+    clipA: Float64Array;
+    clipB: Float64Array;
+    worldTriangle: Float64Array;
+}
+export declare const Decals: import("@aethervtt/shard-core").ResourceDef<{
+    records: DecalRecord[];
+    receivers: Receiver[];
+    receiverByEntity: Map<number, Receiver>;
+    frame: number;
+    revision: number;
+    rejected: number;
+}>;
+/** Clips a convex polygon against one axis-aligned half-space. Scratch fits a clipped triangle. */
+export declare function clipPlane(input: Float64Array, count: number, output: Float64Array, axis: number, sign: number, half: number): number;
+/** Cold projection work. Output is all-or-nothing on budget/unsupported errors. */
+export declare function projectDecal(r: DecalRecord, receivers: readonly Receiver[]): void;
+export declare const updateDecals: import("@aethervtt/shard-core").SystemDef<{
+    q: import("@aethervtt/shard-core").Query;
+    receivers: import("@aethervtt/shard-core").Query;
+}>;
+export declare function describeDecals(world: World): {
+    rejected: number;
+    error: string | null;
+    receivers: number;
+    records: {
+        entity: number;
+        kind: "beam" | "decal" | "trail";
+        vertices: number;
+        age: number;
+        opacity: number;
+        error: string | null;
+        visible: boolean;
+        texture: string;
+        playing: boolean;
+        paused: boolean;
+        cpuBytes: number;
+        rebuilds: number;
+        triangles: number;
+    }[];
+};
+export {};

package/dist/decals.js

@@ -0,0 +1,326 @@
+import {
+  affine,
+  defineResource,
+  defineSystem
+} from "@aethervtt/shard-core";
+import { FrameDemand, Time } from "@aethervtt/shard-runtime";
+import { GlobalTransform } from "@aethervtt/shard-transform";
+import { Materials, Meshes } from "./assets.js";
+import { Mesh3d, MeshMaterial, MorphWeights, SkinnedMesh } from "./instances.js";
+import { RenderLayers } from "./layers.js";
+import { isTransparent } from "./materials.js";
+import { Decal, DecalReceiver } from "./vfx.js";
+import {
+  createRecord,
+  matrixChanged,
+  number,
+  point,
+  recordDescription,
+  refreshRecord,
+  VFX_STRIDE
+} from "./vfx-state.js";
+import { ComputedVisibility } from "./visibility.js";
+const DECAL_TRIANGLE_BUDGET = 32768;
+const Decals = defineResource("render/Decals", {
+  init: () => ({
+    records: [],
+    receivers: [],
+    receiverByEntity: /* @__PURE__ */ new Map(),
+    frame: 0,
+    revision: 0,
+    rejected: 0
+  })
+});
+function create(world, entity) {
+  const max = world.get(entity, Decal).maxVertices;
+  return {
+    ...createRecord(world, entity, Decal, "decal", max),
+    inverse: new Float64Array(12),
+    settings: new Float64Array(8).fill(NaN),
+    geometryCount: 0,
+    receiverRevision: -1,
+    rebuilds: 0,
+    ranges: [],
+    clipA: new Float64Array(48),
+    clipB: new Float64Array(48),
+    worldTriangle: new Float64Array(9)
+  };
+}
+function clipPlane(input, count, output, axis, sign, half) {
+  let n = 0;
+  for (let i = 0; i < count; i++) {
+    const a = (i + count - 1) % count * 3, b = i * 3;
+    const da = half - sign * input[a + axis], db = half - sign * input[b + axis];
+    if (da >= 0 !== db >= 0) {
+      const f = da / (da - db);
+      for (let k = 0; k < 3; k++)
+        output[n * 3 + k] = input[a + k] + (input[b + k] - input[a + k]) * f;
+      n++;
+    }
+    if (db >= 0) {
+      for (let k = 0; k < 3; k++) output[n * 3 + k] = input[b + k];
+      n++;
+    }
+  }
+  return n;
+}
+function intersects(r, receiver, sx, sy, sz) {
+  const bounds = receiver.mesh.bounds, scratch = r.worldTriangle;
+  let minX = Infinity, minY = Infinity, minZ = Infinity, maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+  for (let i = 0; i < 8; i++) {
+    point(
+      scratch,
+      0,
+      receiver.matrix,
+      bounds[i & 1 ? 3 : 0],
+      bounds[i & 2 ? 4 : 1],
+      bounds[i & 4 ? 5 : 2]
+    );
+    point(scratch, 3, r.inverse, scratch[0], scratch[1], scratch[2]);
+    minX = Math.min(minX, scratch[3]);
+    minY = Math.min(minY, scratch[4]);
+    minZ = Math.min(minZ, scratch[5]);
+    maxX = Math.max(maxX, scratch[3]);
+    maxY = Math.max(maxY, scratch[4]);
+    maxZ = Math.max(maxZ, scratch[5]);
+  }
+  return minX <= sx / 2 && maxX >= -sx / 2 && minY <= sy / 2 && maxY >= -sy / 2 && minZ <= sz / 2 && maxZ >= -sz / 2;
+}
+function projectDecal(r, receivers) {
+  r.count = 0;
+  r.geometryCount = 0;
+  r.ranges.length = 0;
+  r.error = null;
+  r.rebuilds++;
+  if (!affine.invert(r.inverse, r.matrix)) {
+    r.error = "render/decal-singular";
+    return;
+  }
+  const size = r.columns.size, so = r.row * 3;
+  const sx = size[so], sy = size[so + 1], sz = size[so + 2];
+  if (!(sx > 0 && sy > 0 && sz > 0)) {
+    r.error = "render/decal-size";
+    return;
+  }
+  const mask = number(r, "receiverMask"), offset = number(r, "offset"), cos = Math.cos(number(r, "maxAngle") * Math.PI / 180);
+  const zx = r.matrix[2], zy = r.matrix[6], zz = r.matrix[10], zl = Math.sqrt(zx * zx + zy * zy + zz * zz);
+  let tested = 0;
+  for (let ri = 0; ri < receivers.length; ri++) {
+    const receiver = receivers[ri], mesh = receiver.mesh;
+    if (!receiver.visible || !(receiver.mask & mask) || !mesh || !intersects(r, receiver, sx, sy, sz))
+      continue;
+    if (receiver.unsupported) {
+      r.error = "render/decal-unsupported-receiver";
+      break;
+    }
+    const start = r.count, positions = mesh.positions, indices = mesh.indices;
+    const triangles = Math.floor((indices ? indices.length : positions.length / 3) / 3);
+    if (tested + triangles > DECAL_TRIANGLE_BUDGET) {
+      r.error = "render/decal-input-budget";
+      break;
+    }
+    tested += triangles;
+    for (let t = 0; t < triangles; t++) {
+      for (let v = 0; v < 3; v++) {
+        const vi = (indices ? indices[t * 3 + v] : t * 3 + v) * 3;
+        point(
+          r.worldTriangle,
+          v * 3,
+          receiver.matrix,
+          positions[vi],
+          positions[vi + 1],
+          positions[vi + 2]
+        );
+      }
+      const w = r.worldTriangle;
+      const ax = w[3] - w[0], ay = w[4] - w[1], az = w[5] - w[2], bx = w[6] - w[0], by = w[7] - w[1], bz = w[8] - w[2];
+      let nx = ay * bz - az * by, ny = az * bx - ax * bz, nz = ax * by - ay * bx;
+      const length = Math.sqrt(nx * nx + ny * ny + nz * nz);
+      if (length < 1e-12) continue;
+      nx /= length;
+      ny /= length;
+      nz /= length;
+      if ((nx * zx + ny * zy + nz * zz) / zl < cos) continue;
+      for (let v = 0; v < 3; v++)
+        point(r.clipA, v * 3, r.inverse, w[v * 3], w[v * 3 + 1], w[v * 3 + 2]);
+      let a = r.clipA, b = r.clipB, count = 3;
+      for (let plane = 0; plane < 6 && count; plane++) {
+        const axis = plane >> 1, half = (axis === 0 ? sx : axis === 1 ? sy : sz) * 0.5;
+        count = clipPlane(a, count, b, axis, plane % 2 ? -1 : 1, half);
+        const swap = a;
+        a = b;
+        b = swap;
+      }
+      if (count < 3) continue;
+      if (r.count + (count - 2) * 3 > r.vertices.length / VFX_STRIDE) {
+        r.error = "render/decal-output-budget";
+        break;
+      }
+      for (let fan = 1; fan < count - 1; fan++)
+        for (let v = 0; v < 3; v++) {
+          const at = (v === 0 ? 0 : v === 1 ? fan : fan + 1) * 3, o = r.count++ * VFX_STRIDE;
+          point(w, 0, r.matrix, a[at], a[at + 1], a[at + 2]);
+          r.vertices[o] = w[0] + nx * offset;
+          r.vertices[o + 1] = w[1] + ny * offset;
+          r.vertices[o + 2] = w[2] + nz * offset;
+          r.vertices[o + 3] = 0;
+          r.vertices[o + 4] = 0;
+          r.vertices[o + 5] = 0;
+          r.vertices[o + 6] = a[at] / sx + 0.5;
+          r.vertices[o + 7] = 0.5 - a[at + 1] / sy;
+          for (let k = 8; k < 12; k++) r.vertices[o + k] = 1;
+          r.vertices[o + 12] = 0;
+          r.vertices[o + 13] = 0;
+        }
+    }
+    if (r.error) break;
+    if (r.count > start)
+      r.ranges.push({
+        start,
+        count: r.count - start,
+        entity: receiver.entity,
+        layers: receiver.layers
+      });
+  }
+  if (r.error) {
+    r.count = 0;
+    r.ranges.length = 0;
+  }
+  r.geometryCount = r.count;
+  r.version++;
+}
+const updateDecals = defineSystem({
+  name: "render/decals-update",
+  setup: (world) => ({
+    q: world.query({ with: [Decal, GlobalTransform] }),
+    receivers: world.query({ with: [DecalReceiver, Mesh3d, GlobalTransform] })
+  }),
+  run({ q, receivers }, world) {
+    const state = world.resource(Decals), meshes = world.resource(Meshes), delta = world.resource(Time).delta;
+    state.frame++;
+    state.rejected = 0;
+    for (let ti = 0; ti < receivers.tables.length; ti++) {
+      const table = receivers.tables[ti], mask = table.column(DecalReceiver, "mask"), refs = table.column(Mesh3d, "mesh");
+      for (let row = 0; row < table.count; row++) {
+        const entity = table.entities[row];
+        let receiver = state.receiverByEntity.get(entity);
+        if (!receiver) {
+          receiver = {
+            entity,
+            matrix: new Float64Array(12),
+            mesh: void 0,
+            version: -1,
+            mask: -1,
+            visible: false,
+            unsupported: false,
+            layers: 1,
+            seen: 0
+          };
+          state.receivers.push(receiver);
+          state.receiverByEntity.set(entity, receiver);
+          state.revision++;
+        }
+        const mesh = meshes.get(refs[row]), version = mesh?.version ?? -1;
+        const visible = !table.has(ComputedVisibility) || table.column(ComputedVisibility, "visible")[row] !== 0;
+        const layers = table.has(RenderLayers) ? table.column(RenderLayers, "mask")[row] : 1;
+        let unsupported = !!mesh && (!mesh.positions || !!mesh.joints || !!mesh.targets?.length || table.has(SkinnedMesh) || table.has(MorphWeights));
+        if (table.has(MeshMaterial)) {
+          const material = world.tryResource(Materials)?.get(table.column(MeshMaterial, "material")[row]);
+          if (material && isTransparent(material.type.blendOf(material.value))) unsupported = true;
+        }
+        if (matrixChanged(world, entity, receiver.matrix) || receiver.mesh !== mesh || receiver.version !== version || receiver.mask !== mask[row] || receiver.visible !== visible || receiver.layers !== layers || receiver.unsupported !== unsupported)
+          state.revision++;
+        receiver.mesh = mesh;
+        receiver.version = version;
+        receiver.mask = mask[row];
+        receiver.visible = visible;
+        receiver.layers = layers;
+        receiver.unsupported = unsupported;
+        receiver.seen = state.frame;
+      }
+    }
+    for (let i = state.receivers.length - 1; i >= 0; i--)
+      if (state.receivers[i].seen !== state.frame) {
+        state.receiverByEntity.delete(state.receivers[i].entity);
+        state.receivers.splice(i, 1);
+        state.revision++;
+      }
+    let demand = false;
+    for (let ti = 0; ti < q.tables.length; ti++) {
+      const table = q.tables[ti];
+      for (let row = 0; row < table.count; row++) {
+        const entity = table.entities[row];
+        const maxVertices = table.column(Decal, "maxVertices")[row];
+        if (maxVertices < 3 || maxVertices > 65535) {
+          state.rejected++;
+          continue;
+        }
+        let r;
+        for (let i = 0; i < state.records.length; i++)
+          if (state.records[i].entity === entity) {
+            r = state.records[i];
+            break;
+          }
+        if (!r) {
+          if (state.records.length >= 64) {
+            state.rejected++;
+            continue;
+          }
+          r = create(world, entity);
+          state.records.push(r);
+        }
+        refreshRecord(world, r);
+        r.seen = state.frame;
+        let changed = matrixChanged(world, entity, r.matrix);
+        const size = r.columns.size;
+        for (let i = 0; i < 8; i++) {
+          const value = i < 3 ? size[row * 3 + i] : i === 3 ? number(r, "receiverMask") : i === 4 ? number(r, "maxAngle") : i === 5 ? number(r, "offset") : i === 6 ? number(r, "maxVertices") : 0;
+          if (r.settings[i] !== value) changed = true;
+          r.settings[i] = value;
+        }
+        const capacity = number(r, "maxVertices") * VFX_STRIDE;
+        if (r.vertices.length !== capacity) {
+          r.vertices = new Float32Array(capacity);
+          changed = true;
+        }
+        const playing = !!number(r, "playing"), paused = !!number(r, "paused"), lifetime = number(r, "lifetime");
+        if (playing && !r.wasPlaying) r.age = 0;
+        r.wasPlaying = playing;
+        if (playing && !paused) r.age += delta;
+        if (changed || r.receiverRevision !== state.revision) {
+          projectDecal(r, state.receivers);
+          r.receiverRevision = state.revision;
+        }
+        r.count = playing && (!lifetime || r.age < lifetime) ? r.geometryCount : 0;
+        if (lifetime && number(r, "fadeOut") > 0)
+          r.opacity *= Math.min(1, Math.max(0, (lifetime - r.age) / number(r, "fadeOut")));
+        if (playing && !paused && lifetime > 0 && r.age < lifetime) demand = true;
+      }
+    }
+    for (let i = state.records.length - 1; i >= 0; i--)
+      if (state.records[i].seen !== state.frame) state.records.splice(i, 1);
+    world.tryResource(FrameDemand)?.set("render/decals", demand);
+  }
+});
+function describeDecals(world) {
+  const s = world.resource(Decals);
+  return {
+    rejected: s.rejected,
+    error: s.rejected ? "render/decal-limit" : null,
+    receivers: s.receivers.length,
+    records: s.records.map((r) => ({
+      ...recordDescription(r),
+      cpuBytes: r.vertices.byteLength + r.matrix.byteLength + r.inverse.byteLength + r.settings.byteLength + r.clipA.byteLength + r.clipB.byteLength + r.worldTriangle.byteLength,
+      rebuilds: r.rebuilds,
+      triangles: r.geometryCount / 3
+    }))
+  };
+}
+export {
+  DECAL_TRIANGLE_BUDGET,
+  Decals,
+  clipPlane,
+  describeDecals,
+  projectDecal,
+  updateDecals
+};

package/dist/deferred.js

@@ -2,6 +2,7 @@ import { ShardError } from "@aethervtt/shard-core";
 import { GpuBuffer } from "@aethervtt/shard-gpu";
 import { Culler } from "./culling.js";
 import { addRenderFeatures } from "./features.js";
+import { FoliagePath } from "./foliage-path.js";
 import {
   drawMaterials,
   ForwardStateResource,
@@ -31,7 +32,9 @@ function fillGBuffer(ctx) {
   const state = ctx.world.resource(ForwardStateResource);
   const cam = cameraOf(ctx.view);
   const pv = state.views.get(ctx.view.name);
-  if (pv) drawMaterials(ctx, state, pv, cam, cam.draws, PASS_GBUFFER);
+  if (!pv) return;
+  drawMaterials(ctx, state, pv, cam, cam.draws, PASS_GBUFFER);
+  ctx.world.tryResource(FoliagePath)?.draw(ctx, cam, PASS_GBUFFER, ctx.renderPass);
 }
 const gbufferNode = {
   kind: "render",

package/dist/display-nodes.js

@@ -33,7 +33,8 @@ function tonemapNode() {
     kind: "render",
     phase: RenderPhase.Tonemap,
     enabled: (view) => cameraOf(view) !== void 0,
-    reads: ["post-hdr"],
+    // Bloom's chain, when the view blooms: the glow is composited here (see the 'bloom' node).
+    reads: ["post-hdr", "bloom"],
     writes: ["ldr"],
     color: [{ resource: "ldr", clear: { r: 0, g: 0, b: 0, a: 1 } }],
     run: (ctx) => {
@@ -43,7 +44,7 @@ function tonemapNode() {
         layoutGen = gpu.generation;
         layout = gpu.layouts.bindGroupLayout({
           label: "tonemap",
-          entries: [tex(0, "unfilterable-float"), uniform(1), tex(2), sampler(3)]
+          entries: [tex(0, "unfilterable-float"), uniform(1), tex(2), sampler(3), tex(4)]
         });
         white = gpu.device.createTexture({
           label: "tonemap/no-lut",
@@ -55,16 +56,18 @@ function tonemapNode() {
       const format = ctx.texture("ldr").format;
       const srgb = format.endsWith("-srgb");
       const alpha = cam.alphaOutput;
+      const bloom = (cam.post.effects & PostEffect.Bloom) !== 0;
       const pipeline = cache.render(
         ctx,
-        `tonemap/${format}${alpha ? "/alpha" : ""}`,
+        `tonemap/${format}${alpha ? "/alpha" : ""}${bloom ? "/bloom" : ""}`,
         "shard::post::tonemap",
         "fs",
         [layout],
         [{ format }],
         {
           SRGB_TARGET: srgb,
-          TRANSPARENT: alpha
+          TRANSPARENT: alpha,
+          BLOOM: bloom
         }
       );
       if (!pipeline) return;
@@ -82,7 +85,7 @@ function tonemapNode() {
           flags |= 4;
         }
       }
-      scratch.fill(0, 0, 32);
+      scratch.fill(0, 0, 36);
       u[0] = cam.curve;
       u[1] = cam.dither ? 1 : 0;
       u[2] = flags;
@@ -100,20 +103,30 @@ function tonemapNode() {
       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 chain = bloom ? ctx.texture("bloom") : void 0;
+      if (chain) {
+        const b = post.bloom;
+        scratch[32] = b.intensity;
+        scratch[33] = chain.mipLevelCount;
+        scratch[34] = b.threshold > 0 ? 0 : 1;
+      }
+      const params = cache.buffer(gpu, `${ctx.view.name}/tonemap`, 144);
+      params.write(scratch, 0, 0, 36);
       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}`,
+        `${idOf(hdr)}/${params.version}/${lut ? idOf(lut) : 0}/${chain ? idOf(chain) : 0}`,
         layout,
         () => [
           { binding: 0, resource: hdr.createView() },
           { binding: 1, resource: { buffer: params.buffer } },
-          { binding: 2, resource: lutView },
-          { binding: 3, resource: cache.sampler(gpu) }
+          { binding: 2, resource: lut ?? white.createView() },
+          { binding: 3, resource: cache.sampler(gpu) },
+          {
+            binding: 4,
+            resource: chain ? chain.createView({ mipLevelCount: 1 }) : white.createView()
+          }
         ]
       );
       const pass = ctx.renderPass;

package/dist/foliage-budget.d.ts

@@ -0,0 +1,64 @@
+import { type Profiler } from '@aethervtt/shard-core';
+/** The budget key foliage's GPU time is measured by: it covers `gpu:foliage/place`, `/cull`, `/draw`. */
+export declare const FOLIAGE_SPAN_KEY = "gpu:foliage";
+export interface FoliageBudgetValue {
+    /**
+     * GPU milliseconds foliage may take a frame. 0 (the default): its `gpu:foliage` slice of the
+     * app's scenario (`App.perfScenario`) on the detected machine, and with no scenario (or an
+     * unknown machine) no target: foliage draws at full detail.
+     */
+    ms: number;
+    /** The least detail it thins to, as a share of the instances drawn at full detail. Default 0.1. */
+    minDetail: number;
+    /** Read only: the target in force (ms), 0 when none. */
+    target: number;
+    /** Read only: foliage's GPU time a frame, smoothed (ms). */
+    measuredMs: number;
+    /**
+     * Read only: the share of full detail drawn (minDetail to 1). Density is its square root and range
+     * its fourth root, so instances drawn scale with it.
+     */
+    detail: number;
+}
+export declare const FoliageBudget: import("@aethervtt/shard-core").ResourceDef<FoliageBudgetValue>;
+/**
+ * The controller: one GPU time a frame in, detail out. Smoothed (an exponential average), with
+ * hysteresis (it moves only above the target, or under 85% of it) and asymmetric steps (down 1% a
+ * sample, up 0.5%), so the lag of GPU timings (frames late) doesn't make it oscillate. Like
+ * `TerrainBudget.triangles`' LOD bias (0043), slow on purpose: density and range change gradually.
+ */
+export declare class FoliageController {
+    detail: number;
+    /** Smoothed GPU time (ms); 0 before the first sample. */
+    smoothed: number;
+    private primed;
+    /** One frame's foliage GPU time against `target` (0: none, back to full detail at once). */
+    sample(ms: number, target: number, minDetail: number): void;
+    /** No target: full detail, and the smoothing starts over. */
+    reset(): void;
+    /** The share of instances kept by thinning (the cull's density factor). */
+    get density(): number;
+    /** The share of each layer's range drawn. */
+    get rangeScale(): number;
+}
+/**
+ * Reads the GPU time a budget key covers, one GPU frame at a time, without allocating: when
+ * `gpu:frame` has a new sample, the covered spans that got one with it are summed. Span names are
+ * matched by `spanCovers` as they're interned.
+ */
+export declare class CoveredGpuTime {
+    readonly key: string;
+    /** The latest frame's covered time (ms), after `read` returned true. */
+    ms: number;
+    private ids;
+    private seen;
+    private count;
+    private scanned;
+    private frameId;
+    private frameRuns;
+    constructor(key: string);
+    /** True when a new GPU frame's timings landed since the last call; `ms` is then its covered time. */
+    read(profiler: Profiler): boolean;
+    /** New span names since the last scan: the ones the key covers join the list. */
+    private scan;
+}