@driftengine/core 3.61.0

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

@@ -0,0 +1,257 @@
+import type { SurfaceTextureOptions } from '../../surfaceTexture.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import { shaderModule } from './shaderModules.ts';
+
+/**
+ * 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: number, height: number): number {
+  return Math.floor(Math.log2(Math.max(width, height))) + 1;
+}
+
+function sourceSize(source: TexImageSource): { width: number; height: number } {
+  const candidate = source as {
+    width?: number;
+    height?: number;
+    videoWidth?: number;
+    videoHeight?: number;
+  };
+  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 {
+  readonly view: GPUTextureView;
+  readonly sampler: GPUSampler;
+
+  private texture: GPUTexture | null;
+  private readonly format: GPUTextureFormat;
+  private readonly mipmapped: boolean;
+  private readonly levels: number;
+  private readonly width: number;
+  private readonly height: number;
+
+  constructor(
+    private readonly device: GPUDevice,
+    private readonly pipelines: PipelineCache,
+    source: TexImageSource,
+    options: SurfaceTextureOptions = {},
+  ) {
+    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: GPUAddressMode =
+      (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: TexImageSource): void {
+    if (this.texture === null) return;
+    this.upload(source);
+  }
+
+  dispose(): void {
+    if (this.texture === null) return;
+    this.texture.destroy();
+    this.texture = null;
+  }
+
+  private upload(source: TexImageSource): void {
+    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 as GPUCopyExternalImageSource, 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.
+   */
+  private generateMips(texture: GPUTexture): void {
+    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.
+   */
+  private mipPipeline(): GPURenderPipeline {
+    return this.pipelines.get(`surface.mip:${this.format}`, () => ({
+      label: `surface.mip:${this.format}`,
+      layout: 'auto' as const,
+      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' as const },
+    }));
+  }
+}

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

@@ -0,0 +1,224 @@
+import { DEPTH_COMPARE_EQUAL } from '../../depthConvention.ts';
+import {
+  TEXT_BINDINGS,
+  TEXT_FRAG_WGSL,
+  TEXT_VERT_WGSL,
+} from '../../shaders/generated/text.wgsl.ts';
+import { MAX_CELLS, TEXT_CUBE, TextLayout } from '../../textLayout.ts';
+import type { UniformFields } from './scatterPass.ts';
+import { DEPTH_FORMAT } from './flatPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import { shaderModule } from './shaderModules.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 const TEXT_VERT_FIELDS: UniformFields = TEXT_BINDINGS.TEXT_VERT.fields;
+export const TEXT_VERT_SIZE = TEXT_BINDINGS.TEXT_VERT.uniformSize;
+export const TEXT_FRAG_FIELDS: UniformFields = 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
+
+/** 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 function createGpuTextCube(device: GPUDevice): GpuTextCube {
+  const upload = (data: Float32Array, label: string): GPUBuffer => {
+    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(): void {
+      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 {
+  readonly layout = new TextLayout();
+  readonly cells: GPUBuffer;
+  readonly chars: GPUBuffer;
+
+  constructor(private readonly device: GPUDevice) {
+    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: string): void {
+    if (this.layout.setText(content)) this.upload();
+  }
+
+  setPlate(widthCells: number, heightCells: number, bottomCell: number): void {
+    if (this.layout.setPlate(widthCells, heightCells, bottomCell)) this.upload();
+  }
+
+  dispose(): void {
+    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.
+   */
+  private upload(): void {
+    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(): GPUVertexBufferLayout[] {
+  return [
+    {
+      arrayStride: 12,
+      attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' as GPUVertexFormat }],
+    },
+    {
+      arrayStride: 12,
+      attributes: [{ shaderLocation: 1, offset: 0, format: 'float32x3' as GPUVertexFormat }],
+    },
+    {
+      arrayStride: 8,
+      stepMode: 'instance' as GPUVertexStepMode,
+      attributes: [{ shaderLocation: 2, offset: 0, format: 'float32x2' as GPUVertexFormat }],
+    },
+    {
+      arrayStride: 4,
+      stepMode: 'instance' as GPUVertexStepMode,
+      attributes: [{ shaderLocation: 3, offset: 0, format: 'float32' as GPUVertexFormat }],
+    },
+  ];
+}
+
+export function createTextBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+  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: GPUDevice,
+  layout: GPUBindGroupLayout,
+  vertices: GPUBuffer,
+  fragments: GPUBuffer,
+): GPUBindGroup {
+  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: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+): GPURenderPipeline {
+  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,
+    },
+  }));
+}