@driftengine/core 3.61.0

package/dist/render/backend/webgpu/scatterPass.d.ts

@@ -0,0 +1,95 @@
+import type { MeshData } from '../../mesh.ts';
+import type { PipelineCache } from './pipelineCache.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;
+}>>;
+export declare const SCATTER_DEPTH_FIELDS: UniformFields;
+export declare const SCATTER_DEPTH_SIZE: 240;
+export declare const SCATTER_VERT_FIELDS: UniformFields;
+export declare const SCATTER_VERT_SIZE: 240;
+export declare const SCATTER_FRAG_FIELDS: UniformFields;
+export declare const SCATTER_FRAG_SIZE: 128;
+export declare function scatterVertexLayouts(): GPUVertexBufferLayout[];
+/** 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 declare function createGpuScatter(device: GPUDevice, base: MeshData, capacity: number): GpuScatter;
+export declare function createScatterBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
+export declare function createScatterBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, perPass: GPUBuffer, perFrame: GPUBuffer): GPUBindGroup;
+/**
+ * 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 declare function scatterDepthPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout, shadowFormat: GPUTextureFormat, depthFragment: string): GPURenderPipeline;
+/**
+ * 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 declare function scatterPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout): GPURenderPipeline;
+/**
+ * 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 declare function createScatterDepthBindGroupLayout(device: GPUDevice, fragBinding: number, fragSize: number, previous: {
+    texture: number;
+    sampler: number;
+}): GPUBindGroupLayout;
+/** `perDraw` is a `UniformRing`'s buffer now, bound one slot at a time. See the layout above. */
+export declare 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;

package/dist/render/backend/webgpu/scatterPass.js

@@ -0,0 +1,266 @@
+import { DEPTH_COMPARE } from '../../depthConvention.js';
+import { SCATTER_BINDINGS, SCATTER_DEPTH_VERT_WGSL, SCATTER_FRAG_WGSL, SCATTER_VERT_WGSL, } from '../../shaders/generated/scatter.wgsl.js';
+import { DEPTH_FORMAT } from './flatPass.js';
+import { shaderModule } from './shaderModules.js';
+/*
+ * 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 = SCATTER_BINDINGS.SCATTER_DEPTH_VERT.fields;
+export const SCATTER_DEPTH_SIZE = SCATTER_BINDINGS.SCATTER_DEPTH_VERT.uniformSize;
+export const SCATTER_VERT_FIELDS = SCATTER_BINDINGS.SCATTER_VERT.fields;
+export const SCATTER_VERT_SIZE = SCATTER_BINDINGS.SCATTER_VERT.uniformSize;
+export const SCATTER_FRAG_FIELDS = 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 = [
+    { 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 = {
+    2: 'float32x2',
+    3: 'float32x3',
+};
+export function scatterVertexLayouts() {
+    return ATTRIBUTES.map((attribute) => ({
+        arrayStride: attribute.floats * 4,
+        stepMode: attribute.perInstance ? 'instance' : 'vertex',
+        attributes: [
+            {
+                shaderLocation: attribute.location,
+                offset: 0,
+                format: FORMATS[attribute.floats],
+            },
+        ],
+    }));
+}
+/**
+ * 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, base, capacity) {
+    const buffers = [];
+    const upload = (data, label) => {
+        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() {
+            for (const buffer of buffers)
+                buffer.destroy();
+            indexBuffer.destroy();
+        },
+    };
+}
+export function createScatterBindGroupLayout(device) {
+    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, layout, perPass, perFrame) {
+    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, device, layout, shadowFormat, depthFragment) {
+    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, device, layout) {
+    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, fragBinding, fragSize, previous) {
+    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, layout, perDraw, frag, previous, view, sampler) {
+    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/dist/render/backend/webgpu/sdfTextPass.d.ts

@@ -0,0 +1,86 @@
+import type { UniformFields } from './scatterPass.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';
+/**
+ * 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 declare const SDF_TEXT_VERT_FIELDS: UniformFields;
+export declare const SDF_TEXT_VERT_SIZE: 128;
+export declare const SDF_TEXT_FRAG_FIELDS: UniformFields;
+export declare const SDF_TEXT_FRAG_SIZE: 48;
+/**
+ * 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 declare class GpuSdfText {
+    private readonly device;
+    readonly layout: 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;
+    atlas: GpuSurfaceTexture | null;
+    constructor(device: GPUDevice);
+    /**
+     * 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;
+    dispose(): void;
+    /** Both vertex buffers, from the arrays `layout.set` filled in place — the live prefix only. */
+    private upload;
+}
+/**
+ * `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 declare function sdfTextVertexLayouts(): GPUVertexBufferLayout[];
+/**
+ * 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 declare function createSdfTextBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
+/**
+ * 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 declare function createSdfTextBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, vertices: GPUBuffer, fragments: GPUBuffer, atlasView: GPUTextureView, atlasSampler: GPUSampler): GPUBindGroup;
+/**
+ * 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 declare function sdfTextPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout): GPURenderPipeline;

package/dist/render/backend/webgpu/sdfTextPass.js

@@ -0,0 +1,190 @@
+import { DEPTH_COMPARE } from '../../depthConvention.js';
+import { SDFTEXT_BINDINGS, SDF_TEXT_FRAG_WGSL, SDF_TEXT_VERT_WGSL, } from '../../shaders/generated/sdfText.wgsl.js';
+import { DEPTH_FORMAT } from './flatPass.js';
+import { SdfTextLayout } from '../../sdfTextLayout.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * 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 = SDFTEXT_BINDINGS.SDF_TEXT_VERT.fields;
+export const SDF_TEXT_VERT_SIZE = SDFTEXT_BINDINGS.SDF_TEXT_VERT.uniformSize;
+export const SDF_TEXT_FRAG_FIELDS = 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 {
+    device;
+    layout = new SdfTextLayout();
+    positions;
+    uvs;
+    indices;
+    /** Set by `setText`; `drawSdfText` reads neither this class nor the atlas from anywhere else. */
+    font = null;
+    atlas = null;
+    constructor(device) {
+        this.device = device;
+        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, atlas, text, style) {
+        this.font = font;
+        this.atlas = atlas;
+        if (this.layout.set(font, text, style))
+            this.upload();
+    }
+    dispose() {
+        this.positions.destroy();
+        this.uvs.destroy();
+        this.indices.destroy();
+    }
+    /** Both vertex buffers, from the arrays `layout.set` filled in place — the live prefix only. */
+    upload() {
+        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() {
+    return [
+        {
+            arrayStride: 12,
+            attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }],
+        },
+        {
+            arrayStride: 8,
+            attributes: [{ shaderLocation: 1, offset: 0, format: 'float32x2' }],
+        },
+    ];
+}
+/**
+ * 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) {
+    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, layout, vertices, fragments, atlasView, atlasSampler) {
+    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, device, layout) {
+    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/dist/render/backend/webgpu/shaderModules.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare function shaderModule(device: GPUDevice, descriptor: GPUShaderModuleDescriptor): GPUShaderModule;
+/** How many distinct sources this device has compiled. Read by tests and diagnostics. */
+export declare function shaderModuleCount(device: GPUDevice): number;