@driftengine/core 3.61.0

package/src/render/backend/webgpu/scatterPass.ts

@@ -0,0 +1,354 @@
+import { DEPTH_COMPARE } from '../../depthConvention.ts';
+import {
+  SCATTER_BINDINGS,
+  SCATTER_DEPTH_VERT_WGSL,
+  SCATTER_FRAG_WGSL,
+  SCATTER_VERT_WGSL,
+} from '../../shaders/generated/scatter.wgsl.ts';
+import type { MeshData } from '../../mesh.ts';
+import { DEPTH_FORMAT } from './flatPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import { shaderModule } from './shaderModules.ts';
+
+/**
+ * The scatter pass: one base mesh drawn many times, deformed by wind in the vertex stage.
+ *
+ * **The first pass here that instances**, and the whole reason it is worth porting early: a
+ * field of grass is tens of thousands of copies of a few triangles, and everything else this
+ * backend draws is one copy of one mesh. The WebGPU shape of it is `stepMode: 'instance'` on
+ * a vertex buffer, which is `vertexAttribDivisor(location, 1)` with the divisor moved from
+ * the attribute to the buffer that carries it.
+ */
+
+/** One field's place in the block, as the generator recorded it. See `flatPass.StageBindings`. */
+export type UniformFields = Readonly<
+  Record<
+    string,
+    {
+      readonly offset: number;
+      readonly size: number;
+      readonly length?: number;
+      readonly stride?: number;
+    }
+  >
+>;
+
+/*
+ * Widened once here, for the reason `flatPass.ts` gives: the generated file is `as const`, so
+ * every field is its own literal type and indexing it by a computed name is an error. Checked
+ * against the real object rather than asserted about it — a generator that stopped emitting
+ * `offset` would fail on this line.
+ */
+export const SCATTER_DEPTH_FIELDS: UniformFields = SCATTER_BINDINGS.SCATTER_DEPTH_VERT.fields;
+export const SCATTER_DEPTH_SIZE = SCATTER_BINDINGS.SCATTER_DEPTH_VERT.uniformSize;
+export const SCATTER_VERT_FIELDS: UniformFields = SCATTER_BINDINGS.SCATTER_VERT.fields;
+export const SCATTER_VERT_SIZE = SCATTER_BINDINGS.SCATTER_VERT.uniformSize;
+export const SCATTER_FRAG_FIELDS: UniformFields = SCATTER_BINDINGS.SCATTER_FRAG.fields;
+export const SCATTER_FRAG_SIZE = SCATTER_BINDINGS.SCATTER_FRAG.uniformSize;
+
+const VERT_BINDING = SCATTER_BINDINGS.SCATTER_VERT.uniforms;
+const FRAG_BINDING = SCATTER_BINDINGS.SCATTER_FRAG.uniforms;
+
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+
+/** Buffer usage: VERTEX | COPY_DST, and INDEX | COPY_DST. See `buffers.ts`. */
+const USAGE_VERTEX = 0x0020 | 0x0008;
+const USAGE_INDEX = 0x0010 | 0x0008;
+
+/**
+ * How the seven attributes are laid out, one buffer each.
+ *
+ * **Seven buffers rather than the two `flat` uses, and that is affordable here.**
+ * `maxVertexBuffers` is eight; `flat` interleaves because it declares ten attributes and
+ * would not fit. Seven does, and one buffer per attribute is what `InstancedMesh` already
+ * holds on the other backend, so the upload paths stay the same shape.
+ *
+ * The last four step per *instance*. That is the entire difference between a field of grass
+ * and one blade drawn tens of thousands of times in the same place.
+ */
+const ATTRIBUTES: readonly {
+  readonly location: number;
+  readonly floats: number;
+  readonly perInstance: boolean;
+}[] = [
+  { location: 0, floats: 3, perInstance: false },
+  { location: 1, floats: 3, perInstance: false },
+  { location: 2, floats: 3, perInstance: false },
+  { location: 3, floats: 3, perInstance: true },
+  { location: 4, floats: 2, perInstance: true },
+  { location: 5, floats: 3, perInstance: true },
+  { location: 6, floats: 3, perInstance: true },
+];
+
+const FORMATS: Readonly<Record<number, GPUVertexFormat>> = {
+  2: 'float32x2',
+  3: 'float32x3',
+};
+
+export function scatterVertexLayouts(): GPUVertexBufferLayout[] {
+  return ATTRIBUTES.map((attribute) => ({
+    arrayStride: attribute.floats * 4,
+    stepMode: attribute.perInstance ? ('instance' as const) : ('vertex' as const),
+    attributes: [
+      {
+        shaderLocation: attribute.location,
+        offset: 0,
+        format: FORMATS[attribute.floats] as GPUVertexFormat,
+      },
+    ],
+  }));
+}
+
+/** Geometry and placement on the device, behind the opaque handle the surface hands out. */
+export interface GpuScatter {
+  readonly vertexBuffers: readonly GPUBuffer[];
+  readonly indexBuffer: GPUBuffer;
+  readonly indexCount: number;
+  /** How many instances the per-instance buffers were sized for. */
+  readonly capacity: number;
+  dispose(): void;
+}
+
+/**
+ * Upload a base mesh and size the per-instance buffers.
+ *
+ * **Sized to capacity now and rewritten later**, matching `InstancedMesh`: growing a buffer
+ * mid-frame is a stall, and a scatter's capacity is known when it is built.
+ */
+export function createGpuScatter(device: GPUDevice, base: MeshData, capacity: number): GpuScatter {
+  const buffers: GPUBuffer[] = [];
+  const upload = (data: Float32Array, label: string): GPUBuffer => {
+    const buffer = device.createBuffer({
+      label,
+      size: Math.max(4, data.byteLength),
+      usage: USAGE_VERTEX,
+    });
+    device.queue.writeBuffer(buffer, 0, data);
+    buffers.push(buffer);
+    return buffer;
+  };
+  upload(base.positions, 'scatter.positions');
+  upload(base.normals, 'scatter.normals');
+  upload(base.colors, 'scatter.colors');
+
+  for (const attribute of ATTRIBUTES.filter((a) => a.perInstance)) {
+    const buffer = device.createBuffer({
+      label: `scatter.instance${attribute.location}`,
+      size: Math.max(4, capacity * attribute.floats * 4),
+      usage: USAGE_VERTEX,
+    });
+    buffers.push(buffer);
+  }
+
+  const indexBuffer = device.createBuffer({
+    label: 'scatter.indices',
+    size: Math.max(4, base.indices.byteLength),
+    usage: USAGE_INDEX,
+  });
+  device.queue.writeBuffer(indexBuffer, 0, base.indices);
+
+  return {
+    vertexBuffers: buffers,
+    indexBuffer,
+    indexCount: base.indices.length,
+    capacity,
+    dispose(): void {
+      for (const buffer of buffers) buffer.destroy();
+      indexBuffer.destroy();
+    },
+  };
+}
+
+export function createScatterBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+  return device.createBindGroupLayout({
+    label: 'scatter.layout',
+    entries: [
+      /*
+       * **The vertex block is per draw and the fragment block is not.**
+       *
+       * The vertex block carries the gust and the trample field, and both arrive as arguments
+       * to `drawScatter` — so a scene bending its grass by one press field and its canopy by
+       * another gets whichever was written last for both, from a single buffer. That is not
+       * hypothetical elsewhere: the plume pass had exactly this and drew a flame bent by the
+       * smoke's wind response. The demo that exercises this today happens to pass both
+       * batches the same wind and no trample, which is luck rather than a guarantee.
+       *
+       * The fragment block holds the camera, the sun, the point lights and the medium, which
+       * are settled per pass rather than per batch. It stops being safe the day something
+       * per-batch is added to it, and that is what would make this a ring too.
+       */
+      {
+        binding: VERT_BINDING,
+        visibility: VISIBILITY_VERTEX,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: SCATTER_VERT_SIZE },
+      },
+      {
+        binding: FRAG_BINDING,
+        visibility: VISIBILITY_FRAGMENT,
+        buffer: { type: 'uniform', minBindingSize: SCATTER_FRAG_SIZE },
+      },
+    ],
+  });
+}
+
+export function createScatterBindGroup(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  perPass: GPUBuffer,
+  perFrame: GPUBuffer,
+): GPUBindGroup {
+  return device.createBindGroup({
+    label: 'scatter.bindGroup',
+    layout,
+    entries: [
+      { binding: VERT_BINDING, resource: { buffer: perPass, size: SCATTER_VERT_SIZE } },
+      { binding: FRAG_BINDING, resource: { buffer: perFrame, size: SCATTER_FRAG_SIZE } },
+    ],
+  });
+}
+
+/**
+ * The scatter *depth* pipeline: the same blades, bent the same way, into the shadow map.
+ *
+ * **It has to be the same deformation or the shadow comes loose from its caster.** The
+ * vertex stage is `SCATTER_DEPTH_VERT` rather than the frame's, but it reads the same wind
+ * block at the same offsets, so the two are fed from one `resolveScatterDeform`. A blade
+ * bent by one gust and shadowed by another is the failure this pairing exists to prevent —
+ * and it is why `ShadowCasterSink.scatter` takes the gust rather than looking it up.
+ *
+ * Paired with `DEPTH_FRAG`, exactly as `renderer.ts` pairs `scatterDepthProgram`.
+ *
+ * Single-sampled and no colour target: the shadow map is neither multisampled nor presented.
+ */
+export function scatterDepthPipeline(
+  cache: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  shadowFormat: GPUTextureFormat,
+  depthFragment: string,
+): GPURenderPipeline {
+  return cache.get('scatter.depth', () => ({
+    label: 'scatter.depth',
+    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+    vertex: {
+      module: shaderModule(device, {
+        label: 'scatter.depthVert',
+        code: SCATTER_DEPTH_VERT_WGSL,
+      }),
+      entryPoint: 'main',
+      buffers: scatterVertexLayouts(),
+    },
+    fragment: {
+      module: shaderModule(device, { label: 'depth.frag', code: depthFragment }),
+      entryPoint: 'main',
+      targets: [],
+    },
+    primitive: { topology: 'triangle-list', cullMode: 'none' },
+    depthStencil: { format: shadowFormat, depthWriteEnabled: true, depthCompare: DEPTH_COMPARE },
+  }));
+}
+
+/**
+ * The scatter pipeline.
+ *
+ * **Culling off, matching `renderer.ts`.** It brackets the scatter draw with
+ * `gl.disable(gl.CULL_FACE)`, because a blade of grass is a flat card with no back: cull it
+ * and half the field vanishes depending on which way the wind turned it.
+ */
+export function scatterPipeline(
+  cache: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+): GPURenderPipeline {
+  return cache.get('scatter', () => ({
+    label: 'scatter',
+    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+    vertex: {
+      module: shaderModule(device, { label: 'scatter.vert', code: SCATTER_VERT_WGSL }),
+      entryPoint: 'main',
+      buffers: scatterVertexLayouts(),
+    },
+    fragment: {
+      module: shaderModule(device, { label: 'scatter.frag', code: SCATTER_FRAG_WGSL }),
+      entryPoint: 'main',
+      targets: [{ format: cache.format }],
+    },
+    primitive: { topology: 'triangle-list', cullMode: 'none' },
+    multisample: { count: cache.sampleCount },
+    depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: true, depthCompare: DEPTH_COMPARE },
+  }));
+}
+
+/**
+ * The layout the scatter depth pass binds against.
+ *
+ * The vertex block is the scatter one — wind and trample — and the fragment block and its
+ * previous-map sampler are the depth pass's own, unchanged, because the peel layer works the
+ * same way whatever geometry is filling it.
+ *
+ * **`hasDynamicOffset` on the vertex block, and it is a bug fix rather than a shape.** That
+ * block used to be one buffer rewritten before every batch, which is the failure `UniformRing`
+ * exists for: writes are ordered on the queue timeline and the encoder is submitted afterwards,
+ * so every scatter draw recorded before that submit reads the *last* write. Inside one
+ * directional layer that costs a batch the wrong gust. Inside a point light's bake it costs the
+ * wrong `uLightViewProj`, because six cube faces share one encoder — so a field of grass was
+ * rasterised into all six faces under the last face's projection, and five sixths of it landed
+ * in the octahedral map at directions nothing occupies. What that draws is a hard-edged patch of
+ * shadow on the ground beside a lamp with nothing above it to cast one.
+ */
+export function createScatterDepthBindGroupLayout(
+  device: GPUDevice,
+  fragBinding: number,
+  fragSize: number,
+  previous: { texture: number; sampler: number },
+): GPUBindGroupLayout {
+  return device.createBindGroupLayout({
+    label: 'scatter.depthLayout',
+    entries: [
+      {
+        binding: VERT_BINDING,
+        visibility: VISIBILITY_VERTEX,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: SCATTER_DEPTH_SIZE },
+      },
+      {
+        binding: fragBinding,
+        visibility: VISIBILITY_FRAGMENT,
+        buffer: { type: 'uniform', minBindingSize: fragSize },
+      },
+      /* A depth format, for the reason `depthPass.ts` spells out over its own copy of this. */
+      {
+        binding: previous.texture,
+        visibility: VISIBILITY_FRAGMENT,
+        texture: { sampleType: 'unfilterable-float' },
+      },
+      {
+        binding: previous.sampler,
+        visibility: VISIBILITY_FRAGMENT,
+        sampler: { type: 'non-filtering' },
+      },
+    ],
+  });
+}
+
+/** `perDraw` is a `UniformRing`'s buffer now, bound one slot at a time. See the layout above. */
+export function createScatterDepthBindGroup(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  perDraw: GPUBuffer,
+  frag: { binding: number; buffer: GPUBuffer; size: number },
+  previous: { texture: number; sampler: number },
+  view: GPUTextureView,
+  sampler: GPUSampler,
+): GPUBindGroup {
+  return device.createBindGroup({
+    label: 'scatter.depthBindGroup',
+    layout,
+    entries: [
+      { binding: VERT_BINDING, resource: { buffer: perDraw, size: SCATTER_DEPTH_SIZE } },
+      { binding: frag.binding, resource: { buffer: frag.buffer, size: frag.size } },
+      { binding: previous.texture, resource: view },
+      { binding: previous.sampler, resource: sampler },
+    ],
+  });
+}

package/src/render/backend/webgpu/sdfTextPass.ts

@@ -0,0 +1,220 @@
+import { DEPTH_COMPARE } from '../../depthConvention.ts';
+import {
+  SDFTEXT_BINDINGS,
+  SDF_TEXT_FRAG_WGSL,
+  SDF_TEXT_VERT_WGSL,
+} from '../../shaders/generated/sdfText.wgsl.ts';
+import type { UniformFields } from './scatterPass.ts';
+import { DEPTH_FORMAT } from './flatPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import type { SdfFont } from '../../sdfFont.ts';
+import { SdfTextLayout, type SdfTextStyle } from '../../sdfTextLayout.ts';
+import type { GpuSurfaceTexture } from './surfaceTexturePass.ts';
+import { shaderModule } from './shaderModules.ts';
+
+/**
+ * The SDF text pass: a string as flat, textured quads, drawn into the scene.
+ *
+ * Same job as `textPass.ts` for the engine's pixel font, and `sdfTextRenderer.ts`'s own class
+ * comment gives the reason this shape differs from that one: a distance field is sampled by
+ * the fragment shader, so a quad per glyph is the whole glyph — one indexed draw per string,
+ * no per-instance stepping. The layout is `sdfTextLayout.ts`'s and is shared with WebGL2; this
+ * owns only the buffers, the bind group and the pipeline.
+ *
+ * **World geometry, not a screen overlay — unlike `GpuText`.** It draws against the frame's
+ * own view-projection inside whatever pass is already open, the same one `drawMesh` uses, so
+ * it needs neither a pass of its own nor `openTextPass`'s depth clear. See `drawSdfText` in
+ * `webgpu/renderer.ts` for what that means for where this is called from.
+ */
+
+export const SDF_TEXT_VERT_FIELDS: UniformFields = SDFTEXT_BINDINGS.SDF_TEXT_VERT.fields;
+export const SDF_TEXT_VERT_SIZE = SDFTEXT_BINDINGS.SDF_TEXT_VERT.uniformSize;
+export const SDF_TEXT_FRAG_FIELDS: UniformFields = SDFTEXT_BINDINGS.SDF_TEXT_FRAG.fields;
+export const SDF_TEXT_FRAG_SIZE = SDFTEXT_BINDINGS.SDF_TEXT_FRAG.uniformSize;
+
+const VERT_BINDING = SDFTEXT_BINDINGS.SDF_TEXT_VERT.uniforms;
+const FRAG_BINDING = SDFTEXT_BINDINGS.SDF_TEXT_FRAG.uniforms;
+const ATLAS = SDFTEXT_BINDINGS.SDF_TEXT_FRAG.textures.uAtlas;
+
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008; // VERTEX | COPY_DST
+const USAGE_INDEX = 0x0010 | 0x0008; // INDEX | COPY_DST
+
+/**
+ * One SDF text object on the device: the layout, and the three buffers it fills.
+ *
+ * **A plain indexed quad list, not `GpuText`'s instanced cube** — see this file's own doc
+ * comment. `positions`/`uvs` are re-uploaded only when `layout.set` says something moved,
+ * matching `SdfTextRenderer.upload`'s skip on the other backend; `indices` never changes after
+ * construction, matching `SdfTextLayout`'s own fixed `0,1,2,0,2,3` pattern.
+ */
+export class GpuSdfText {
+  readonly layout = new SdfTextLayout();
+  readonly positions: GPUBuffer;
+  readonly uvs: GPUBuffer;
+  readonly indices: GPUBuffer;
+
+  /** Set by `setText`; `drawSdfText` reads neither this class nor the atlas from anywhere else. */
+  font: SdfFont | null = null;
+  atlas: GpuSurfaceTexture | null = null;
+
+  constructor(private readonly device: GPUDevice) {
+    this.positions = device.createBuffer({
+      label: 'sdfText.positions',
+      size: this.layout.positions.byteLength,
+      usage: USAGE_VERTEX,
+    });
+    this.uvs = device.createBuffer({
+      label: 'sdfText.uvs',
+      size: this.layout.uvs.byteLength,
+      usage: USAGE_VERTEX,
+    });
+    this.indices = device.createBuffer({
+      label: 'sdfText.indices',
+      size: this.layout.indices.byteLength,
+      usage: USAGE_INDEX,
+    });
+    device.queue.writeBuffer(this.indices, 0, this.layout.indices);
+  }
+
+  /**
+   * Lay a string out against a font, and retain the atlas `drawSdfText` will sample.
+   *
+   * The engine fetches nothing: `font` was parsed from a metrics document the caller already
+   * had, and `atlas` is a `GpuSurfaceTexture` the caller already uploaded. A no-op, and no
+   * re-upload, when neither the text nor the style moved — see `SdfTextLayout.set`.
+   */
+  setText(font: SdfFont, atlas: GpuSurfaceTexture, text: string, style: SdfTextStyle): void {
+    this.font = font;
+    this.atlas = atlas;
+    if (this.layout.set(font, text, style)) this.upload();
+  }
+
+  dispose(): void {
+    this.positions.destroy();
+    this.uvs.destroy();
+    this.indices.destroy();
+  }
+
+  /** Both vertex buffers, from the arrays `layout.set` filled in place — the live prefix only. */
+  private upload(): void {
+    const vertexCount = this.layout.quadCount * 4;
+    this.device.queue.writeBuffer(this.positions, 0, this.layout.positions, 0, vertexCount * 3);
+    this.device.queue.writeBuffer(this.uvs, 0, this.layout.uvs, 0, vertexCount * 2);
+  }
+}
+
+/**
+ * `aPosition` at location 0, `aUv` at location 1 — pinned in `sdfText.ts` and read verbatim
+ * here rather than guessed, for the reason `sdfTextRenderer.ts`'s class comment gives. Neither
+ * is instanced: every vertex is its own quad corner, unlike `textVertexLayouts`'s per-instance
+ * cell and character.
+ */
+export function sdfTextVertexLayouts(): GPUVertexBufferLayout[] {
+  return [
+    {
+      arrayStride: 12,
+      attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' as GPUVertexFormat }],
+    },
+    {
+      arrayStride: 8,
+      attributes: [{ shaderLocation: 1, offset: 0, format: 'float32x2' as GPUVertexFormat }],
+    },
+  ];
+}
+
+/**
+ * Built from `SDFTEXT_BINDINGS`, not hand-numbered — the generator emits bindings per shader
+ * precisely so this always binds the numbers the shader actually declared.
+ */
+export function createSdfTextBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+  return device.createBindGroupLayout({
+    label: 'sdfText.layout',
+    entries: [
+      {
+        binding: VERT_BINDING,
+        visibility: VISIBILITY_VERTEX,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: SDF_TEXT_VERT_SIZE },
+      },
+      {
+        binding: FRAG_BINDING,
+        visibility: VISIBILITY_FRAGMENT,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: SDF_TEXT_FRAG_SIZE },
+      },
+      { binding: ATLAS.texture, visibility: VISIBILITY_FRAGMENT, texture: {} },
+      { binding: ATLAS.sampler, visibility: VISIBILITY_FRAGMENT, sampler: {} },
+    ],
+  });
+}
+
+/**
+ * Bound once per atlas against both rings; a dynamic offset per string. See
+ * `createTextBindGroup` and, for why one bind group serves every draw against the same atlas,
+ * `webgpu/renderer.ts`'s `albedoBindGroups`.
+ */
+export function createSdfTextBindGroup(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  vertices: GPUBuffer,
+  fragments: GPUBuffer,
+  atlasView: GPUTextureView,
+  atlasSampler: GPUSampler,
+): GPUBindGroup {
+  return device.createBindGroup({
+    label: 'sdfText.bindGroup',
+    layout,
+    entries: [
+      { binding: VERT_BINDING, resource: { buffer: vertices, size: SDF_TEXT_VERT_SIZE } },
+      { binding: FRAG_BINDING, resource: { buffer: fragments, size: SDF_TEXT_FRAG_SIZE } },
+      { binding: ATLAS.texture, resource: atlasView },
+      { binding: ATLAS.sampler, resource: atlasSampler },
+    ],
+  });
+}
+
+/**
+ * The pipeline.
+ *
+ * **Alpha over, depth tested, depth not written — matching `filmPipeline`, not `textPipeline`.**
+ * `sdfTextRenderer.ts`'s own comment gives the reason: an SDF glyph's antialiased edge is
+ * coverage, not a solid surface, and writing depth from it punches a hole in whatever sits
+ * behind that edge. Depth *testing* is left at the pass's own ambient state rather than
+ * reasserted, the same assumption `drawTranslucentMesh` makes for the same reason — this draws
+ * inside the mesh pass, not a pass of its own.
+ *
+ * **Back faces culled**, matching the ambient state `bindMeshPass` sets for the whole mesh
+ * pass on the other backend (`gl.enable(CULL_FACE); gl.cullFace(BACK)`) and the convention
+ * `filmPipeline` already uses for ordinary world geometry drawn the same way.
+ */
+export function sdfTextPipeline(
+  cache: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+): GPURenderPipeline {
+  return cache.get('sdfText', () => ({
+    label: 'sdfText',
+    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+    vertex: {
+      module: shaderModule(device, { label: 'sdfText.vert', code: SDF_TEXT_VERT_WGSL }),
+      entryPoint: 'main',
+      buffers: sdfTextVertexLayouts(),
+    },
+    fragment: {
+      module: shaderModule(device, { label: 'sdfText.frag', code: SDF_TEXT_FRAG_WGSL }),
+      entryPoint: 'main',
+      targets: [
+        {
+          format: cache.format,
+          blend: {
+            color: { srcFactor: 'src-alpha', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+            alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
+          },
+        },
+      ],
+    },
+    primitive: { topology: 'triangle-list', cullMode: 'back' },
+    multisample: { count: cache.sampleCount },
+    depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: DEPTH_COMPARE },
+  }));
+}

package/src/render/backend/webgpu/shaderModules.ts

@@ -0,0 +1,49 @@
+/**
+ * Shader modules, built once per source per device.
+ *
+ * **A module used to be created inside every pipeline descriptor**, which reads as free and is
+ * not: `createShaderModule` parses and validates the WGSL, and a descriptor is built on every
+ * `PipelineCache` miss. The flat shader is the worst case and the common one. A consumer that
+ * creates two dozen meshes gets a pipeline per distinct vertex layout, times a blended twin,
+ * times every target the mesh can land on, and each of those parsed the same large source
+ * again. On a workstation that is invisible. On a phone it is seconds of the main thread,
+ * before a single frame, which is a black and unresponsive page rather than a slow one.
+ *
+ * Keyed by the source text rather than by the label, because the source is what decides what a
+ * module *is* — two passes that compile the same WGSL under different labels want one module,
+ * and a label is a debugging string that must never change the object graph. Modules are
+ * immutable once created and safe to share between pipelines, which is the whole reason this
+ * can be a cache rather than a pool.
+ *
+ * `WeakMap` on the device, so nothing here outlives the device it belongs to: a lost context
+ * builds a new device, which starts empty and cannot be handed a module belonging to the dead
+ * one. That also means this needs no `dispose` and no wiring into anybody's teardown.
+ */
+const byDevice = new WeakMap<GPUDevice, Map<string, GPUShaderModule>>();
+
+/**
+ * The module for this source, compiling it on the first ask only.
+ *
+ * A drop-in for `device.createShaderModule(descriptor)`, and deliberately the same shape so a
+ * call site reads the same after the change as before it.
+ */
+export function shaderModule(
+  device: GPUDevice,
+  descriptor: GPUShaderModuleDescriptor,
+): GPUShaderModule {
+  let modules = byDevice.get(device);
+  if (modules === undefined) {
+    modules = new Map<string, GPUShaderModule>();
+    byDevice.set(device, modules);
+  }
+  const existing = modules.get(descriptor.code);
+  if (existing !== undefined) return existing;
+  const built = device.createShaderModule(descriptor);
+  modules.set(descriptor.code, built);
+  return built;
+}
+
+/** How many distinct sources this device has compiled. Read by tests and diagnostics. */
+export function shaderModuleCount(device: GPUDevice): number {
+  return byDevice.get(device)?.size ?? 0;
+}