@aethervtt/shard-render 0.0.1

package/dist/debug-views.d.ts

@@ -0,0 +1,60 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import type { GpuContext } from '@aethervtt/shard-gpu';
+import type { CapturedBuffer } from './graph.js';
+/** Debug views a camera can render instead of its normal image. */
+export declare const DEBUG_VIEWS: {
+    readonly none: 0;
+    readonly clusters: 1;
+    readonly cascades: 2;
+    readonly lod: 3;
+    readonly culling: 0;
+};
+/** G-buffer channels, shown through the `gbuffer-debug` buffer (deferred or forward views). */
+export declare const GBUFFER_VIEWS: readonly ['albedo', 'normal', 'roughness', 'metallic', 'emissive'];
+export type DebugView = keyof typeof DEBUG_VIEWS | (typeof GBUFFER_VIEWS)[number];
+/**
+ * Switches a camera's debug view; it stays until switched back to 'none'. Lighting views replace
+ * the image; G-buffer channels render into the `gbuffer-debug` buffer (see `captureBuffer`).
+ */
+export declare function setDebugView(world: World, camera: Entity, view: DebugView): void;
+/** The culling section of `render.describe`: per view, what was culled and what it cost. */
+export declare function describeCulling(world: World): {
+    mode: string;
+    instances: number;
+    batches: number;
+    lodSets: number;
+    uploadedBytes: number;
+    cpuMs: {
+        total: number;
+        systems: Record<string, number>;
+    } | undefined;
+    gpuMs: number | undefined;
+    views: Record<string, unknown>;
+} | undefined;
+/** Copies one layer of a texture to the CPU as floats (depth in R). */
+export declare function readTextureLayer(gpu: GpuContext, texture: GPUTexture, layer: number): Promise<CapturedBuffer>;
+/** Reads a GPU buffer back to the CPU (tests and debugging). */
+export declare function readBuffer(gpu: GpuContext, source: GPUBuffer, size: number): Promise<ArrayBuffer>;
+/**
+ * A light's shadow map as floats (reversed-Z depth in R). Directional lights: the cascades of
+ * `camera` (default: the first camera view), `layer` = cascade. Spots: its map. Points: `layer` =
+ * face (+X, -X, +Y, -Y, +Z, -Z).
+ */
+export declare function captureShadowMap(world: World, light: Entity, layer?: number, camera?: Entity): Promise<CapturedBuffer>;
+/** The lighting section of `render.describe`: per view lights, clusters, shadows, uploads. */
+export declare function describeLighting(world: World): {
+    directional: number;
+    shadowedDirectional: number | null;
+    pointAndSpot: number;
+    uploadedLights: number;
+    uploadedBytes: number;
+    shadowBudget: {
+        spots: string;
+        points: string;
+        overBudget: {
+            entity: number;
+            type: string;
+        }[];
+    };
+    views: Record<string, unknown>;
+} | undefined;

package/dist/debug-views.js

@@ -0,0 +1,197 @@
+import {
+  ProfilerResource,
+  ShardError
+} from "@aethervtt/shard-core";
+import { Culler } from "./culling.js";
+import { ForwardStateResource } from "./forward.js";
+import { Instances } from "./instances.js";
+import { DirectionalLight, LightingSettings, Lights, PointLight, SpotLight } from "./lights.js";
+import { Gpu, Views } from "./plugin.js";
+import { BYTES_PER_TEXEL, toFloats } from "./readback.js";
+import { ShadowsResource } from "./shadows.js";
+import { Cameras, cameraOf } from "./view.js";
+const DEBUG_VIEWS = { none: 0, clusters: 1, cascades: 2, lod: 3, culling: 0 };
+const GBUFFER_VIEWS = ["albedo", "normal", "roughness", "metallic", "emissive"];
+function setDebugView(world, camera, view) {
+  const cam = world.resource(Cameras).get(camera);
+  if (!cam) {
+    throw new ShardError("render/unknown-camera", `Entity ${camera} is not a rendered camera`, {
+      hint: "Pass a Camera3d entity that has rendered at least one frame."
+    });
+  }
+  const channel = GBUFFER_VIEWS.indexOf(view);
+  cam.gbufferDebug = channel;
+  cam.debug = channel >= 0 ? 0 : DEBUG_VIEWS[view];
+  if (view === "culling") {
+    cam.frozenFrustum = Float32Array.from(cam.frustum);
+    cam.frozenPosition = Float32Array.from(cam.position);
+  } else {
+    cam.frozenFrustum = void 0;
+    cam.frozenPosition = void 0;
+  }
+}
+const PREP_SYSTEMS = ["render/prepare-instances", "render/forward-queue", "render/upload-visible"];
+function prepMs(profiler) {
+  if (!profiler) return void 0;
+  const systems = {};
+  let total = 0;
+  for (const name of PREP_SYSTEMS) {
+    const ms = profiler.timing(name)?.avg ?? 0;
+    systems[name] = ms;
+    total += ms;
+  }
+  return { total, systems };
+}
+function describeCulling(world) {
+  const store = world.tryResource(Instances);
+  const culler = world.tryResource(Culler);
+  const state = world.tryResource(ForwardStateResource);
+  if (!store || !culler || !state) return void 0;
+  const profiler = world.tryResource(ProfilerResource);
+  const views = {};
+  for (const view of world.resource(Views).list) {
+    const cam = cameraOf(view);
+    if (!cam) continue;
+    const lods = culler.lodCounts.get(cam.draws);
+    views[view.name] = {
+      mode: cam.draws.cullView >= 0 ? "gpu" : "cpu",
+      batches: cam.draws.length,
+      visible: cam.draws.visible + cam.forwardOnly.visible + cam.transparent.visible,
+      perLod: lods ? [...lods].map((n) => n ?? 0) : void 0,
+      frozen: cam.frozenFrustum !== void 0,
+      shadowViews: state.views.get(view.name)?.cascades.count ?? 0
+    };
+  }
+  return {
+    mode: culler.active ? "gpu" : "cpu",
+    instances: store.live,
+    batches: store.batches.filter((b) => b.count > 0).length,
+    lodSets: store.lodSets.length,
+    uploadedBytes: store.uploadedBytes,
+    cpuMs: prepMs(profiler),
+    gpuMs: profiler?.timing("gpu:instance-cull")?.avg,
+    views
+  };
+}
+async function readTextureLayer(gpu, texture, layer) {
+  const { width, height, format } = texture;
+  const bpp = BYTES_PER_TEXEL[format] ?? 4;
+  const bytesPerRow = Math.ceil(width * bpp / 256) * 256;
+  const buffer = gpu.device.createBuffer({
+    label: "capture/layer",
+    size: bytesPerRow * height,
+    usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
+  });
+  const encoder = gpu.device.createCommandEncoder({ label: "capture/layer" });
+  encoder.copyTextureToBuffer(
+    {
+      texture,
+      origin: { x: 0, y: 0, z: layer },
+      aspect: format.startsWith("depth") ? "depth-only" : "all"
+    },
+    { buffer, bytesPerRow },
+    [width, height, 1]
+  );
+  gpu.device.queue.submit([encoder.finish()]);
+  await buffer.mapAsync(GPUMapMode.READ);
+  const src = buffer.getMappedRange().slice(0);
+  buffer.unmap();
+  buffer.destroy();
+  const data = new Float32Array(width * height * 4);
+  for (let y = 0; y < height; y++) {
+    toFloats(src.slice(y * bytesPerRow, (y + 1) * bytesPerRow), format, width, data, y * width * 4);
+  }
+  return { width, height, format, data };
+}
+async function readBuffer(gpu, source, size) {
+  const buffer = gpu.device.createBuffer({
+    label: "readback",
+    size,
+    usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ
+  });
+  const encoder = gpu.device.createCommandEncoder({ label: "readback" });
+  encoder.copyBufferToBuffer(source, 0, buffer, 0, size);
+  gpu.device.queue.submit([encoder.finish()]);
+  await buffer.mapAsync(GPUMapMode.READ);
+  const out = buffer.getMappedRange().slice(0);
+  buffer.unmap();
+  buffer.destroy();
+  return out;
+}
+async function captureShadowMap(world, light, layer = 0, camera) {
+  const gpu = world.resource(Gpu);
+  const lights = world.resource(Lights);
+  const local = world.resource(ShadowsResource).local;
+  const noShadow = (why) => new ShardError("render/no-shadow-map", `Light ${light} has no shadow map: ${why}`, {
+    hint: "Set shadows: true on the light, and check render.describe for the shadow budget."
+  });
+  if (world.isAlive(light) && world.has(light, DirectionalLight)) {
+    if (lights.shadowSun?.entity !== light) throw noShadow("not the shadowed directional light");
+    const state = world.resource(ForwardStateResource);
+    const viewName = camera !== void 0 ? `camera:${camera}` : world.resource(Views).list.find((v) => cameraOf(v))?.name;
+    const pv = viewName ? state.views.get(viewName) : void 0;
+    if (!pv?.cascades.texture || layer >= pv.cascades.count) throw noShadow("no cascades rendered");
+    return readTextureLayer(gpu, pv.cascades.texture, layer);
+  }
+  const r = lights.byEntity.get(light);
+  if (!r) throw noShadow("not a light");
+  if (r.shadowIndex < 0) throw noShadow("no shadow map this frame (budget or shadows off)");
+  if (r.kind === 1) return readTextureLayer(gpu, local.spotTexture, r.shadowIndex);
+  return readTextureLayer(gpu, local.pointTexture, r.shadowIndex * 6 + Math.min(5, layer));
+}
+function describeLighting(world) {
+  const lights = world.tryResource(Lights);
+  const state = world.tryResource(ForwardStateResource);
+  const shadows = world.tryResource(ShadowsResource);
+  if (!lights || !state || !shadows) return void 0;
+  const settings = world.resource(LightingSettings);
+  const local = shadows.local;
+  const views = {};
+  for (const view of world.resource(Views).list) {
+    const cam = cameraOf(view);
+    const pv = state.views.get(view.name);
+    if (!cam || !pv) continue;
+    views[view.name] = {
+      lights: pv.lightList.records.map((r) => ({
+        entity: r.entity,
+        type: r.kind === 1 ? "spot" : "point",
+        intensity: r.intensity,
+        range: r.range,
+        castsShadows: r.shadowIndex >= 0
+      })),
+      clusters: {
+        grid: [16, 9, 24],
+        maxLightsPerCluster: pv.clusters.latest.maxLightsPerCluster,
+        overflows: pv.clusters.latest.overflows
+      },
+      cascades: pv.cascades.count,
+      cascadeSplits: [...pv.cascades.splits.subarray(0, pv.cascades.count)]
+    };
+  }
+  return {
+    directional: lights.directionalCount,
+    shadowedDirectional: lights.shadowSun?.entity ?? null,
+    pointAndSpot: lights.byEntity.size,
+    uploadedLights: lights.uploadedLights,
+    uploadedBytes: lights.uploadedBytes,
+    shadowBudget: {
+      spots: `${local.spots.length}/${settings.maxShadowedSpots}`,
+      points: `${local.points.length}/${settings.maxShadowedPoints}`,
+      overBudget: local.overBudget.map((r) => ({
+        entity: r.entity,
+        type: world.has(r.entity, SpotLight) ? "spot" : world.has(r.entity, PointLight) ? "point" : "unknown"
+      }))
+    },
+    views
+  };
+}
+export {
+  DEBUG_VIEWS,
+  GBUFFER_VIEWS,
+  captureShadowMap,
+  describeCulling,
+  describeLighting,
+  readBuffer,
+  readTextureLayer,
+  setDebugView
+};

package/dist/deferred-plugin.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The deferred path (spec 0021): cameras with `RenderPath { mode: 'deferred' }` shade opaque
+ * geometry through a G-buffer. Without it they render forward.
+ */
+export declare const deferredPlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/deferred-plugin.js

@@ -0,0 +1,20 @@
+import { definePlugin } from "@aethervtt/shard-runtime";
+import { addDeferredNodes } from "./deferred.js";
+import { DEFERRED_SHADERS } from "./deferred-shaders.js";
+import { Shaders } from "./plugin.js";
+import { registerShaders } from "./shaders.js";
+import { DeferredPath } from "./view.js";
+const deferredPlugin = definePlugin({
+  name: "render/deferred",
+  dependencies: ["render/forward"],
+  build(app) {
+    app.insertResource(DeferredPath, { installed: true });
+  },
+  ready(app) {
+    registerShaders(app.world.resource(Shaders), DEFERRED_SHADERS);
+    addDeferredNodes(app);
+  }
+});
+export {
+  deferredPlugin
+};

package/dist/deferred-shaders.d.ts

@@ -0,0 +1,2 @@
+/** WGSL for the deferred path: G-buffer packing, the G-buffer pass, and the lighting pass. */
+export declare const DEFERRED_SHADERS: Record<string, string>;

package/dist/deferred-shaders.js

@@ -0,0 +1,151 @@
+const DEFERRED_SHADERS = {
+  "shard::pbr::gbuffer": `
+import shard::pbr::types::PbrInput;
+
+/**
+ * The G-buffer layout, in one place:
+ *   gbuffer0 (rgba8unorm-srgb): base color, occlusion
+ *   gbuffer1 (rgba16float): octahedral normal (xy), roughness, metallic (+2 when shadows are off)
+ *   gbuffer2 (rg11b10ufloat): emissive, pre-exposed
+ */
+struct GBufferOutput {
+  @location(0) albedo: vec4f,
+  @location(1) normal: vec4f,
+  @location(2) emissive: vec4f,
+}
+
+fn oct_wrap(v: vec2f) -> vec2f {
+  return (1.0 - abs(v.yx)) * select(vec2f(-1.0), vec2f(1.0), v >= vec2f(0.0));
+}
+
+fn oct_encode(n: vec3f) -> vec2f {
+  let p = n.xy / (abs(n.x) + abs(n.y) + abs(n.z));
+  return select(p, oct_wrap(p), n.z < 0.0);
+}
+
+fn oct_decode(e: vec2f) -> vec3f {
+  var n = vec3f(e, 1.0 - abs(e.x) - abs(e.y));
+  let t = max(-n.z, 0.0);
+  n.x += select(t, -t, n.x >= 0.0);
+  n.y += select(t, -t, n.y >= 0.0);
+  return normalize(n);
+}
+
+fn pack_gbuffer(p: PbrInput, receives_shadows: bool, exposure: f32) -> GBufferOutput {
+  var out: GBufferOutput;
+  out.albedo = vec4f(p.base_color, p.occlusion);
+  out.normal = vec4f(oct_encode(p.normal), p.roughness, p.metallic + select(2.0, 0.0, receives_shadows));
+  out.emissive = vec4f(p.emissive * exposure, 1.0);
+  return out;
+}
+
+struct GBufferSample {
+  p: PbrInput,
+  receives_shadows: bool,
+  /** Pre-exposed emissive. */
+  emissive: vec3f,
+}
+
+fn unpack_gbuffer(albedo: vec4f, normal: vec4f, emissive: vec4f) -> GBufferSample {
+  var s: GBufferSample;
+  s.p.base_color = albedo.rgb;
+  s.p.alpha = 1.0;
+  s.p.occlusion = albedo.a;
+  s.p.normal = oct_decode(normal.xy);
+  s.p.roughness = normal.z;
+  s.receives_shadows = normal.w < 1.5;
+  s.p.metallic = select(normal.w - 2.0, normal.w, s.receives_shadows);
+  s.p.emissive = vec3f(0.0);
+  s.emissive = emissive.rgb;
+  return s;
+}`,
+  "shard::pbr::gbuffer_pass": `
+import shard::view::view;
+import shard::pbr::types::VertexOutput;
+import shard::mesh::mesh_vertex_at;
+import shard::pbr::material::pbr_input;
+import shard::pbr::standard::material;
+import shard::pbr::gbuffer::{ GBufferOutput, pack_gbuffer };
+
+const FLAG_RECEIVER: u32 = 4u;
+
+@vertex fn vs(
+  @builtin(instance_index) instance_index: u32,
+  @builtin(vertex_index) vertex_index: u32,
+  @location(0) position: vec3f,
+  @location(1) normal: vec3f,
+  @location(2) uv: vec2f,
+  @location(3) uv1: vec2f,
+  @location(4) tangent: vec4f,
+) -> VertexOutput {
+  var out = mesh_vertex_at(instance_index, vertex_index, position, normal, uv, uv1, tangent);
+  out.clip = view.viewProj * vec4f(out.world_position, 1.0);
+  return out;
+}
+
+/** The surface stage only: what the material makes of the surface, packed for lighting. */
+@fragment fn fs(in: VertexOutput) -> GBufferOutput {
+  let p = pbr_input(in);
+  @if(MASK) if (p.alpha < material.alphaCutoff) { discard; }
+  return pack_gbuffer(p, (in.flags & FLAG_RECEIVER) != 0u, view.exposure);
+}`,
+  "shard::pbr::deferred_lighting": `
+import shard::view::view;
+import shard::pbr::gbuffer::unpack_gbuffer;
+import shard::pbr::lighting::apply_lighting;
+
+@group(1) @binding(0) var gbuffer0: texture_2d<f32>;
+@group(1) @binding(1) var gbuffer1: texture_2d<f32>;
+@group(1) @binding(2) var gbuffer2: texture_2d<f32>;
+@group(1) @binding(3) var gbuffer_depth: texture_depth_2d;
+
+const FLAG_RECEIVER: u32 = 4u;
+
+@vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {
+  let xy = vec2f(f32((i << 1u) & 2u), f32(i & 2u));
+  return vec4f(xy * 2.0 - 1.0, 0.0, 1.0);
+}
+
+/** One lighting evaluation per pixel: the same lighting stage the forward path runs. */
+@fragment fn fs(@builtin(position) frag: vec4f) -> @location(0) vec4f {
+  let px = vec2i(frag.xy);
+  let depth = textureLoad(gbuffer_depth, px, 0);
+  // Reversed-Z: 0 is the far background, left for the sky.
+  if (depth <= 0.0) { discard; }
+  let ndc = vec2f(frag.x * view.viewport.z * 2.0 - 1.0, 1.0 - frag.y * view.viewport.w * 2.0);
+  let world = view.invViewProj * vec4f(ndc, depth, 1.0);
+  let position = world.xyz / world.w;
+  let s = unpack_gbuffer(textureLoad(gbuffer0, px, 0), textureLoad(gbuffer1, px, 0), textureLoad(gbuffer2, px, 0));
+  let flags = select(0u, FLAG_RECEIVER, s.receives_shadows);
+  let color = apply_lighting(s.p, position, frag, flags) * view.exposure + s.emissive;
+  return vec4f(color, 1.0);
+}`,
+  "shard::debug::gbuffer": `
+import shard::pbr::gbuffer::unpack_gbuffer;
+
+@group(0) @binding(0) var gbuffer0: texture_2d<f32>;
+@group(0) @binding(1) var gbuffer1: texture_2d<f32>;
+@group(0) @binding(2) var gbuffer2: texture_2d<f32>;
+@group(0) @binding(3) var<uniform> channel: vec4u;
+
+@vertex fn vs(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {
+  let xy = vec2f(f32((i << 1u) & 2u), f32(i & 2u));
+  return vec4f(xy * 2.0 - 1.0, 0.0, 1.0);
+}
+
+/** A G-buffer channel as a viewable image: albedo, normal, roughness, metallic, emissive. */
+@fragment fn fs(@builtin(position) frag: vec4f) -> @location(0) vec4f {
+  let px = vec2i(frag.xy);
+  let s = unpack_gbuffer(textureLoad(gbuffer0, px, 0), textureLoad(gbuffer1, px, 0), textureLoad(gbuffer2, px, 0));
+  switch channel.x {
+    case 0u: { return vec4f(s.p.base_color, 1.0); }
+    case 1u: { return vec4f(s.p.normal * 0.5 + 0.5, 1.0); }
+    case 2u: { return vec4f(vec3f(s.p.roughness), 1.0); }
+    case 3u: { return vec4f(vec3f(s.p.metallic), 1.0); }
+    default: { return vec4f(s.emissive / (1.0 + s.emissive), 1.0); }
+  }
+}`
+};
+export {
+  DEFERRED_SHADERS
+};

package/dist/deferred.d.ts

@@ -0,0 +1,22 @@
+import { type World } from '@aethervtt/shard-core';
+import type { CapturedImage } from './graph.js';
+/** G-buffer channels a capture can show. */
+export declare const GBUFFER_CHANNELS: readonly ['albedo', 'normal', 'roughness', 'metallic', 'emissive'];
+export type GBufferChannel = (typeof GBUFFER_CHANNELS)[number];
+/**
+ * A G-buffer channel of a camera, as an image, after the next frame renders it. Deferred views show
+ * their own G-buffer; forward views fill one. The first time, set the channel with `setDebugView`
+ * and render until shaders compile (as `render.capture` does), or the capture may be blank.
+ */
+export declare function captureGBuffer(world: World, camera: number, channel: GBufferChannel): Promise<CapturedImage>;
+/** The deferred section of `render.describe`: path, G-buffer memory, and what drew forward. */
+export declare function describeDeferred(world: World): {
+    views: Record<string, unknown>;
+} | undefined;
+/**
+ * The deferred rendering path's graph nodes, installed by the forward renderer: a camera chooses
+ * it with `RenderPath`, sharing lights, shadows, environments, and materials.
+ */
+export declare function addDeferredNodes(app: {
+    world: World;
+}): void;