@driftengine/core 3.61.0

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

@@ -0,0 +1,70 @@
+import { DEPTH_COMPARE_EQUAL } from '../../depthConvention.js';
+import { SKY_BINDINGS, SKY_FRAG_WGSL, SKY_VERT_WGSL } from '../../shaders/generated/sky.wgsl.js';
+import { DEPTH_FORMAT } from './flatPass.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * The sky: one triangle covering the screen, with the world reconstructed per fragment.
+ *
+ * **No vertex buffers at all.** The vertex shader builds its three corners from
+ * `gl_VertexIndex` — `gl_VertexID` in the GLSL, which the transform renames — so there is
+ * nothing to upload and nothing to bind. That makes this the simplest pass in the engine to
+ * port and a good second one after `flat`.
+ */
+export const SKY_FIELDS = SKY_BINDINGS.SKY_FRAG.fields;
+export const SKY_UNIFORM_SIZE = SKY_BINDINGS.SKY_FRAG.uniformSize;
+const SKY_BINDING = SKY_BINDINGS.SKY_FRAG.uniforms;
+const VISIBILITY_FRAGMENT = 0x2;
+export function createSkyBindGroupLayout(device) {
+    return device.createBindGroupLayout({
+        label: 'sky.bindGroupLayout',
+        entries: [
+            {
+                binding: SKY_BINDING,
+                visibility: VISIBILITY_FRAGMENT,
+                buffer: { type: 'uniform', minBindingSize: SKY_UNIFORM_SIZE },
+            },
+        ],
+    });
+}
+export function createSkyBindGroup(device, layout, uniforms) {
+    return device.createBindGroup({
+        label: 'sky.bindGroup',
+        layout,
+        entries: [{ binding: SKY_BINDING, resource: { buffer: uniforms, size: SKY_UNIFORM_SIZE } }],
+    });
+}
+/**
+ * The sky pipeline.
+ *
+ * **Depth is tested but not written**, which is what `gl.depthMask(false)` does on the
+ * WebGL2 path. The sky sits at the far plane, so writing its depth would push every later
+ * pass behind it; not testing at all would paint it over geometry already drawn.
+ */
+export function skyPipeline(cache, device, layout) {
+    return cache.get('sky', () => ({
+        label: 'sky',
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: shaderModule(device, { label: 'sky.vert', code: SKY_VERT_WGSL }),
+            entryPoint: 'main',
+            buffers: [],
+        },
+        fragment: {
+            module: shaderModule(device, { label: 'sky.frag', code: SKY_FRAG_WGSL }),
+            entryPoint: 'main',
+            targets: [{ format: cache.format }],
+        },
+        primitive: { topology: 'triangle-list' },
+        multisample: { count: cache.sampleCount },
+        depthStencil: {
+            format: DEPTH_FORMAT,
+            depthWriteEnabled: false,
+            /*
+             * `less-equal` rather than `less`: the triangle is emitted at exactly the far plane,
+             * and a cleared depth buffer holds exactly that value, so `less` would reject every
+             * fragment and the sky would never appear.
+             */
+            depthCompare: DEPTH_COMPARE_EQUAL,
+        },
+    }));
+}

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

@@ -0,0 +1,41 @@
+import type { SurfaceTextureOptions } from '../../surfaceTexture.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+/** How many levels an image of this size has, counting the one it arrives with. */
+export declare function mipLevelCount(width: number, height: number): number;
+/** An image uploaded once and bound per material. */
+export declare class GpuSurfaceTexture {
+    private readonly device;
+    private readonly pipelines;
+    readonly view: GPUTextureView;
+    readonly sampler: GPUSampler;
+    private texture;
+    private readonly format;
+    private readonly mipmapped;
+    private readonly levels;
+    private readonly width;
+    private readonly height;
+    constructor(device: GPUDevice, pipelines: PipelineCache, source: TexImageSource, options?: SurfaceTextureOptions);
+    /**
+     * Replace the pixels, keeping the texture, its view and its sampler.
+     *
+     * The binding a draw loop already holds stays valid, so the swap is a swap rather than a
+     * rebuild — the same argument `surfaceTexture.ts` makes. Not a hot path: it re-uploads the
+     * whole image and rebuilds the chain.
+     */
+    update(source: TexImageSource): void;
+    dispose(): void;
+    private upload;
+    /**
+     * Each level rendered from the one above it, which is what WebGPU asks for instead of a call.
+     *
+     * One encoder and one pass per level, submitted together. The source view is a single level
+     * so the sample cannot read the level being written, which would be the same texture bound as
+     * an attachment and a resource at once — rejected, and rejected silently enough to matter.
+     */
+    private generateMips;
+    /**
+     * Cached per format, because the two differ: an `-srgb` target encodes on write, and blitting
+     * a linear chain through a pipeline declared for the other one is a gamma error per level.
+     */
+    private mipPipeline;
+}

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

@@ -0,0 +1,228 @@
+import { shaderModule } from './shaderModules.js';
+/**
+ * A caller's image on the device, and the mip chain WebGPU will not build for it.
+ *
+ * The boundary is `surfaceTexture.ts`'s and is unchanged: the engine ships no image assets and
+ * fetches nothing, so what arrives is a `TexImageSource` the consumer already has. This owns
+ * the texture and the sampler; where the pixels came from stays the caller's business.
+ *
+ * **The one real difference from WebGL2 is mipmaps.** `gl.generateMipmap` is a single call and
+ * WebGPU has no equivalent at all — a chain is built by rendering each level from the one above
+ * it. So this carries a blit pipeline and spends a render pass per level, once, at upload.
+ * Everything else is a rename: `UNPACK_FLIP_Y_WEBGL` is `flipY` on the copy, `SRGB8_ALPHA8` is
+ * the `-srgb` format suffix, and anisotropy is a sampler field rather than an extension.
+ */
+const DEFAULT_ANISOTROPY = 4;
+/**
+ * The blit that fills one mip level from the level above it.
+ *
+ * A fullscreen triangle from `vertex_index` rather than a quad from a buffer, because this
+ * shader is this file's own — it is not generated from GLSL and has no WebGL2 counterpart to
+ * stay honest against. `textureSampleLevel` at 0 reads the source view, which is a single level.
+ */
+const MIP_WGSL = `
+struct Varying {
+  @builtin(position) position: vec4<f32>,
+  @location(0) uv: vec2<f32>,
+}
+
+@vertex
+fn vertexMain(@builtin(vertex_index) index: u32) -> Varying {
+  var out: Varying;
+  let x = f32((index << 1u) & 2u);
+  let y = f32(index & 2u);
+  out.uv = vec2<f32>(x, y);
+  out.position = vec4<f32>(x * 2.0 - 1.0, 1.0 - y * 2.0, 0.0, 1.0);
+  return out;
+}
+
+@group(0) @binding(0) var source: texture_2d<f32>;
+@group(0) @binding(1) var samp: sampler;
+
+@fragment
+fn fragmentMain(in: Varying) -> @location(0) vec4<f32> {
+  return textureSampleLevel(source, samp, in.uv, 0.0);
+}
+`;
+/** How many levels an image of this size has, counting the one it arrives with. */
+export function mipLevelCount(width, height) {
+    return Math.floor(Math.log2(Math.max(width, height))) + 1;
+}
+function sourceSize(source) {
+    const candidate = source;
+    const width = candidate.videoWidth ?? candidate.width ?? 0;
+    const height = candidate.videoHeight ?? candidate.height ?? 0;
+    return { width: Math.max(1, width), height: Math.max(1, height) };
+}
+/** An image uploaded once and bound per material. */
+export class GpuSurfaceTexture {
+    device;
+    pipelines;
+    view;
+    sampler;
+    texture;
+    format;
+    mipmapped;
+    levels;
+    width;
+    height;
+    constructor(device, pipelines, source, options = {}) {
+        this.device = device;
+        this.pipelines = pipelines;
+        const { width, height } = sourceSize(source);
+        this.width = width;
+        this.height = height;
+        this.mipmapped = options.mipmap ?? true;
+        this.levels = this.mipmapped ? mipLevelCount(width, height) : 1;
+        /* `SRGB8_ALPHA8`'s equivalent. Decoded in the sampler, before filtering, which is the only
+           place it is correct — `surfaceTexture.ts` makes the argument in full. */
+        this.format = (options.colorSpace ?? 'linear') === 'srgb' ? 'rgba8unorm-srgb' : 'rgba8unorm';
+        this.texture = device.createTexture({
+            label: 'surface.texture',
+            size: [width, height],
+            format: this.format,
+            mipLevelCount: this.levels,
+            /*
+             * **`RENDER_ATTACHMENT` is required by `copyExternalImageToTexture`, not by the mip
+             * chain**, and the difference matters enough to state.
+             *
+             * This used to say the flag was there "because building the chain renders into levels 1
+             * and below", which is true and is not the reason. The upload itself demands it: Dawn
+             * rejects a destination without `CopyDst | RenderAttachment` outright, whatever its mip
+             * count. Gating it on `levels > 1` therefore breaks every unmipped texture, and the read
+             * of the old comment that led there cost a broken build to disprove.
+             *
+             * So it cannot be dropped to make a sampled-only allocation, and anything that wants one
+             * has to leave `copyExternalImageToTexture` behind and write raw pixels instead, which
+             * trades a driver cost for a CPU readback.
+             */
+            usage: 0x2 | 0x4 | 0x10, // COPY_DST | TEXTURE_BINDING | RENDER_ATTACHMENT
+        });
+        this.view = this.texture.createView();
+        const wrap = (options.wrap ?? 'repeat') === 'repeat' ? 'repeat' : 'clamp-to-edge';
+        /*
+         * Nearest where the caller said their pixels are the subject. `mipmapFilter` stays as it was:
+         * the choice is about magnification, and taking the nearest mip *level* as well would trade a
+         * smear for a visible pop as the camera pulls back. See `SurfaceTextureOptions.filter`.
+         */
+        const nearest = options.filter === 'nearest';
+        this.sampler = device.createSampler({
+            label: 'surface.sampler',
+            addressModeU: wrap,
+            addressModeV: wrap,
+            magFilter: nearest ? 'nearest' : 'linear',
+            minFilter: nearest ? 'nearest' : 'linear',
+            mipmapFilter: this.mipmapped ? 'linear' : 'nearest',
+            /*
+             * A sampler field here, where WebGL2 needs `EXT_texture_filter_anisotropic`. **Only legal
+             * above 1 when every filter is `linear`**, which is why it is gated on the mip chain — with
+             * `mipmapFilter: 'nearest'` a value above 1 is a validation error rather than a nicety — and
+             * now on the filter too.
+             *
+             * **That second gate is a real asymmetry between the backends and not a tidy-up.** WebGL2
+             * accepts the anisotropy parameter beside `NEAREST` and simply gets nothing useful from it;
+             * WebGPU refuses the sampler outright, and a refused sampler is a bind group that never
+             * builds and a frame that draws nothing at all. So a caller asking for nearest gets 1 here
+             * and an ignored request there, which is the same picture by two routes.
+             */
+            maxAnisotropy: this.mipmapped && !nearest
+                ? Math.max(1, Math.floor(options.anisotropy ?? DEFAULT_ANISOTROPY))
+                : 1,
+        });
+        this.upload(source);
+    }
+    /**
+     * Replace the pixels, keeping the texture, its view and its sampler.
+     *
+     * The binding a draw loop already holds stays valid, so the swap is a swap rather than a
+     * rebuild — the same argument `surfaceTexture.ts` makes. Not a hot path: it re-uploads the
+     * whole image and rebuilds the chain.
+     */
+    update(source) {
+        if (this.texture === null)
+            return;
+        this.upload(source);
+    }
+    dispose() {
+        if (this.texture === null)
+            return;
+        this.texture.destroy();
+        this.texture = null;
+    }
+    upload(source) {
+        const texture = this.texture;
+        if (texture === null)
+            return;
+        /*
+         * **No flip, matching WebGL2 — and this is where the two APIs differ most quietly.**
+         *
+         * `UNPACK_FLIP_Y_WEBGL` is ignored for an `ImageBitmap` and honoured for a canvas, so that
+         * backend flipped one source type and not the other. `copyExternalImageToTexture`'s `flipY`
+         * has no such exception and flips both. So a `flipY: true` here was *self*-consistent and
+         * disagreed with WebGL2 on exactly the sources `drftLoader` uses for every model texture.
+         *
+         * The orientation check that passed this backend was run on a canvas alone, where the two
+         * agreed. Measure both source types, or a texture pipeline is half tested.
+         */
+        this.device.queue.copyExternalImageToTexture({ source: source, flipY: false }, { texture }, [this.width, this.height]);
+        if (this.levels > 1)
+            this.generateMips(texture);
+    }
+    /**
+     * Each level rendered from the one above it, which is what WebGPU asks for instead of a call.
+     *
+     * One encoder and one pass per level, submitted together. The source view is a single level
+     * so the sample cannot read the level being written, which would be the same texture bound as
+     * an attachment and a resource at once — rejected, and rejected silently enough to matter.
+     */
+    generateMips(texture) {
+        const pipeline = this.mipPipeline();
+        const sampler = this.device.createSampler({
+            label: 'surface.mipSampler',
+            magFilter: 'linear',
+            minFilter: 'linear',
+        });
+        const encoder = this.device.createCommandEncoder({ label: 'surface.mips' });
+        for (let level = 1; level < this.levels; level++) {
+            const source = texture.createView({ baseMipLevel: level - 1, mipLevelCount: 1 });
+            const target = texture.createView({ baseMipLevel: level, mipLevelCount: 1 });
+            const pass = encoder.beginRenderPass({
+                label: `surface.mip${level}`,
+                colorAttachments: [
+                    { view: target, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
+                ],
+            });
+            pass.setPipeline(pipeline);
+            pass.setBindGroup(0, this.device.createBindGroup({
+                layout: pipeline.getBindGroupLayout(0),
+                entries: [
+                    { binding: 0, resource: source },
+                    { binding: 1, resource: sampler },
+                ],
+            }));
+            pass.draw(3);
+            pass.end();
+        }
+        this.device.queue.submit([encoder.finish()]);
+    }
+    /**
+     * Cached per format, because the two differ: an `-srgb` target encodes on write, and blitting
+     * a linear chain through a pipeline declared for the other one is a gamma error per level.
+     */
+    mipPipeline() {
+        return this.pipelines.get(`surface.mip:${this.format}`, () => ({
+            label: `surface.mip:${this.format}`,
+            layout: 'auto',
+            vertex: {
+                module: shaderModule(this.device, { label: 'surface.mip', code: MIP_WGSL }),
+                entryPoint: 'vertexMain',
+            },
+            fragment: {
+                module: shaderModule(this.device, { label: 'surface.mip', code: MIP_WGSL }),
+                entryPoint: 'fragmentMain',
+                targets: [{ format: this.format }],
+            },
+            primitive: { topology: 'triangle-list' },
+        }));
+    }
+}

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

@@ -0,0 +1,73 @@
+import { TextLayout } from '../../textLayout.ts';
+import type { UniformFields } from './scatterPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+/**
+ * The text pass: a string as instanced glyph cubes, drawn over the scene.
+ *
+ * The layout is `textLayout.ts`'s and is shared with WebGL2 — this owns four buffers and the
+ * pipeline. Two of the buffers are the cube, uploaded once and shared by every text object; two
+ * are per object and re-uploaded only when the string changes.
+ */
+export declare const TEXT_VERT_FIELDS: UniformFields;
+export declare const TEXT_VERT_SIZE: 128;
+export declare const TEXT_FRAG_FIELDS: UniformFields;
+export declare const TEXT_FRAG_SIZE: 32;
+/** The cube every text object instances, built once for the device rather than per object. */
+export interface GpuTextCube {
+    readonly positions: GPUBuffer;
+    readonly normals: GPUBuffer;
+    readonly vertexCount: number;
+    dispose(): void;
+}
+export declare function createGpuTextCube(device: GPUDevice): GpuTextCube;
+/**
+ * One text object on the device: the layout, and the two instance buffers it fills.
+ *
+ * `setText` uploads only when the layout says something moved, which is the skip the whole
+ * design exists for — most frames show the message the frame before did.
+ */
+export declare class GpuText {
+    private readonly device;
+    readonly layout: TextLayout;
+    readonly cells: GPUBuffer;
+    readonly chars: GPUBuffer;
+    constructor(device: GPUDevice);
+    setText(content: string): void;
+    setPlate(widthCells: number, heightCells: number, bottomCell: number): void;
+    dispose(): void;
+    /**
+     * Whole slots rather than the used prefix.
+     *
+     * `writeBuffer` takes a byte length that must be a multiple of four, and the count of cells
+     * is arbitrary — so this writes what the layout holds and lets the instance count decide
+     * what is drawn. The arrays are reused in place, so the tail is last frame's and unread.
+     */
+    private upload;
+}
+/**
+ * Four buffers: the cube's two, and the object's two at one step per instance.
+ *
+ * Not interleaved, matching what `TextRenderer` binds on the other backend and for the same
+ * reason: they are four separate arrays on both sides, and four of eight slots is nothing.
+ */
+export declare function textVertexLayouts(): GPUVertexBufferLayout[];
+export declare function createTextBindGroupLayout(device: GPUDevice): GPUBindGroupLayout;
+/** Bound once against both rings; a dynamic offset per string. See `createPanelBindGroup`. */
+export declare function createTextBindGroup(device: GPUDevice, layout: GPUBindGroupLayout, vertices: GPUBuffer, fragments: GPUBuffer): GPUBindGroup;
+/**
+ * The pipeline.
+ *
+ * **Depth tested and depth written, against a buffer the caller has just cleared.** Turning
+ * depth off is the obvious move and is wrong: the cubes are solid, so with nothing sorting them
+ * the last face drawn wins and every letter renders as one flat facet. A cleared buffer puts
+ * the message in front of the scene while still letting its own geometry sort against itself,
+ * which is what gives the glyphs their edges. WebGL2 calls `gl.clear` mid-frame for this;
+ * WebGPU cannot, so the renderer opens a pass whose `depthLoadOp` is `clear` instead.
+ *
+ * **Back faces culled, and the cube is wound backwards on purpose so that means the right
+ * thing.** `textLayout.ts` explains: the shader flips Y, a mirror reverses winding, so faces
+ * authored the usual way come out back-facing and every one of them is culled. On this backend
+ * the toolchain's own Y negation and `uClipCorrection` cancel, so the winding that reaches the
+ * rasteriser is the one WebGL2 sees and this matches it.
+ */
+export declare function textPipeline(cache: PipelineCache, device: GPUDevice, layout: GPUBindGroupLayout): GPURenderPipeline;

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

@@ -0,0 +1,190 @@
+import { DEPTH_COMPARE_EQUAL } from '../../depthConvention.js';
+import { TEXT_BINDINGS, TEXT_FRAG_WGSL, TEXT_VERT_WGSL, } from '../../shaders/generated/text.wgsl.js';
+import { MAX_CELLS, TEXT_CUBE, TextLayout } from '../../textLayout.js';
+import { DEPTH_FORMAT } from './flatPass.js';
+import { shaderModule } from './shaderModules.js';
+/**
+ * The text pass: a string as instanced glyph cubes, drawn over the scene.
+ *
+ * The layout is `textLayout.ts`'s and is shared with WebGL2 — this owns four buffers and the
+ * pipeline. Two of the buffers are the cube, uploaded once and shared by every text object; two
+ * are per object and re-uploaded only when the string changes.
+ */
+export const TEXT_VERT_FIELDS = TEXT_BINDINGS.TEXT_VERT.fields;
+export const TEXT_VERT_SIZE = TEXT_BINDINGS.TEXT_VERT.uniformSize;
+export const TEXT_FRAG_FIELDS = TEXT_BINDINGS.TEXT_FRAG.fields;
+export const TEXT_FRAG_SIZE = TEXT_BINDINGS.TEXT_FRAG.uniformSize;
+const VERT_BINDING = TEXT_BINDINGS.TEXT_VERT.uniforms;
+const FRAG_BINDING = TEXT_BINDINGS.TEXT_FRAG.uniforms;
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008; // VERTEX | COPY_DST
+export function createGpuTextCube(device) {
+    const upload = (data, label) => {
+        const buffer = device.createBuffer({ label, size: data.byteLength, usage: USAGE_VERTEX });
+        device.queue.writeBuffer(buffer, 0, data);
+        return buffer;
+    };
+    const positions = upload(TEXT_CUBE.positions, 'text.positions');
+    const normals = upload(TEXT_CUBE.normals, 'text.normals');
+    return {
+        positions,
+        normals,
+        vertexCount: TEXT_CUBE.vertexCount,
+        dispose() {
+            positions.destroy();
+            normals.destroy();
+        },
+    };
+}
+/**
+ * One text object on the device: the layout, and the two instance buffers it fills.
+ *
+ * `setText` uploads only when the layout says something moved, which is the skip the whole
+ * design exists for — most frames show the message the frame before did.
+ */
+export class GpuText {
+    device;
+    layout = new TextLayout();
+    cells;
+    chars;
+    constructor(device) {
+        this.device = device;
+        this.cells = device.createBuffer({
+            label: 'text.cells',
+            size: MAX_CELLS * 2 * 4,
+            usage: USAGE_VERTEX,
+        });
+        this.chars = device.createBuffer({
+            label: 'text.chars',
+            size: MAX_CELLS * 4,
+            usage: USAGE_VERTEX,
+        });
+    }
+    setText(content) {
+        if (this.layout.setText(content))
+            this.upload();
+    }
+    setPlate(widthCells, heightCells, bottomCell) {
+        if (this.layout.setPlate(widthCells, heightCells, bottomCell))
+            this.upload();
+    }
+    dispose() {
+        this.cells.destroy();
+        this.chars.destroy();
+    }
+    /**
+     * Whole slots rather than the used prefix.
+     *
+     * `writeBuffer` takes a byte length that must be a multiple of four, and the count of cells
+     * is arbitrary — so this writes what the layout holds and lets the instance count decide
+     * what is drawn. The arrays are reused in place, so the tail is last frame's and unread.
+     */
+    upload() {
+        this.device.queue.writeBuffer(this.cells, 0, this.layout.cells);
+        this.device.queue.writeBuffer(this.chars, 0, this.layout.chars);
+    }
+}
+/**
+ * Four buffers: the cube's two, and the object's two at one step per instance.
+ *
+ * Not interleaved, matching what `TextRenderer` binds on the other backend and for the same
+ * reason: they are four separate arrays on both sides, and four of eight slots is nothing.
+ */
+export function textVertexLayouts() {
+    return [
+        {
+            arrayStride: 12,
+            attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }],
+        },
+        {
+            arrayStride: 12,
+            attributes: [{ shaderLocation: 1, offset: 0, format: 'float32x3' }],
+        },
+        {
+            arrayStride: 8,
+            stepMode: 'instance',
+            attributes: [{ shaderLocation: 2, offset: 0, format: 'float32x2' }],
+        },
+        {
+            arrayStride: 4,
+            stepMode: 'instance',
+            attributes: [{ shaderLocation: 3, offset: 0, format: 'float32' }],
+        },
+    ];
+}
+export function createTextBindGroupLayout(device) {
+    return device.createBindGroupLayout({
+        label: 'text.layout',
+        entries: [
+            {
+                binding: VERT_BINDING,
+                visibility: VISIBILITY_VERTEX,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: TEXT_VERT_SIZE },
+            },
+            {
+                binding: FRAG_BINDING,
+                visibility: VISIBILITY_FRAGMENT,
+                buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: TEXT_FRAG_SIZE },
+            },
+        ],
+    });
+}
+/** Bound once against both rings; a dynamic offset per string. See `createPanelBindGroup`. */
+export function createTextBindGroup(device, layout, vertices, fragments) {
+    return device.createBindGroup({
+        label: 'text.bindGroup',
+        layout,
+        entries: [
+            { binding: VERT_BINDING, resource: { buffer: vertices, size: TEXT_VERT_SIZE } },
+            { binding: FRAG_BINDING, resource: { buffer: fragments, size: TEXT_FRAG_SIZE } },
+        ],
+    });
+}
+/**
+ * The pipeline.
+ *
+ * **Depth tested and depth written, against a buffer the caller has just cleared.** Turning
+ * depth off is the obvious move and is wrong: the cubes are solid, so with nothing sorting them
+ * the last face drawn wins and every letter renders as one flat facet. A cleared buffer puts
+ * the message in front of the scene while still letting its own geometry sort against itself,
+ * which is what gives the glyphs their edges. WebGL2 calls `gl.clear` mid-frame for this;
+ * WebGPU cannot, so the renderer opens a pass whose `depthLoadOp` is `clear` instead.
+ *
+ * **Back faces culled, and the cube is wound backwards on purpose so that means the right
+ * thing.** `textLayout.ts` explains: the shader flips Y, a mirror reverses winding, so faces
+ * authored the usual way come out back-facing and every one of them is culled. On this backend
+ * the toolchain's own Y negation and `uClipCorrection` cancel, so the winding that reaches the
+ * rasteriser is the one WebGL2 sees and this matches it.
+ */
+export function textPipeline(cache, device, layout) {
+    return cache.get('text', () => ({
+        label: 'text',
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        vertex: {
+            module: shaderModule(device, { label: 'text.vert', code: TEXT_VERT_WGSL }),
+            entryPoint: 'main',
+            buffers: textVertexLayouts(),
+        },
+        fragment: {
+            module: shaderModule(device, { label: 'text.frag', code: 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: true,
+            depthCompare: DEPTH_COMPARE_EQUAL,
+        },
+    }));
+}