@tinypoly/gpu-renderer 0.2.5 → 0.3.0

package/src/memoryProbe.ts

@@ -0,0 +1,275 @@
+import { SLOT_CHANNELS } from "./texturePack.js";
+
+/**
+ * Memory diagnostics: what the renderer holds on the device, by label, and the page's JavaScript heap, logged at each
+ * step of a frame. Every buffer and texture the device creates is counted until it is destroyed or collected, so a
+ * step that leaves the device fuller than it found it shows up as a growing total between frames.
+ */
+
+interface Allocation {
+  label: string;
+  bytes: number;
+}
+
+const live = new Map<number, Allocation>();
+let nextId = 0;
+let enabled = false;
+
+// A resource dropped without destroy() still holds its memory until it is collected; then it leaves the count.
+const collected = typeof FinalizationRegistry === "undefined"
+  ? null
+  : new FinalizationRegistry<number>(id => live.delete(id));
+
+const MB = 1024 * 1024;
+
+/** Turns the memory log on or off. It is off by default. */
+export function setMemoryLogging(on: boolean) {
+  enabled = on;
+}
+
+/** Whether the memory log is on, so a caller can skip measuring what nobody will read. */
+export function memoryLogging(): boolean {
+  return enabled;
+}
+
+function track<T extends GPUBuffer | GPUTexture>(resource: T, label: string, bytes: number): T {
+  const id = nextId++;
+  const destroy = resource.destroy.bind(resource);
+
+  live.set(id, { label, bytes });
+  collected?.register(resource, id);
+
+  resource.destroy = () => {
+    live.delete(id);
+    destroy();
+  };
+
+  return resource;
+}
+
+/** Bytes per texel of the formats the renderer and a canvas use; anything else counts as four. */
+function texelBytes(format: GPUTextureFormat): number {
+  if (format.startsWith("rgba32")) return 16;
+  if (format.startsWith("rgba16") || format.startsWith("rg32")) return 8;
+  if (format.startsWith("r8") && !format.startsWith("r8g8")) return 1;
+
+  return 4;
+}
+
+/** Counts every buffer and texture the device creates from now on. */
+export function trackDevice(device: GPUDevice) {
+  const createBuffer = device.createBuffer.bind(device);
+  const createTexture = device.createTexture.bind(device);
+
+  device.createBuffer = descriptor =>
+    track(createBuffer(descriptor), descriptor.label || "unlabeled", descriptor.size);
+
+  device.createTexture = descriptor => {
+    const size = descriptor.size as number[] | GPUExtent3DDict;
+
+    const [width, height = 1, layers = 1] = Array.isArray(size)
+      ? size
+      : [size.width, size.height ?? 1, size.depthOrArrayLayers ?? 1];
+
+    return track(createTexture(descriptor), descriptor.label || "texture",
+      width * height * layers * texelBytes(descriptor.format) * (descriptor.mipLevelCount ?? 1));
+  };
+}
+
+const mb = (bytes: number) => Math.round(bytes / MB * 10) / 10;
+
+/** Bytes of every typed array and ArrayBuffer reachable from a value, each counted once, without crossing into DOM. */
+export function retainedBytes(value: unknown): number {
+  const seen = new Set<unknown>();
+  const buffers = new Set<ArrayBufferLike>();
+  const stack = [value];
+  let plain = 0;
+
+  while (stack.length) {
+    const item = stack.pop();
+
+    if (item === null || typeof item !== "object" || seen.has(item)) {
+      if (typeof item === "string") plain += item.length * 2;
+
+      continue;
+    }
+
+    seen.add(item);
+
+    if (ArrayBuffer.isView(item)) {
+      buffers.add(item.buffer);
+      continue;
+    }
+
+    if (item instanceof ArrayBuffer) {
+      buffers.add(item);
+      continue;
+    }
+
+    if (Array.isArray(item)) {
+      // A plain array of numbers costs eight bytes an element, which is how a large one goes unnoticed.
+      plain += item.length * 8;
+      for (const element of item) if (typeof element === "object" || typeof element === "string") stack.push(element);
+      continue;
+    }
+
+    if (typeof (item as { nodeType?: unknown }).nodeType === "number") continue;
+
+    for (const key of Object.keys(item)) stack.push((item as Record<string, unknown>)[key]);
+  }
+
+  let typed = 0;
+
+  for (const buffer of buffers) typed += buffer.byteLength;
+
+  return typed + plain;
+}
+
+/** What the device holds, in MB, with the largest labels first. */
+export function deviceMemory(): { totalMB: number; byLabel: Record<string, number> } {
+  const byLabel = new Map<string, number>();
+  let total = 0;
+
+  for (const { label, bytes } of live.values()) {
+    total += bytes;
+    byLabel.set(label, (byLabel.get(label) ?? 0) + bytes);
+  }
+
+  const sorted = [...byLabel].sort((a, b) => b[1] - a[1]).slice(0, 12);
+
+  return { totalMB: mb(total), byLabel: Object.fromEntries(sorted.map(([label, bytes]) => [label, mb(bytes)])) };
+}
+
+/** The page's JavaScript heap, where the browser tells (Chrome and Edge only). */
+function heap(): { usedMB: number; totalMB: number; limitMB: number } | null {
+  const memory = (performance as { memory?: { usedJSHeapSize: number; totalJSHeapSize: number;
+    jsHeapSizeLimit: number } }).memory;
+
+  return memory
+    ? { usedMB: mb(memory.usedJSHeapSize), totalMB: mb(memory.totalJSHeapSize), limitMB: mb(memory.jsHeapSizeLimit) }
+    : null;
+}
+
+/** Logs one step: the device's total and largest labels, the JavaScript heap, and whatever sizes the step adds. */
+export function logMemory(step: string, details: Record<string, unknown> = {}) {
+  if (!enabled) return;
+
+  const device = deviceMemory();
+  const js = heap();
+
+  // As text, not as an object: a console that folds objects loses them when it is copied.
+  const text = Object.entries({ ...details, device: device.byLabel })
+    .map(([key, value]) => `\n  ${key}: ${typeof value === "object" ? JSON.stringify(value) : String(value)}`)
+    .join("");
+
+  // eslint-disable-next-line no-console -- the log is the point of this module
+  console.info(`[gpu-renderer] ${step}: device ${device.totalMB} MB`
+    + (js ? `, JS heap ${js.usedMB}/${js.limitMB} MB` : "") + text);
+}
+
+interface BreakdownMesh {
+  primitive?: string;
+  attributes: Record<string, { data: ArrayLike<number> } | undefined>;
+  index: ArrayLike<number> | null;
+  materials: ({ name?: string; type?: string; values?: Record<string, unknown> } | null | undefined)[];
+}
+
+/**
+ * Where a snapshot's triangles come from: plain meshes, wireframe materials, or lines, points and sprites, which the
+ * packer turns into triangles facing the camera (a line segment becomes two). Lines and wireframes that are not
+ * meant to be rendered are the usual reason a scene packs far more than it shows. Also the largest meshes, by the
+ * triangles each one packs.
+ */
+export function sceneBreakdown(meshes: readonly BreakdownMesh[]) {
+  const kinds: Record<string, { meshes: number; packedTriangles: number }> = {};
+  const largest: { kind: string; material: string; packedTriangles: number; vertices: number }[] = [];
+
+  for (const mesh of meshes) {
+    const vertices = (mesh.attributes.position?.data.length ?? 0) / 3;
+    const count = mesh.index?.length ?? vertices;
+    const material = mesh.materials[0];
+    const wireframe = !mesh.primitive && mesh.materials.some(entry => entry?.values?.wireframe === true);
+    const kind = mesh.primitive ?? (wireframe ? "wireframe" : "mesh");
+
+    // Two triangles a segment or a point; a strip has one segment fewer than vertices.
+    const packed = kind === "lineSegments" ? count : kind === "line" || kind === "lineLoop" ? 2 * count
+      : kind === "points" ? 2 * count : count / 3;
+
+    kinds[kind] ??= { meshes: 0, packedTriangles: 0 };
+    kinds[kind].meshes++;
+    kinds[kind].packedTriangles += Math.round(packed);
+    largest.push({ kind, material: material?.name || material?.type || "?", packedTriangles: Math.round(packed),
+      vertices });
+  }
+
+  largest.sort((a, b) => b.packedTriangles - a.packedTriangles);
+
+  return { kinds, largest: largest.slice(0, 10) };
+}
+
+interface UsageTexture {
+  id: string;
+  width: number;
+  height: number;
+  data: ArrayLike<number>;
+}
+
+interface UsageMaterial {
+  maps?: Record<string, string>;
+}
+
+/**
+ * What each texture costs and how much of it is read: the slots that use it, the channels those slots read, and the
+ * bytes a texel would take if only those channels were kept (one, two or four bytes; float textures keep their four
+ * floats). The total says what keeping only the channels read would save.
+ */
+export function textureUsage(
+  textures: readonly UsageTexture[], materials: readonly (UsageMaterial | null | undefined)[]) {
+  const slots = new Map<string, Set<string>>();
+
+  for (const material of new Set(materials)) {
+    for (const [slot, id] of Object.entries(material?.maps ?? {})) {
+      if (typeof id !== "string") continue;
+
+      let known = slots.get(id);
+
+      if (!known) slots.set(id, known = new Set());
+
+      known.add(slot);
+    }
+  }
+
+  let nowBytes = 0, packedBytes = 0;
+
+  const rows = textures.map(texture => {
+    const used = [...slots.get(texture.id) ?? []];
+    // A normal map's third component could be rebuilt from the other two, so it counts as two here.
+    const channels = new Set(used.flatMap(slot => [...(slot.endsWith("ormalMap") ? "rg" : SLOT_CHANNELS[slot] ?? "rgba")]));
+    const float = texture.data instanceof Float32Array;
+    const texels = texture.width * texture.height;
+    const now = texels * (float ? 16 : 4);
+    // Three channels do not pack into fewer than four bytes on a word boundary; one or two do.
+    const kept = float ? 16 : channels.size === 0 ? 0 : channels.size <= 2 ? channels.size : 4;
+    const packed = texels * kept;
+
+    nowBytes += now;
+    packedBytes += packed;
+
+    return {
+      id: texture.id.length > 12 ? `${texture.id.slice(0, 12)}…` : texture.id,
+      fullId: texture.id,
+      size: `${texture.width}x${texture.height}`,
+      MB: mb(now),
+      slots: used.join("+") || "unused",
+      channels: [...channels].sort().join("") || "-",
+      packedMB: mb(packed),
+    };
+  });
+
+  rows.sort((a, b) => b.MB - a.MB);
+
+  return { totalMB: mb(nowBytes), packedMB: mb(packedBytes), textures: rows };
+}
+
+/** Bytes as MB, for the details of a step. */
+export const toMB = mb;

package/src/oidnPass.ts

@@ -192,7 +192,7 @@ export class OidnPass {
     const usage = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST;
 
     // Colour, albedo and normal for the network, then the result.
-    this.buffers = Array.from({ length: 4 }, () => this.device.createBuffer({ size, usage }));
+    this.buffers = Array.from({ length: 4 }, () => this.device.createBuffer({ label: "oidn", size, usage }));
     this.output = this.buffers[3];
     this.width = width;
     this.height = height;
@@ -275,6 +275,26 @@ export class OidnPass {
     return true;
   }
 
+  /**
+   * Lets go of everything sized by an image: the four buffers here and the network's own, its activations and its
+   * input and output passes, which together hold a few hundred megabytes for a large image. The network is loaded
+   * again by the next run. Call it only once no run is in flight.
+   */
+  async release() {
+    for (const buffer of this.buffers) buffer.destroy();
+
+    this.buffers = [];
+    this.output = null;
+    this.width = 0;
+    this.height = 0;
+
+    const byUrl = networks.get(this.device);
+
+    networks.delete(this.device);
+
+    for (const unet of byUrl?.values() ?? []) await unet.then(loaded => loaded.dispose(), () => undefined);
+  }
+
   destroy() {
     for (const buffer of [...this.buffers, this.params, this.scale]) buffer.destroy();
 

package/src/pathTracePass.ts

@@ -26,28 +26,38 @@ export type FrameUniforms = Record<keyof typeof FRAME_LAYOUT.offsets & string, n
  */
 export function pathTraceSource(
   programs: ShaderPrograms | null = null, subsurface = true, volumes = true, bevel = true,
-  portals = true, grass = true): string {
+  portals = true, grass = true, instances = true): string {
   // The random walk inside materials and the media inside volumes are compiled in only for a scene that has them: the
   // kernel is bound by its size, and either would cost every other scene a few percent for code that never runs.
   return `const SUBSURFACE_WALK: bool = ${subsurface};\nconst VOLUMES: bool = ${volumes};\nconst BEVEL: bool = ${bevel};\n`
-    + `const PORTALS: bool = ${portals};\nconst GRASS: bool = ${grass};\n` + COMMON_WGSL + RANDOM_WGSL + BVH_WGSL
+    + `const PORTALS: bool = ${portals};\nconst GRASS: bool = ${grass};\n` + traversalConstants(instances) + COMMON_WGSL + RANDOM_WGSL + BVH_WGSL
     + SAMPLING_WGSL + TEXTURE_WGSL + SHADER_SUPPORT_WGSL + programsWgsl(programs) + ENVIRONMENT_WGSL + SURFACE_WGSL
     + (grass ? GRASS_WGSL : GRASS_STUB_WGSL) + BSDF_WGSL + LIGHTS_WGSL + PATH_TRACE_WGSL;
 }
 
+/**
+ * Whether the traversal can enter instances, and the stack that takes: an instance stacks its own hierarchy on top of
+ * the scene's and the tree over the instances, so the stack doubles. A scene with no repeated geometry keeps the
+ * smaller one, which is what the kernel's registers are measured against.
+ */
+export function traversalConstants(instances: boolean): string {
+  return `const INSTANCES: bool = ${instances};\nconst BVH_STACK: u32 = ${instances ? 64 : 32}u;\n`;
+}
+
 const FRAME_BYTES = FRAME_WORDS * 4;
 
 const WORKGROUP = 8;
 
 export class PathTracePass {
-  private pipeline: GPUComputePipeline;
+  private pipeline: GPUComputePipeline | null = null;
+  /** The kernel being compiled for `programKey`, which every caller asking for the same set waits on. */
+  private building: Promise<GPUComputePipeline> | null = null;
   private readonly uniforms: GPUBuffer;
   private readonly values = new ArrayBuffer(FRAME_BYTES);
   private bindGroup: GPUBindGroup | null = null;
-  private programKey = "|false|false|false|false|false";
+  private programKey: string | null = null;
 
   constructor(private readonly device: GPUDevice) {
-    this.pipeline = this.build(null, false, false, false, false, false);
     this.uniforms = device.createBuffer({ size: FRAME_BYTES, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
   }
 
@@ -55,27 +65,41 @@ export class PathTracePass {
    * Recompiles the kernel when the scene's shaders changed, or whether it has a material that scatters light inside;
    * the same set keeps the pipeline it has.
    */
-  setPrograms(programs: ShaderPrograms | null, subsurface = false, volumes = false, bevel = false,
-    portals = false, grass = false) {
-    const key = `${programs?.key ?? ""}|${subsurface}|${volumes}|${bevel}|${portals}|${grass}`;
-
-    if (key === this.programKey) return;
-
-    this.programKey = key;
-    this.pipeline = this.build(programs, subsurface, volumes, bevel, portals, grass);
-    this.bindGroup = null;
+  async setPrograms(programs: ShaderPrograms | null, subsurface = false, volumes = false, bevel = false,
+    portals = false, grass = false, instances = false): Promise<void> {
+    const key = `${programs?.key ?? ""}|${subsurface}|${volumes}|${bevel}|${portals}|${grass}|${instances}`;
+
+    if (key !== this.programKey) {
+      this.programKey = key;
+      this.pipeline = null;
+      this.bindGroup = null;
+      this.building = this.build(programs, subsurface, volumes, bevel, portals, grass, instances);
+    }
+
+    const building = this.building as Promise<GPUComputePipeline>;
+    const pipeline = await building;
+
+    // A newer set may have started compiling meanwhile; this one is then already stale.
+    if (this.building === building) this.pipeline = pipeline;
   }
 
+  /**
+   * The kernel is large, and on Windows the browser compiles it through the D3D shader compiler, which can take many
+   * seconds. Compiled synchronously that blocks the GPU process long enough for its watchdog to kill it, and the device
+   * is lost before the first sample; the async path compiles off that thread.
+   */
   private build(programs: ShaderPrograms | null, subsurface: boolean, volumes: boolean,
-    bevel: boolean, portals: boolean, grass: boolean): GPUComputePipeline {
+    bevel: boolean, portals: boolean, grass: boolean, instances: boolean): Promise<GPUComputePipeline> {
     const module = createShaderModule(this.device, "path trace",
-      pathTraceSource(programs, subsurface, volumes, bevel, portals, grass));
+      pathTraceSource(programs, subsurface, volumes, bevel, portals, grass, instances));
 
-    return this.device.createComputePipeline({ layout: "auto", compute: { module, entryPoint: "main" } });
+    return this.device.createComputePipelineAsync({ label: "path trace", layout: "auto", compute: { module, entryPoint: "main" } });
   }
 
   /** Rebinds after the scene or the accumulation buffer was replaced. */
   setBindings(scene: SceneBuffers, accumulation: GPUBuffer) {
+    if (!this.pipeline) throw new Error("GPU renderer: the path tracing kernel is not compiled yet.");
+
     this.bindGroup = this.device.createBindGroup({
       layout: this.pipeline.getBindGroupLayout(0),
       entries: [
@@ -93,7 +117,7 @@ export class PathTracePass {
   }
 
   encode(encoder: GPUCommandEncoder, frame: FrameUniforms) {
-    if (!this.bindGroup) throw new Error("GPU renderer: the path tracing pass has no scene bound.");
+    if (!this.bindGroup || !this.pipeline) throw new Error("GPU renderer: the path tracing pass has no scene bound.");
 
     new Uint32Array(this.values).fill(0);
     writeStruct(FRAME_LAYOUT, this.values, 0, frame);