@aethervtt/shard-render 0.0.1

package/dist/environment.js

@@ -0,0 +1,529 @@
+import {
+  defineComponent,
+  defineResource,
+  defineSystem,
+  t
+} from "@aethervtt/shard-core";
+import { GpuBuffer } from "@aethervtt/shard-gpu";
+import { Textures } from "@aethervtt/shard-texture";
+import { Atmospheres } from "./atmosphere-state.js";
+import {
+  Environment,
+  EnvironmentStore,
+  Environments,
+  environmentParams,
+  LUT_SIZE,
+  REBAKE_FRAMES,
+  SKY_SIZE,
+  SOURCE_SIZE,
+  SPECULAR_MIPS,
+  SPECULAR_SIZE
+} from "./environment-state.js";
+import { GpuAssetsResource } from "./gpu-assets.js";
+import { Gpu, Shaders, Views } from "./plugin.js";
+import { cameraOf } from "./view.js";
+const EnvironmentPresets = {
+  "overcast-sky": 2e3,
+  "clear-sky": 8e3
+};
+const EnvironmentMap = defineComponent(
+  "render/EnvironmentMap",
+  {
+    texture: t.handle("Texture", {
+      description: 'An HDR texture: an equirectangular .hdr (usage "hdr") or a cube-map KTX2.'
+    }),
+    intensity: t.f32({
+      default: 5e3,
+      min: 0,
+      unit: "cd/m\xB2",
+      presets: EnvironmentPresets,
+      description: "Luminance a texel value of 1.0 represents. HDR files are relative; this ties them to physical units. Presets: overcast-sky 2000, clear-sky 8000."
+    }),
+    rotation: t.f32({ unit: "deg", description: "Rotation of the environment about +Y." })
+  },
+  {
+    description: "Image-based lighting for a camera: ambient light and reflections from an HDR environment, prefiltered on the GPU."
+  }
+);
+const Skybox = defineComponent(
+  "render/Skybox",
+  {
+    brightness: t.f32({
+      default: 1,
+      min: 0,
+      description: "Multiplies the environment's luminance in the background (not its lighting)."
+    })
+  },
+  {
+    description: "Draws the camera's environment map behind everything. Replaces the clear color."
+  }
+);
+const ProceduralSky = defineComponent(
+  "render/ProceduralSky",
+  {
+    turbidity: t.f32({
+      default: 2,
+      min: 1,
+      max: 10,
+      description: "Haze: aerosol density. 1 is very clear, 10 is hazy."
+    }),
+    rayleigh: t.f32({
+      default: 1,
+      min: 0,
+      description: "Multiplies molecular (blue) scattering."
+    }),
+    mie: t.f32({ default: 1, min: 0, description: "Multiplies aerosol (white haze) scattering." }),
+    groundAlbedo: t.color({
+      default: [0.3, 0.3, 0.3, 1],
+      description: "Ground below the horizon."
+    }),
+    sunDiskSize: t.f32({
+      default: 1,
+      min: 0,
+      description: "Sun disk size, as a multiple of the DirectionalLight's angularDiameter (the Sun's 0.53\xB0). 0 hides the disk."
+    })
+  },
+  {
+    description: "An Earth sky seen from 10 m above the ground wherever the camera is: an Atmosphere (spec 0044) lit by the two brightest DirectionalLights, in cd/m\xB2 consistent with their illuminance. Drawn as the background, and baked into the environment so image-based lighting follows the time of day. For skies you can fly out of, put an Atmosphere on the planet instead."
+  }
+);
+const DefaultEnvironment = defineResource(
+  "render/DefaultEnvironment",
+  {
+    description: "The environment (map or procedural sky) for cameras that have none. AmbientLight is the fallback when neither is set.",
+    init: () => ({ map: null, sky: null, background: true })
+  }
+);
+const prepareEnvironments = defineSystem({
+  name: "render/prepare-environments",
+  description: "Picks each camera environment and queues GPU prefiltering when sources change.",
+  run: (_, world) => {
+    const store = world.resource(Environments);
+    const gpu = world.resource(Gpu);
+    store.ensure(gpu);
+    store.frame++;
+    store.cameras.clear();
+    const defaults = world.resource(DefaultEnvironment);
+    const textures = world.tryResource(Textures);
+    const assets = world.resource(GpuAssetsResource);
+    const atmospheres = world.tryResource(Atmospheres);
+    for (const view of world.resource(Views).list) {
+      const cam = cameraOf(view);
+      if (!cam) continue;
+      const e = cam.entity;
+      const own = world.isAlive(e);
+      const map = own && world.has(e, EnvironmentMap) ? world.get(e, EnvironmentMap) : void 0;
+      const skybox = own && world.has(e, Skybox) ? world.get(e, Skybox).brightness : -1;
+      let entry = {
+        environment: void 0,
+        intensity: 0,
+        rotation: 0,
+        background: -1,
+        sky: false,
+        backdrop: void 0
+      };
+      const mapEnvironment = (value) => {
+        const texture = textures?.get(value.texture);
+        if (!texture) return void 0;
+        const key = `map:${idOf(texture)}:${texture.version}`;
+        let env = store.environments.get(key);
+        if (!env) {
+          for (const [k, old] of store.environments) {
+            if (old.input === texture) {
+              old.destroy();
+              store.environments.delete(k);
+            }
+          }
+          env = new Environment(gpu, "map");
+          env.key = key;
+          env.input = texture;
+          store.environments.set(key, env);
+          store.pending.push(env);
+        }
+        env.lastUsed = store.frame;
+        assets.texture(texture);
+        return env;
+      };
+      const useMap = (value, background) => {
+        const env = mapEnvironment(value);
+        if (!env) return;
+        entry = {
+          environment: env,
+          intensity: value.intensity,
+          rotation: value.rotation * Math.PI / 180,
+          background,
+          sky: false,
+          backdrop: void 0
+        };
+      };
+      const ca = atmospheres?.cameras.get(e);
+      if (ca?.primary) {
+        const id = `atmosphere@${e}`;
+        let env = store.environments.get(id);
+        if (!env) {
+          env = new Environment(gpu, "atmosphere");
+          store.environments.set(id, env);
+        }
+        env.atmosphere = ca;
+        const same = env.key.slice(0, env.key.indexOf("|")) === ca.bakeKey.slice(0, ca.bakeKey.indexOf("|"));
+        if (env.key !== ca.bakeKey && (!same || store.frame - env.queuedFrame >= REBAKE_FRAMES)) {
+          env.key = ca.bakeKey;
+          env.queuedFrame = store.frame;
+          env.state = "pending";
+          if (!store.pending.includes(env)) store.pending.push(env);
+        }
+        env.lastUsed = store.frame;
+        let backdrop;
+        const behind = map?.texture && skybox >= 0 ? map : !map?.texture && defaults.map?.texture && defaults.background ? defaults.map : void 0;
+        const backdropEnv = behind ? mapEnvironment(behind) : void 0;
+        if (behind && backdropEnv) {
+          backdrop = {
+            environment: backdropEnv,
+            intensity: behind.intensity * (skybox >= 0 ? skybox : 1),
+            rotation: behind.rotation * Math.PI / 180
+          };
+        }
+        entry = {
+          environment: env,
+          intensity: 1,
+          rotation: 0,
+          background: ca.background,
+          sky: true,
+          backdrop
+        };
+      } else if (map?.texture) useMap(map, skybox);
+      else if (defaults.map?.texture)
+        useMap(defaults.map, defaults.background ? Math.max(skybox, 1) : skybox);
+      store.cameras.set(e, entry);
+      view.data.environment = entry;
+    }
+    for (const [key, env] of store.environments) {
+      if (store.frame - env.lastUsed > 120) {
+        env.destroy();
+        store.environments.delete(key);
+      }
+    }
+  }
+});
+const ids = /* @__PURE__ */ new WeakMap();
+let nextId = 1;
+function idOf(o) {
+  let id = ids.get(o);
+  if (id === void 0) {
+    id = nextId++;
+    ids.set(o, id);
+  }
+  return id;
+}
+function storage2dArray(binding) {
+  return {
+    binding,
+    visibility: GPUShaderStage.COMPUTE,
+    storageTexture: { access: "write-only", format: "rgba16float", viewDimension: "2d-array" }
+  };
+}
+function environmentPipelines(gpu, world) {
+  const shaders = world.resource(Shaders);
+  const C = GPUShaderStage.COMPUTE;
+  const layouts = {
+    equirect: gpu.layouts.bindGroupLayout({
+      label: "env/equirect",
+      entries: [
+        { binding: 0, visibility: C, texture: { sampleType: "float" } },
+        { binding: 1, visibility: C, sampler: { type: "filtering" } },
+        storage2dArray(2)
+      ]
+    }),
+    cube: gpu.layouts.bindGroupLayout({
+      label: "env/cube",
+      entries: [
+        { binding: 0, visibility: C, texture: { sampleType: "float", viewDimension: "cube" } },
+        { binding: 1, visibility: C, sampler: { type: "filtering" } },
+        storage2dArray(2)
+      ]
+    }),
+    downsample: gpu.layouts.bindGroupLayout({
+      label: "env/downsample",
+      entries: [
+        { binding: 0, visibility: C, texture: { sampleType: "float", viewDimension: "2d-array" } },
+        storage2dArray(1)
+      ]
+    }),
+    sh: gpu.layouts.bindGroupLayout({
+      label: "env/sh",
+      entries: [
+        { binding: 0, visibility: C, texture: { sampleType: "float", viewDimension: "2d-array" } },
+        { binding: 1, visibility: C, buffer: { type: "storage" } }
+      ]
+    }),
+    specular: gpu.layouts.bindGroupLayout({
+      label: "env/specular",
+      entries: [
+        { binding: 0, visibility: C, texture: { sampleType: "float", viewDimension: "cube" } },
+        { binding: 1, visibility: C, sampler: { type: "filtering" } },
+        storage2dArray(2),
+        { binding: 3, visibility: C, buffer: { type: "uniform" } }
+      ]
+    }),
+    lut: gpu.layouts.bindGroupLayout({
+      label: "env/lut",
+      entries: [
+        {
+          binding: 0,
+          visibility: C,
+          storageTexture: { access: "write-only", format: "rgba16float", viewDimension: "2d" }
+        }
+      ]
+    })
+  };
+  const pipelines = {};
+  const modules = {
+    equirect: "shard::env::from_equirect",
+    cube: "shard::env::from_cube",
+    downsample: "shard::env::downsample",
+    sh: "shard::env::sh",
+    specular: "shard::env::specular",
+    lut: "shard::env::brdf_lut"
+  };
+  let missing = false;
+  for (const [name, root] of Object.entries(modules)) {
+    const module = shaders.module(gpu, { root });
+    if (!module) {
+      missing = true;
+      continue;
+    }
+    const p = gpu.pipelines.compute({
+      label: `env/${name}`,
+      layout: gpu.layouts.pipelineLayout({
+        label: `env/${name}`,
+        bindGroupLayouts: [layouts[name]]
+      }),
+      compute: { module, entryPoint: "main" }
+    });
+    if (!p) missing = true;
+    else pipelines[name] = p;
+  }
+  return missing ? void 0 : { layouts, pipelines };
+}
+const specData = new Float32Array(4);
+const environmentBakers = /* @__PURE__ */ new Map();
+function runEnvironmentWork(ctx) {
+  const world = ctx.world;
+  const gpu = ctx.gpu;
+  const store = world.resource(Environments);
+  if (store.ranFrame === store.frame) return;
+  if (store.pending.length === 0 && store.lutReady) {
+    store.ranFrame = store.frame;
+    return;
+  }
+  const p = environmentPipelines(gpu, world);
+  if (!p) {
+    gpu.pipelines.skipped++;
+    return;
+  }
+  store.ranFrame = store.frame;
+  const device = gpu.device;
+  const pass = ctx.encoder.beginComputePass({
+    label: "environment/prefilter",
+    timestampWrites: ctx.timestamps("environment/prefilter")
+  });
+  if (!store.lutReady) {
+    pass.setPipeline(p.pipelines.lut);
+    pass.setBindGroup(
+      0,
+      device.createBindGroup({
+        layout: p.layouts.lut,
+        entries: [{ binding: 0, resource: store.lut.createView() }]
+      })
+    );
+    pass.dispatchWorkgroups(LUT_SIZE / 8, LUT_SIZE / 8);
+    store.lutReady = true;
+  }
+  const assets = world.resource(GpuAssetsResource);
+  const sampler = store.sampler;
+  const wrapU = gpu.layouts.sampler({
+    label: "environment/equirect",
+    magFilter: "linear",
+    minFilter: "linear",
+    addressModeU: "repeat",
+    addressModeV: "clamp-to-edge"
+  });
+  const done = [];
+  for (const env of store.pending) {
+    const size = env.size;
+    const level0 = env.source.createView({
+      dimension: "2d-array",
+      baseMipLevel: 0,
+      mipLevelCount: 1
+    });
+    if (env.kind === "map") {
+      const input = env.input && assets.texture(env.input);
+      if (!input) continue;
+      const cube = env.input.faces === 6;
+      pass.setPipeline(cube ? p.pipelines.cube : p.pipelines.equirect);
+      pass.setBindGroup(
+        0,
+        device.createBindGroup({
+          layout: cube ? p.layouts.cube : p.layouts.equirect,
+          entries: [
+            { binding: 0, resource: input.linear },
+            { binding: 1, resource: cube ? sampler : wrapU },
+            { binding: 2, resource: level0 }
+          ]
+        })
+      );
+      pass.dispatchWorkgroups(size / 8, size / 8, 6);
+    } else {
+      const bake = environmentBakers.get(env.kind);
+      if (!bake?.(ctx, pass, env, level0)) continue;
+    }
+    const mips = Math.log2(size) + 1;
+    pass.setPipeline(p.pipelines.downsample);
+    for (let m = 1; m < mips; m++) {
+      const dim = Math.max(1, size >> m);
+      pass.setBindGroup(
+        0,
+        device.createBindGroup({
+          layout: p.layouts.downsample,
+          entries: [
+            {
+              binding: 0,
+              resource: env.source.createView({
+                dimension: "2d-array",
+                baseMipLevel: m - 1,
+                mipLevelCount: 1
+              })
+            },
+            {
+              binding: 1,
+              resource: env.source.createView({
+                dimension: "2d-array",
+                baseMipLevel: m,
+                mipLevelCount: 1
+              })
+            }
+          ]
+        })
+      );
+      pass.dispatchWorkgroups(Math.ceil(dim / 8), Math.ceil(dim / 8), 6);
+    }
+    const shLevel = Math.max(0, Math.log2(size) - 5);
+    pass.setPipeline(p.pipelines.sh);
+    pass.setBindGroup(
+      0,
+      device.createBindGroup({
+        layout: p.layouts.sh,
+        entries: [
+          {
+            binding: 0,
+            resource: env.source.createView({
+              dimension: "2d-array",
+              baseMipLevel: shLevel,
+              mipLevelCount: 1
+            })
+          },
+          { binding: 1, resource: { buffer: env.sh.buffer } }
+        ]
+      })
+    );
+    pass.dispatchWorkgroups(1);
+    pass.setPipeline(p.pipelines.specular);
+    for (let m = 0; m < SPECULAR_MIPS; m++) {
+      const dim = SPECULAR_SIZE >> m;
+      const params = new GpuBuffer(gpu, {
+        label: "env/specular-params",
+        usage: GPUBufferUsage.UNIFORM,
+        size: 16
+      });
+      specData[0] = m / (SPECULAR_MIPS - 1);
+      specData[1] = size;
+      specData[2] = dim;
+      specData[3] = 0;
+      params.write(specData);
+      ctx.afterSubmit(() => params.destroy());
+      pass.setBindGroup(
+        0,
+        device.createBindGroup({
+          layout: p.layouts.specular,
+          entries: [
+            { binding: 0, resource: env.sourceView },
+            { binding: 1, resource: sampler },
+            {
+              binding: 2,
+              resource: env.specular.createView({
+                dimension: "2d-array",
+                baseMipLevel: m,
+                mipLevelCount: 1
+              })
+            },
+            { binding: 3, resource: { buffer: params.buffer } }
+          ]
+        })
+      );
+      pass.dispatchWorkgroups(Math.ceil(dim / 8), Math.ceil(dim / 8), 6);
+    }
+    env.state = "ready";
+    env.bakes++;
+    done.push(env);
+  }
+  pass.end();
+  for (const env of done) store.pending.splice(store.pending.indexOf(env), 1);
+}
+function atmosphereDescription(world, camera, ca) {
+  const s = ca.suns;
+  if (s.count === 0) return { sunIlluminance: 0 };
+  const lux = 0.2126 * s.data[4] + 0.7152 * s.data[5] + 0.0722 * s.data[6];
+  const radius = s.data[3];
+  const sky = world.isAlive(camera) ? world.tryGet(camera, ProceduralSky) : void 0;
+  return {
+    ...sky ? { sky } : {},
+    sunDirection: [s.data[0], s.data[1], s.data[2]],
+    sunIlluminance: lux,
+    // E / solid angle, before the atmosphere dims it.
+    sunDiskLuminance: radius > 0 ? lux / (Math.PI * radius * radius) : 0
+  };
+}
+function describeEnvironment(world) {
+  const store = world.tryResource(Environments);
+  if (!store) return void 0;
+  const views = {};
+  for (const view of world.resource(Views).list) {
+    const cam = cameraOf(view);
+    if (!cam) continue;
+    const entry = store.cameras.get(cam.entity);
+    const env = entry?.environment;
+    views[view.name] = {
+      tonemapping: ["aces", "agx", "pbr-neutral", "reinhard", "none"][cam.curve],
+      environment: env ? {
+        source: env.kind === "map" ? "environment-map" : env.atmosphere?.primary?.wrapper ? "procedural-sky" : "atmosphere",
+        intensity: entry.intensity,
+        rotation: entry.rotation * 180 / Math.PI,
+        prefilter: env.state,
+        bakes: env.bakes,
+        background: entry.background >= 0,
+        ...env.kind === "atmosphere" && env.atmosphere ? atmosphereDescription(world, cam.entity, env.atmosphere) : {}
+      } : { source: "ambient-light" }
+    };
+  }
+  return { views, prefilteredEnvironments: store.environments.size };
+}
+export {
+  DefaultEnvironment,
+  Environment,
+  EnvironmentMap,
+  EnvironmentPresets,
+  EnvironmentStore,
+  Environments,
+  ProceduralSky,
+  REBAKE_FRAMES,
+  SKY_SIZE,
+  SOURCE_SIZE,
+  SPECULAR_MIPS,
+  SPECULAR_SIZE,
+  Skybox,
+  describeEnvironment,
+  environmentBakers,
+  environmentParams,
+  prepareEnvironments,
+  runEnvironmentWork
+};

package/dist/forward.d.ts

@@ -0,0 +1,123 @@
+import { type World } from '@aethervtt/shard-core';
+import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
+import { type Plugin } from '@aethervtt/shard-runtime';
+import { ClusterBuffers, ViewLightList } from './clusters.js';
+import { type ColorAttachment, type NodeContext, type RenderView } from './graph.js';
+import { type DrawList, Mesh3d, MeshMaterial } from './instances.js';
+import { MaterialPipelines } from './material-pipelines.js';
+import { type RenderScaleValue } from './render-scale.js';
+import { Cascades } from './shadows.js';
+import { type CameraData } from './view.js';
+export { Mesh3d, MeshMaterial };
+/** Per camera view: uniforms, clusters, lights, and shadows, and the bind groups over them. */
+export interface ViewGpu {
+    uniform: GpuBuffer;
+    /** This frame's SSAO texture, when the camera has Ssao. */
+    ao: GPUTexture | undefined;
+    lightList: ViewLightList;
+    clusters: ClusterBuffers;
+    shadowData: GpuBuffer;
+    cascades: Cascades;
+    bindGroup: GPUBindGroup | undefined;
+    bound: string;
+    clusterBindGroup: GPUBindGroup | undefined;
+    clusterBound: string;
+}
+interface Layouts {
+    view: GPUBindGroupLayout;
+    pipeline: GPUPipelineLayout;
+    cluster: GPUBindGroupLayout;
+    clusterPipeline: GPUPipelineLayout;
+    shadowView: GPUBindGroupLayout;
+    shadowPipeline: GPUPipelineLayout;
+}
+export interface ForwardState {
+    views: Map<string, ViewGpu>;
+    viewBytes: DataView;
+    shadowFloats: Float32Array;
+    layouts: Layouts;
+    layoutGeneration: number;
+    /** A 1x1x1 depth array bound where no shadow map exists (and its generation). */
+    emptyShadow: {
+        texture: GPUTexture;
+        generation: number;
+    } | undefined;
+    white: {
+        texture: GPUTexture;
+        generation: number;
+    } | undefined;
+    shadowSampler: GPUSampler | undefined;
+    /** Frame counter, so shared passes (local shadows) run once per frame. */
+    frame: number;
+    /** Last warnings, so each is logged once per change. */
+    warned: {
+        budget: string;
+        overflow: string;
+    };
+    /** Time, delta time, and frame for shaders (`shard::globals`). */
+    globals: GpuBuffer;
+    globalsData: Float32Array;
+    pipelines: MaterialPipelines;
+    /** G-buffer color targets (the emissive format depends on the device). */
+    gbufferTargets: GPUColorTargetState[];
+    /** Whether GPU culling ran this frame (the cull node reads it). */
+    cullerActive: boolean;
+}
+export declare const ForwardStateResource: import("@aethervtt/shard-core").ResourceDef<ForwardState>;
+export declare const upload: import("@aethervtt/shard-core").SystemDef<undefined>;
+export declare const PASS_OPAQUE = 0;
+export declare const PASS_TRANSPARENT = 1;
+export declare const PASS_GBUFFER = 3;
+/** Depth, normals, and velocity for post-processing (TAA, motion blur, forward SSAO). */
+export declare const PASS_PREPASS = 5;
+/** Entity ids, normals, and depth for GPU picking (picking.ts). */
+export declare const PASS_PICK = 7;
+/**
+ * The picking pass's color targets: entity id, and the world normal with the depth in w (0 where
+ * nothing drew). Depth rides in a color target because depth formats only copy out whole.
+ */
+export declare const PICK_TARGETS: GPUColorTargetState[];
+/**
+ * Draws a list of batches with their material types' pipelines. Returns the pipeline switches, so
+ * `render.describe` can show that sorting keeps them rare.
+ */
+export declare function drawMaterials(ctx: NodeContext, state: ForwardState, pv: ViewGpu, cam: CameraData, draws: DrawList, pass: number): number;
+export declare const isCamera: (view: RenderView) => boolean;
+/** The view bind group (group 0): uniforms, lights, clusters, shadows. Rebuilt when inputs change. */
+export declare function viewBindGroup(gpu: GpuContext, world: World, pv: ViewGpu, cam: CameraData): GPUBindGroup;
+/** Prefilters environments whose source changed (once per frame, before any view draws). */
+/** Draws the environment map (Skybox) wherever no geometry was drawn. Atmospheres draw their own. */
+export declare function skyNode(state: ForwardState): {
+    kind: 'render';
+    phase: 400;
+    enabled: (view: RenderView) => boolean;
+    reads: string[];
+    writes: string[];
+    color: (view: RenderView) => readonly ColorAttachment[];
+    depth: {
+        resource: string;
+        readOnly: boolean;
+    };
+    run: (ctx: NodeContext) => void;
+};
+/**
+ * The scene color attachment for a pass that draws into the 3D scene. With MSAA it resolves into
+ * `hdr` at the end of every such pass; the graph stores the multisampled buffer only when a later
+ * pass loads it, so the last scene pass resolves for free.
+ */
+export declare function sceneColor(view: RenderView, clear?: GPUColor): readonly ColorAttachment[];
+export interface ForwardPluginOptions {
+    /** MSAA sample count: 1 or 4. Default 4. */
+    msaa?: 1 | 4;
+    /** Render scale of window cameras (0051). Default: auto, 0.5–1. */
+    renderScale?: Partial<Pick<RenderScaleValue, 'mode' | 'scale' | 'min' | 'max' | 'targetMs' | 'maxHz' | 'sharpen'>>;
+}
+/**
+ * The core of the 3D renderer: cameras, meshes, the standard material, lights, shadows, and ambient
+ * light, drawn into HDR with instancing, frustum culling, and clustered light culling, then
+ * tonemapped. Needs the render and transform plugins. Features (atmosphere, post, ...) are plugins
+ * of their own; `forwardPlugin` adds all of them.
+ */
+export declare function forwardCorePlugin(options?: ForwardPluginOptions): Plugin;
+/** rg11b10ufloat when the device can render to it, else rgba16float. */
+export declare function gbufferEmissiveFormat(gpu: GpuContext): GPUTextureFormat;