@aethervtt/shard-render 0.0.1 → 0.2.0

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({
@@ -439,7 +497,7 @@ const SHADOW_BUFFERS = [
   { arrayStride: 8, attributes: [{ shaderLocation: 3, offset: 0, format: "float32x2" }] },
   { arrayStride: 16, attributes: [{ shaderLocation: 4, offset: 0, format: "float32x4" }] }
 ];
-function drawShadowCasters(ctx, target, view, offset, uniforms, pipelines, shadowView2, label) {
+function drawShadowCasters(ctx, target, view, offset, uniforms, pipelines, shadowView2, label, foliage, cam, cascade = 0) {
   const world = ctx.world;
   const gpu = ctx.gpu;
   const store = world.resource(Instances);
@@ -458,6 +516,7 @@ function drawShadowCasters(ctx, target, view, offset, uniforms, pipelines, shado
   const draws0 = view.draws;
   const instances = draws0.cullView >= 0 ? store.gpuBindGroup : store.bindGroup;
   if (!instances || !uniforms.bindGroup) {
+    if (foliage && cam && uniforms.bindGroup) foliage.drawShadow(ctx, cam, pass, offset, cascade);
     pass.end();
     return;
   }
@@ -472,7 +531,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 +541,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;
@@ -531,6 +608,7 @@ function drawShadowCasters(ctx, target, view, offset, uniforms, pipelines, shado
       pass.draw(gm.count, item.count, 0, item.first);
     }
   }
+  if (foliage && cam) foliage.drawShadow(ctx, cam, pass, offset, cascade);
   pass.end();
 }
 const PASS_SHADOW = 2;
@@ -555,8 +633,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,16 +1,25 @@
 import { definePlugin } from "@aethervtt/shard-runtime";
 import { atmospherePlugin } from "./atmosphere-plugin.js";
+import { cutawayPlugin } from "./cutaway-plugin.js";
+import { decalsPlugin } from "./decals-plugin.js";
 import { deferredPlugin } from "./deferred-plugin.js";
 import { renderDescribePlugin } from "./describe-plugin.js";
 import { dynamicResolutionPlugin } from "./dynamic-resolution.js";
 import { environmentPlugin } from "./environment-plugin.js";
+import { foliagePlugin } from "./foliage.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 { ribbonsPlugin } from "./ribbons-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,7 +35,16 @@ function forwardPlugin(options = {}) {
         deferredPlugin,
         skinningPlugin,
         pixelPerfectPlugin,
+        lensPlugin,
+        outlinePlugin,
+        cutawayPlugin,
+        viewVisibilityPlugin,
+        interiorPlugin,
+        shadowCatcherPlugin,
+        foliagePlugin,
         dynamicResolutionPlugin,
+        ribbonsPlugin,
+        decalsPlugin,
         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
 };

package/dist/surface-model.d.ts

@@ -0,0 +1,57 @@
+import { type InferFields } from '@aethervtt/shard-core';
+export declare const VARIATION_PATTERNS: readonly ['mottle', 'streaks', 'grain', 'cells', 'stagger', 'brushed'];
+export type VariationPattern = (typeof VARIATION_PATTERNS)[number];
+/** The variation's fields: one schema for validation, the inspector, and the GPU struct. */
+export declare const VARIATION_FIELDS: {
+    strength: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    seed: import("@aethervtt/shard-core").FieldType<number, "u32">;
+    pattern: import("@aethervtt/shard-core").FieldType<"brushed" | "cells" | "grain" | "mottle" | "stagger" | "streaks", "u8">;
+    scale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+    warp: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    detail: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    bands: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    toneRange: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    coolTint: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3, "f32">;
+    warmTint: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3, "f32">;
+    roughnessRange: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    weathering: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    weatherThreshold: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+};
+export type Variation = InferFields<typeof VARIATION_FIELDS>;
+/** A partial variation: what presets and materials write (the rest takes the defaults). */
+export type VariationInit = Partial<Variation>;
+/** The GPU struct `surface::variation::VariationUniform`, generated from VARIATION_FIELDS. */
+export declare const VariationUniform: import("@aethervtt/shard-core").ComponentDef<{
+    strength: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    seed: import("@aethervtt/shard-core").FieldType<number, "u32">;
+    pattern: import("@aethervtt/shard-core").FieldType<"brushed" | "cells" | "grain" | "mottle" | "stagger" | "streaks", "u8">;
+    scale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+    warp: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    detail: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    bands: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    toneRange: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    coolTint: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3, "f32">;
+    warmTint: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3, "f32">;
+    roughnessRange: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    weathering: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    weatherThreshold: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+}>;
+/** Where the WGSL struct lives: a material's generated module imports it from here. */
+export declare const VARIATION_STRUCT = "surface::variation::VariationUniform";
+/**
+ * Tuned variations, seeded from Aether's eight recipes (its patch sizes converted from pixels at
+ * 1.5 m per 70 px, its global intensity of 0.5 as `strength`). Plain data: spread one and
+ * override, or add your own. Nothing in the shader knows their names.
+ */
+export declare const SURFACE_PRESETS: Record<string, Variation>;
+export interface SurfaceSample {
+    /** RGB multiplier for the base colour. */
+    tint: [number, number, number];
+    /** Added to roughness. */
+    roughness: number;
+}
+/**
+ * The variation at surface point `p` (metres): a tint multiplier and a roughness offset. The CPU
+ * mirror of WGSL `surface_variation`, for tests and for tools that preview a preset.
+ */
+export declare function surfaceVariation(v: Variation, p: ArrayLike<number>, out?: SurfaceSample): SurfaceSample;