@driftengine/ui2d 3.62.0 → 3.63.0

package/README.md

@@ -119,6 +119,33 @@ decodes and the pass's own output transform re-encodes, so the blend happens in
 `filter` defaults to `nearest`, because a sheet is usually pixel art and linear filtering is the
 thing that makes pixel art look wrong.
 
+### Type in an atlas wants `mipmap: true`
+
+`mipmap` defaults to false, which is right for pixel art: a chain is memory nothing samples, and at
+a distance it dissolves art whose whole point is the pixel. **A glyph page is the sheet where that
+default is wrong.** Bake one page at 96 px, draw body copy at 11, and that is a 7x minification:
+`linear` reads four texels out of a footprint covering dozens, so a `t` crossbar two texels tall
+lands on about a quarter of a pixel and survives or not depending on where the sample falls. A
+player reported it as `Step-In Uppercut` reading `Slep-In Uppercul`, with the same letter surviving
+in one word and not the next, so the line looked unevenly spaced as well as misread.
+
+```ts
+sprites.setTexture(0, glyphPage, { filter: 'linear', mipmap: true });
+```
+
+Measured on `demo/dev/glyphMip.ts`, twelve copies of one glyph at different subpixel offsets: the
+ink varies between copies with a standard deviation of **0.0130** plain and **0.0020** mipmapped, so
+**6.6x less** copy-to-copy disagreement, identical on both backends. `scripts/glyph-mip-check.mjs`
+is that measurement as a gate.
+
+With `filter: 'linear'` this is trilinear. With `filter: 'nearest'` the levels are still blended,
+because that is minification and `filter` is about magnification.
+
+**Pad the cells yourself.** A lower level mixes texels the packer put next to each other, so a sheet
+whose frames touch shows its neighbours once the chain is deep enough to reach them. How much
+padding depends on how far down the sheet is ever sampled, which is a fact about the sheet rather
+than about the sampler — the engine cannot size it for you.
+
 **Neither backend flips the image.** `surfaceTexture.ts` in core carries the whole argument and the
 bug it came from: WebGL2 ignores `UNPACK_FLIP_Y_WEBGL` for an `ImageBitmap` and honours it for a
 canvas, so a pipeline checked with one source type is half checked. `scripts/sprite-check.mjs`

package/dist/spriteGl.js

@@ -97,9 +97,21 @@ export function setWebgl2SpriteTexture(gl, sprites, slot, source, options) {
     gl.bindTexture(gl.TEXTURE_2D, texture);
     const internal = options.colorSpace === 'linear' ? gl.RGBA : gl.SRGB8_ALPHA8;
     gl.texImage2D(gl.TEXTURE_2D, 0, internal, gl.RGBA, gl.UNSIGNED_BYTE, source);
-    const filter = options.filter === 'linear' ? gl.LINEAR : gl.NEAREST;
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
+    const linear = options.filter === 'linear';
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, linear ? gl.LINEAR : gl.NEAREST);
+    /*
+     * **Minification is the chain's question and magnification is `filter`'s**, which is why the two
+     * are set apart here. A mipmapped sheet blends *between* levels whichever filter was asked for:
+     * that is what stops a stroke disappearing on the way down, and `filter` still decides whether
+     * the texels inside a level are blended. `SurfaceTexture` splits it the same way.
+     */
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, options.mipmap === true
+        ? linear
+            ? gl.LINEAR_MIPMAP_LINEAR
+            : gl.NEAREST_MIPMAP_LINEAR
+        : linear
+            ? gl.LINEAR
+            : gl.NEAREST);
     /*
      * Clamped on both axes, and it is a correctness rule rather than a default. A sheet frame's
      * edge texel is adjacent to the *next* frame's, so a repeating wrap bleeds one sprite into
@@ -107,6 +119,10 @@ export function setWebgl2SpriteTexture(gl, sprites, slot, source, options) {
      */
     gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
     gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    /* After the upload, which is the only order that works: the chain is built from level 0, and a
+       driver that has not been given one yet builds nothing from it. */
+    if (options.mipmap === true)
+        gl.generateMipmap(gl.TEXTURE_2D);
     gl.bindTexture(gl.TEXTURE_2D, null);
     gl.activeTexture(gl.TEXTURE0);
     sprites.textures[slot] = texture;

package/dist/spriteGpu.d.ts

@@ -1,5 +1,6 @@
 /** The WebGPU half of the sprite pass: one pipeline, one instance buffer, a bind group per slot. */
 import type { SpriteBatch } from './spriteBatch.ts';
+import { type MipPipelines } from '@driftengine/core';
 import type { SpriteImage, SpriteTextureOptions } from './spriteTexture.ts';
 export interface GpuSpriteSlot {
     readonly texture: GPUTexture;
@@ -14,7 +15,11 @@ export interface GpuSprites {
     readonly samplers: {
         readonly nearest: GPUSampler;
         readonly linear: GPUSampler;
+        readonly nearestMip: GPUSampler;
+        readonly linearMip: GPUSampler;
     };
+    /** One mip-blit pipeline per format, built on first use. See `generateMipChain`. */
+    readonly mipPipelines: MipPipelines;
     readonly slots: (GpuSpriteSlot | null)[];
     readonly vertexScratch: ArrayBuffer;
     readonly vertexFloats: Float32Array;

package/dist/spriteGpu.js

@@ -1,6 +1,16 @@
 /** The WebGPU half of the sprite pass: one pipeline, one instance buffer, a bind group per slot. */
 import { SPRITE_BINDINGS, SPRITE_FRAG_WGSL, SPRITE_VERT_WGSL, } from './shaders/generated/sprite.wgsl.js';
 import { SPRITE_FLOATS } from './spriteBatch.js';
+/*
+ * **The first runtime import this package takes from the engine, and it was measured before it was
+ * taken.** Everything else here is `import type`, which erases, so `ui2d` has had no runtime edge
+ * to `core` at all — and a value import from a barrel is how a package quietly acquires the whole
+ * of another one. Bundled alone, with the import and with it stubbed out: **32,801 against 31,031
+ * raw and 11,777 against 11,163 gzipped**, so 614 gzipped bytes, which is the blit and its shader
+ * and nothing else. The alternative was a second copy of the mip blit living here, and the second
+ * copy is the one that ends up disagreeing about the colour space.
+ */
+import { generateMipChain, mipLevelCount } from '@driftengine/core';
 const VERT = SPRITE_BINDINGS.SPRITE_VERT;
 const FRAG = SPRITE_BINDINGS.SPRITE_FRAG;
 const STRIDE = SPRITE_FLOATS * 4;
@@ -104,7 +114,23 @@ export function createGpuSprites(device, format, depthFormat, samples, capacity,
                 magFilter: 'linear',
                 minFilter: 'linear',
             }),
+            /*
+             * The mipmapped pair. `mipmapFilter` is the level blend and is `linear` in both, because
+             * that is minification; `magFilter` is what `filter` was asked about. Four samplers rather
+             * than two because the questions are independent, and the same split `SurfaceTexture` makes.
+             */
+            nearestMip: device.createSampler({
+                label: `${label}.nearestMip`,
+                mipmapFilter: 'linear',
+            }),
+            linearMip: device.createSampler({
+                label: `${label}.linearMip`,
+                magFilter: 'linear',
+                minFilter: 'linear',
+                mipmapFilter: 'linear',
+            }),
         },
+        mipPipelines: mipPipelineCache(device),
         slots: new Array(slots).fill(null),
         vertexScratch,
         vertexFloats: new Float32Array(vertexScratch),
@@ -113,14 +139,39 @@ export function createGpuSprites(device, format, depthFormat, samples, capacity,
         fragmentInts: new Int32Array(fragmentScratch),
     };
 }
+/**
+ * One pipeline per format, kept on the sprite pass rather than in the renderer's cache.
+ *
+ * The renderer's `PipelineCache` is not reachable from a contributed pass, and the chain builder
+ * takes an interface for exactly that reason. A `Map` is the whole of what is needed: there are at
+ * most two formats here, and they are built once each.
+ */
+function mipPipelineCache(device) {
+    const built = new Map();
+    return {
+        get(key, describe) {
+            const existing = built.get(key);
+            if (existing !== undefined)
+                return existing;
+            const pipeline = device.createRenderPipeline(describe());
+            built.set(key, pipeline);
+            return pipeline;
+        },
+    };
+}
 export function setGpuSpriteTexture(device, sprites, slot, source, options) {
     const previous = sprites.slots[slot];
     if (previous !== null && previous !== undefined)
         previous.texture.destroy();
+    const format = options.colorSpace === 'linear' ? 'rgba8unorm' : 'rgba8unorm-srgb';
+    /* One level unless a chain was asked for. `TEXTURE_USAGE` already carries RENDER_ATTACHMENT,
+       which is what the blit needs to draw into each level. */
+    const levels = options.mipmap === true ? mipLevelCount(source.width, source.height) : 1;
     const texture = device.createTexture({
         label: `ui2d.sprite.${slot}`,
         size: [source.width, source.height],
-        format: options.colorSpace === 'linear' ? 'rgba8unorm' : 'rgba8unorm-srgb',
+        format,
+        mipLevelCount: levels,
         usage: TEXTURE_USAGE,
     });
     /*
@@ -130,7 +181,17 @@ export function setGpuSpriteTexture(device, sprites, slot, source, options) {
      * the source type most callers use.
      */
     device.queue.copyExternalImageToTexture({ source: source, flipY: false }, { texture }, [source.width, source.height]);
-    const sampler = options.filter === 'linear' ? sprites.samplers.linear : sprites.samplers.nearest;
+    /* After the copy, which is the only order that works: every level is rendered from the one above
+       it, and level 0 has to hold the image before the chain can be built from it. */
+    generateMipChain(device, sprites.mipPipelines, texture, format, levels);
+    const linear = options.filter === 'linear';
+    const sampler = levels > 1
+        ? linear
+            ? sprites.samplers.linearMip
+            : sprites.samplers.nearestMip
+        : linear
+            ? sprites.samplers.linear
+            : sprites.samplers.nearest;
     const bindGroup = device.createBindGroup({
         label: `ui2d.sprite.${slot}.bindGroup`,
         layout: sprites.layout,

package/dist/spriteTexture.d.ts

@@ -32,5 +32,35 @@ export interface SpriteTextureOptions {
      * and saves the sharp case from a blur nobody asked for.
      */
     readonly filter?: 'nearest' | 'linear';
+    /**
+     * Whether to build a mip chain and sample it. `false` by default, which is the sheet above.
+     *
+     * **The case it exists for is type baked into an atlas.** The comment on `filter` says a sheet
+     * that is not pixel art "is normally drawn near its authored size, where the two filters differ
+     * by very little" — a glyph page is the sheet where that is not true. A consumer baking one page
+     * per weight at 96 px and drawing body copy at 11 is minifying **7x**, and `linear` reads four
+     * texels of a footprint that covers dozens: a `t` crossbar two texels tall lands on about a
+     * quarter of a pixel, and whether it survives depends on where the sample falls. Reported by a
+     * player as `Step-In Uppercut` reading `Slep-In Uppercul`, with different strokes lost per
+     * glyph and per position, so the line looks unevenly spaced as well as misread.
+     *
+     * Neither workaround available to a consumer is good: baking nearer the drawn size blurs the
+     * headings, because one atlas cannot serve an 8x range of sizes, and baking a second atlas for
+     * small text doubles the pages and the uploads and moves a sampling decision into the game where
+     * it has to be re-tuned whenever a size changes.
+     *
+     * **Off by default because the chain is wrong for pixel art**, which is what most sheets are: it
+     * is memory nothing samples, and at a distance it dissolves art whose whole point is the pixel.
+     *
+     * With `filter: 'linear'` this is trilinear — blended within a level and between levels. With
+     * `filter: 'nearest'` the levels are still blended, because that is minification and `filter` is
+     * about magnification; `SurfaceTexture` makes the same split and for the same reason.
+     *
+     * **Padding cells against bleed is the caller's problem**, and it has to be: a lower level mixes
+     * texels the atlas packer put next to each other, so a sheet whose frames touch will show its
+     * neighbours. How much padding depends on how far the chain is allowed to go, which is a fact
+     * about the sheet rather than about the sampler.
+     */
+    readonly mipmap?: boolean;
 }
 export declare const DEFAULT_SPRITE_TEXTURE_OPTIONS: SpriteTextureOptions;

package/dist/spriteTexture.js

@@ -2,4 +2,5 @@
 export const DEFAULT_SPRITE_TEXTURE_OPTIONS = {
     colorSpace: 'srgb',
     filter: 'nearest',
+    mipmap: false,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/ui2d",
-  "version": "3.62.0",
+  "version": "3.63.0",
   "description": "The 2D layer: batched sprites, sheets, tilemaps, and a retained interface tree over them",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,7 +27,7 @@
   ],
   "sideEffects": false,
   "peerDependencies": {
-    "@driftengine/core": "3.62.0"
+    "@driftengine/core": "3.63.0"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/spriteGl.ts

@@ -129,9 +129,25 @@ export function setWebgl2SpriteTexture(
   gl.bindTexture(gl.TEXTURE_2D, texture);
   const internal = options.colorSpace === 'linear' ? gl.RGBA : gl.SRGB8_ALPHA8;
   gl.texImage2D(gl.TEXTURE_2D, 0, internal, gl.RGBA, gl.UNSIGNED_BYTE, source);
-  const filter = options.filter === 'linear' ? gl.LINEAR : gl.NEAREST;
-  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
-  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
+  const linear = options.filter === 'linear';
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, linear ? gl.LINEAR : gl.NEAREST);
+  /*
+   * **Minification is the chain's question and magnification is `filter`'s**, which is why the two
+   * are set apart here. A mipmapped sheet blends *between* levels whichever filter was asked for:
+   * that is what stops a stroke disappearing on the way down, and `filter` still decides whether
+   * the texels inside a level are blended. `SurfaceTexture` splits it the same way.
+   */
+  gl.texParameteri(
+    gl.TEXTURE_2D,
+    gl.TEXTURE_MIN_FILTER,
+    options.mipmap === true
+      ? linear
+        ? gl.LINEAR_MIPMAP_LINEAR
+        : gl.NEAREST_MIPMAP_LINEAR
+      : linear
+        ? gl.LINEAR
+        : gl.NEAREST,
+  );
   /*
    * Clamped on both axes, and it is a correctness rule rather than a default. A sheet frame's
    * edge texel is adjacent to the *next* frame's, so a repeating wrap bleeds one sprite into
@@ -139,6 +155,9 @@ export function setWebgl2SpriteTexture(
    */
   gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
   gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  /* After the upload, which is the only order that works: the chain is built from level 0, and a
+     driver that has not been given one yet builds nothing from it. */
+  if (options.mipmap === true) gl.generateMipmap(gl.TEXTURE_2D);
   gl.bindTexture(gl.TEXTURE_2D, null);
   gl.activeTexture(gl.TEXTURE0);
   sprites.textures[slot] = texture;

package/src/spriteGpu.ts

@@ -7,6 +7,16 @@ import {
 } from './shaders/generated/sprite.wgsl.ts';
 import { SPRITE_FLOATS } from './spriteBatch.ts';
 import type { SpriteBatch } from './spriteBatch.ts';
+/*
+ * **The first runtime import this package takes from the engine, and it was measured before it was
+ * taken.** Everything else here is `import type`, which erases, so `ui2d` has had no runtime edge
+ * to `core` at all — and a value import from a barrel is how a package quietly acquires the whole
+ * of another one. Bundled alone, with the import and with it stubbed out: **32,801 against 31,031
+ * raw and 11,777 against 11,163 gzipped**, so 614 gzipped bytes, which is the blit and its shader
+ * and nothing else. The alternative was a second copy of the mip blit living here, and the second
+ * copy is the one that ends up disagreeing about the colour space.
+ */
+import { generateMipChain, mipLevelCount, type MipPipelines } from '@driftengine/core';
 import type { SpriteImage, SpriteTextureOptions } from './spriteTexture.ts';
 
 const VERT = SPRITE_BINDINGS.SPRITE_VERT;
@@ -30,7 +40,14 @@ export interface GpuSprites {
   readonly vertexUniforms: GPUBuffer;
   readonly fragmentUniforms: GPUBuffer;
   readonly instances: GPUBuffer;
-  readonly samplers: { readonly nearest: GPUSampler; readonly linear: GPUSampler };
+  readonly samplers: {
+    readonly nearest: GPUSampler;
+    readonly linear: GPUSampler;
+    readonly nearestMip: GPUSampler;
+    readonly linearMip: GPUSampler;
+  };
+  /** One mip-blit pipeline per format, built on first use. See `generateMipChain`. */
+  readonly mipPipelines: MipPipelines;
   readonly slots: (GpuSpriteSlot | null)[];
   readonly vertexScratch: ArrayBuffer;
   readonly vertexFloats: Float32Array;
@@ -146,7 +163,23 @@ export function createGpuSprites(
         magFilter: 'linear',
         minFilter: 'linear',
       }),
+      /*
+       * The mipmapped pair. `mipmapFilter` is the level blend and is `linear` in both, because
+       * that is minification; `magFilter` is what `filter` was asked about. Four samplers rather
+       * than two because the questions are independent, and the same split `SurfaceTexture` makes.
+       */
+      nearestMip: device.createSampler({
+        label: `${label}.nearestMip`,
+        mipmapFilter: 'linear',
+      }),
+      linearMip: device.createSampler({
+        label: `${label}.linearMip`,
+        magFilter: 'linear',
+        minFilter: 'linear',
+        mipmapFilter: 'linear',
+      }),
     },
+    mipPipelines: mipPipelineCache(device),
     slots: new Array<null>(slots).fill(null),
     vertexScratch,
     vertexFloats: new Float32Array(vertexScratch),
@@ -156,6 +189,26 @@ export function createGpuSprites(
   };
 }
 
+/**
+ * One pipeline per format, kept on the sprite pass rather than in the renderer's cache.
+ *
+ * The renderer's `PipelineCache` is not reachable from a contributed pass, and the chain builder
+ * takes an interface for exactly that reason. A `Map` is the whole of what is needed: there are at
+ * most two formats here, and they are built once each.
+ */
+function mipPipelineCache(device: GPUDevice): MipPipelines {
+  const built = new Map<string, GPURenderPipeline>();
+  return {
+    get(key: string, describe: () => GPURenderPipelineDescriptor): GPURenderPipeline {
+      const existing = built.get(key);
+      if (existing !== undefined) return existing;
+      const pipeline = device.createRenderPipeline(describe());
+      built.set(key, pipeline);
+      return pipeline;
+    },
+  };
+}
+
 export function setGpuSpriteTexture(
   device: GPUDevice,
   sprites: GpuSprites,
@@ -165,10 +218,16 @@ export function setGpuSpriteTexture(
 ): void {
   const previous = sprites.slots[slot];
   if (previous !== null && previous !== undefined) previous.texture.destroy();
+  const format: GPUTextureFormat =
+    options.colorSpace === 'linear' ? 'rgba8unorm' : 'rgba8unorm-srgb';
+  /* One level unless a chain was asked for. `TEXTURE_USAGE` already carries RENDER_ATTACHMENT,
+     which is what the blit needs to draw into each level. */
+  const levels = options.mipmap === true ? mipLevelCount(source.width, source.height) : 1;
   const texture = device.createTexture({
     label: `ui2d.sprite.${slot}`,
     size: [source.width, source.height],
-    format: options.colorSpace === 'linear' ? 'rgba8unorm' : 'rgba8unorm-srgb',
+    format,
+    mipLevelCount: levels,
     usage: TEXTURE_USAGE,
   });
   /*
@@ -182,7 +241,18 @@ export function setGpuSpriteTexture(
     { texture },
     [source.width, source.height],
   );
-  const sampler = options.filter === 'linear' ? sprites.samplers.linear : sprites.samplers.nearest;
+  /* After the copy, which is the only order that works: every level is rendered from the one above
+     it, and level 0 has to hold the image before the chain can be built from it. */
+  generateMipChain(device, sprites.mipPipelines, texture, format, levels);
+  const linear = options.filter === 'linear';
+  const sampler =
+    levels > 1
+      ? linear
+        ? sprites.samplers.linearMip
+        : sprites.samplers.nearestMip
+      : linear
+        ? sprites.samplers.linear
+        : sprites.samplers.nearest;
   const bindGroup = device.createBindGroup({
     label: `ui2d.sprite.${slot}.bindGroup`,
     layout: sprites.layout,

package/src/spriteTexture.ts

@@ -34,9 +34,40 @@ export interface SpriteTextureOptions {
    * and saves the sharp case from a blur nobody asked for.
    */
   readonly filter?: 'nearest' | 'linear';
+  /**
+   * Whether to build a mip chain and sample it. `false` by default, which is the sheet above.
+   *
+   * **The case it exists for is type baked into an atlas.** The comment on `filter` says a sheet
+   * that is not pixel art "is normally drawn near its authored size, where the two filters differ
+   * by very little" — a glyph page is the sheet where that is not true. A consumer baking one page
+   * per weight at 96 px and drawing body copy at 11 is minifying **7x**, and `linear` reads four
+   * texels of a footprint that covers dozens: a `t` crossbar two texels tall lands on about a
+   * quarter of a pixel, and whether it survives depends on where the sample falls. Reported by a
+   * player as `Step-In Uppercut` reading `Slep-In Uppercul`, with different strokes lost per
+   * glyph and per position, so the line looks unevenly spaced as well as misread.
+   *
+   * Neither workaround available to a consumer is good: baking nearer the drawn size blurs the
+   * headings, because one atlas cannot serve an 8x range of sizes, and baking a second atlas for
+   * small text doubles the pages and the uploads and moves a sampling decision into the game where
+   * it has to be re-tuned whenever a size changes.
+   *
+   * **Off by default because the chain is wrong for pixel art**, which is what most sheets are: it
+   * is memory nothing samples, and at a distance it dissolves art whose whole point is the pixel.
+   *
+   * With `filter: 'linear'` this is trilinear — blended within a level and between levels. With
+   * `filter: 'nearest'` the levels are still blended, because that is minification and `filter` is
+   * about magnification; `SurfaceTexture` makes the same split and for the same reason.
+   *
+   * **Padding cells against bleed is the caller's problem**, and it has to be: a lower level mixes
+   * texels the atlas packer put next to each other, so a sheet whose frames touch will show its
+   * neighbours. How much padding depends on how far the chain is allowed to go, which is a fact
+   * about the sheet rather than about the sampler.
+   */
+  readonly mipmap?: boolean;
 }
 
 export const DEFAULT_SPRITE_TEXTURE_OPTIONS: SpriteTextureOptions = {
   colorSpace: 'srgb',
   filter: 'nearest',
+  mipmap: false,
 };