@driftengine/core 3.62.0 → 3.63.0

package/CHANGELOG.json

@@ -1,4 +1,15 @@
 [
+  {
+    "version": "3.63.0",
+    "date": "2026-09-14",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "A sprite sheet can carry a mip chain. Type baked into an atlas and drawn small was losing strokes, so a t read as an l and the same letter read differently in different words.",
+        "text": "**`mipmap` on `SpriteTextureOptions`, false by default.** A sprite sheet is usually pixel art, where a chain is memory nothing samples and a blur nobody asked for, so nothing changes for a sheet that does not ask. A glyph page is the sheet where that default is wrong, and the comment on `filter` said as much without offering a way out: it assumed a sheet that is not pixel art \"is normally drawn near its authored size, where the two filters differ by very little\".\n\nA consumer bakes one page per weight at 96 px and draws body copy at 11 to 13, which is about a **7x** minification. `linear` reads four texels out of a footprint covering dozens, so a `t` crossbar two texels tall lands on roughly 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` — and because the sample point moves with the glyph's position, the same letter survived in one word and not the next, which made the line look unevenly spaced as well as misread.\n\nNeither workaround was worth having: baking nearer the drawn size blurs the headings, because one atlas cannot serve the 8x range between body copy and a display size, and 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.\n\n**Measured rather than asserted.** `demo/dev/glyphMip.ts` draws one glyph twelve times at deliberately different subpixel offsets, through a plain sampler and through a chain, because the reported symptom is not missing ink but *inconsistent* ink — a build that samples well by luck passes an ink threshold and fails this. The copies' ink has a standard deviation of **0.0130** plain and **0.0020** mipmapped: **6.6x less** disagreement, and the two backends land on the same number to four decimal places. `scripts/glyph-mip-check.mjs` is that measurement as a gate, and it reddens with four failures when the chain is disabled.\n\nWith `filter: 'linear'` this is trilinear; with `filter: 'nearest'` the levels are still blended, because that is minification and `filter` is about magnification, which is the split `SurfaceTexture` already makes. Padding cells against bleed stays the caller's problem, since how much depends on how far down the sheet is ever sampled.\n\n**WebGPU has no `generateMipmap`**, so `generateMipChain` and `mipLevelCount` are public now: the per-level blit that `SurfaceTexture` has always carried is a free function rather than a private method, and `ui2d` calls it. Writing the blit a second time there would have been a second shader to keep in step, and the copy that quietly disagrees about the colour space is the one that ships. It is the first runtime import `ui2d` takes from the engine and it was measured before it was taken: bundled alone, **11,777 against 11,163 gzipped bytes**, so 614 for the blit and its shader."
+      }
+    ]
+  },
   {
     "version": "3.62.0",
     "date": "2026-09-13",

package/dist/index.d.ts

@@ -64,6 +64,7 @@ export { createVisitResult, visitVisible } from './scene/visit.ts';
 export type { VisitResult } from './scene/visit.ts';
 export type { PassContext, PassDefinition, PassDevice, PassHandle, PrepareContext, } from './render/pass.ts';
 export type { PassAttachmentOptions, PassTarget } from './render/passTarget.ts';
+export { generateMipChain, mipLevelCount, type MipPipelines, } from './render/backend/webgpu/surfaceTexturePass.ts';
 export { createPassAttachment } from './render/passTarget.ts';
 export type { FrameResource } from './render/frame/index.ts';
 export type { OcclusionOptions } from './render/occlusion.ts';

package/dist/index.js

@@ -67,6 +67,17 @@ export { apparentSize, lodForBounds } from './render/lod.js';
 export { SceneNode } from './scene/node.js';
 export { MAX_JOINTS, MAX_MORPH_TARGETS, SKIN_PALETTE_TEXTURE_UNIT, morphTexelIndex, paletteTextureWidth, } from './render/skinPalette.js';
 export { createVisitResult, visitVisible } from './scene/visit.js';
+/*
+ * The mip chain a pass has to build for itself on WebGPU, and the level count it needs to ask for.
+ *
+ * **Public because `gl.generateMipmap` has no WebGPU equivalent and every contributed pass that
+ * uploads a texture meets that the moment its texture is ever minified.** `ui2d` met it with a
+ * glyph atlas baked at 96 px and drawn at 11; writing the blit a second time there would have been
+ * a second WGSL shader to keep in step with this one, and the copy that quietly disagrees about
+ * the colour space is the one that would ship. `MipPipelines` is an interface rather than the
+ * renderer's cache so a pass can hand over a `Map` and nothing more.
+ */
+export { generateMipChain, mipLevelCount, } from './render/backend/webgpu/surfaceTexturePass.js';
 export { createPassAttachment } from './render/passTarget.js';
 export { OcclusionBuffer } from './render/occlusion.js';
 /*

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

@@ -2,6 +2,34 @@ 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;
+/**
+ * Somewhere to keep one pipeline per format. `PipelineCache` satisfies it; so does a `Map`.
+ *
+ * Taken as an interface rather than as the class, because the other caller of the chain below is
+ * `@driftengine/ui2d`, which builds its own pipeline from the device and has no cache of the
+ * renderer's to hand.
+ */
+export interface MipPipelines {
+    get(key: string, describe: () => GPURenderPipelineDescriptor): GPURenderPipeline;
+}
+/**
+ * Fill every level of a texture from the one above it, which is what WebGPU asks for instead of a
+ * call.
+ *
+ * **`gl.generateMipmap` is one line and WebGPU has no equivalent at all**, so this is the whole of
+ * the difference between the two backends for any texture that wants a chain. One encoder, one
+ * render pass per level, submitted together, once, at upload.
+ *
+ * The source view is a **single level**, so the sample cannot read the level being written — that
+ * would be one texture bound as an attachment and as a resource at once, which is rejected, and
+ * rejected quietly enough to matter.
+ *
+ * **A free function because there are two callers now.** A surface texture on a mesh has wanted a
+ * chain since it existed; a sprite sheet wanted one the day a consumer baked type into an atlas and
+ * drew it at a seventh of its authored size. Writing the blit twice would be two statements of one
+ * thing, and the second copy is the one that would quietly disagree about the format.
+ */
+export declare function generateMipChain(device: GPUDevice, pipelines: MipPipelines, texture: GPUTexture, format: GPUTextureFormat, levels: number): void;
 /** An image uploaded once and bound per material. */
 export declare class GpuSurfaceTexture {
     private readonly device;
@@ -33,9 +61,4 @@ export declare class GpuSurfaceTexture {
      * 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

@@ -48,6 +48,75 @@ fn fragmentMain(in: Varying) -> @location(0) vec4<f32> {
 export function mipLevelCount(width, height) {
     return Math.floor(Math.log2(Math.max(width, height))) + 1;
 }
+/**
+ * Fill every level of a texture from the one above it, which is what WebGPU asks for instead of a
+ * call.
+ *
+ * **`gl.generateMipmap` is one line and WebGPU has no equivalent at all**, so this is the whole of
+ * the difference between the two backends for any texture that wants a chain. One encoder, one
+ * render pass per level, submitted together, once, at upload.
+ *
+ * The source view is a **single level**, so the sample cannot read the level being written — that
+ * would be one texture bound as an attachment and as a resource at once, which is rejected, and
+ * rejected quietly enough to matter.
+ *
+ * **A free function because there are two callers now.** A surface texture on a mesh has wanted a
+ * chain since it existed; a sprite sheet wanted one the day a consumer baked type into an atlas and
+ * drew it at a seventh of its authored size. Writing the blit twice would be two statements of one
+ * thing, and the second copy is the one that would quietly disagree about the format.
+ */
+export function generateMipChain(device, pipelines, texture, format, levels) {
+    if (levels < 2)
+        return;
+    const pipeline = mipBlitPipeline(device, pipelines, format);
+    const sampler = device.createSampler({
+        label: 'mip.sampler',
+        magFilter: 'linear',
+        minFilter: 'linear',
+    });
+    const encoder = device.createCommandEncoder({ label: 'mip.chain' });
+    for (let level = 1; level < levels; level++) {
+        const source = texture.createView({ baseMipLevel: level - 1, mipLevelCount: 1 });
+        const target = texture.createView({ baseMipLevel: level, mipLevelCount: 1 });
+        const pass = encoder.beginRenderPass({
+            label: `mip.level${level}`,
+            colorAttachments: [
+                { view: target, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
+            ],
+        });
+        pass.setPipeline(pipeline);
+        pass.setBindGroup(0, device.createBindGroup({
+            layout: pipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: source },
+                { binding: 1, resource: sampler },
+            ],
+        }));
+        pass.draw(3);
+        pass.end();
+    }
+    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.
+ */
+function mipBlitPipeline(device, pipelines, format) {
+    return pipelines.get(`surface.mip:${format}`, () => ({
+        label: `surface.mip:${format}`,
+        layout: 'auto',
+        vertex: {
+            module: shaderModule(device, { label: 'surface.mip', code: MIP_WGSL }),
+            entryPoint: 'vertexMain',
+        },
+        fragment: {
+            module: shaderModule(device, { label: 'surface.mip', code: MIP_WGSL }),
+            entryPoint: 'fragmentMain',
+            targets: [{ format }],
+        },
+        primitive: { topology: 'triangle-list' },
+    }));
+}
 function sourceSize(source) {
     const candidate = source;
     const width = candidate.videoWidth ?? candidate.width ?? 0;
@@ -176,53 +245,6 @@ export class GpuSurfaceTexture {
      * 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' },
-        }));
+        generateMipChain(this.device, this.pipelines, texture, this.format, this.levels);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "3.62.0",
+  "version": "3.63.0",
   "description": "DriftEngine reusable browser 3D runtime",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "3.62.0",
-    "@driftengine/physics": "3.62.0",
+    "@driftengine/drft": "3.63.0",
+    "@driftengine/physics": "3.63.0",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",

package/src/index.ts

@@ -158,6 +158,21 @@ export type {
  * write to the frame stays refused while a write to a pass-owned target does not is written out.
  */
 export type { PassAttachmentOptions, PassTarget } from './render/passTarget.ts';
+/*
+ * The mip chain a pass has to build for itself on WebGPU, and the level count it needs to ask for.
+ *
+ * **Public because `gl.generateMipmap` has no WebGPU equivalent and every contributed pass that
+ * uploads a texture meets that the moment its texture is ever minified.** `ui2d` met it with a
+ * glyph atlas baked at 96 px and drawn at 11; writing the blit a second time there would have been
+ * a second WGSL shader to keep in step with this one, and the copy that quietly disagrees about
+ * the colour space is the one that would ship. `MipPipelines` is an interface rather than the
+ * renderer's cache so a pass can hand over a `Map` and nothing more.
+ */
+export {
+  generateMipChain,
+  mipLevelCount,
+  type MipPipelines,
+} from './render/backend/webgpu/surfaceTexturePass.ts';
 export { createPassAttachment } from './render/passTarget.ts';
 export type { FrameResource } from './render/frame/index.ts';
 /*

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

@@ -55,6 +55,100 @@ export function mipLevelCount(width: number, height: number): number {
   return Math.floor(Math.log2(Math.max(width, height))) + 1;
 }
 
+/**
+ * Somewhere to keep one pipeline per format. `PipelineCache` satisfies it; so does a `Map`.
+ *
+ * Taken as an interface rather than as the class, because the other caller of the chain below is
+ * `@driftengine/ui2d`, which builds its own pipeline from the device and has no cache of the
+ * renderer's to hand.
+ */
+export interface MipPipelines {
+  get(key: string, describe: () => GPURenderPipelineDescriptor): GPURenderPipeline;
+}
+
+/**
+ * Fill every level of a texture from the one above it, which is what WebGPU asks for instead of a
+ * call.
+ *
+ * **`gl.generateMipmap` is one line and WebGPU has no equivalent at all**, so this is the whole of
+ * the difference between the two backends for any texture that wants a chain. One encoder, one
+ * render pass per level, submitted together, once, at upload.
+ *
+ * The source view is a **single level**, so the sample cannot read the level being written — that
+ * would be one texture bound as an attachment and as a resource at once, which is rejected, and
+ * rejected quietly enough to matter.
+ *
+ * **A free function because there are two callers now.** A surface texture on a mesh has wanted a
+ * chain since it existed; a sprite sheet wanted one the day a consumer baked type into an atlas and
+ * drew it at a seventh of its authored size. Writing the blit twice would be two statements of one
+ * thing, and the second copy is the one that would quietly disagree about the format.
+ */
+export function generateMipChain(
+  device: GPUDevice,
+  pipelines: MipPipelines,
+  texture: GPUTexture,
+  format: GPUTextureFormat,
+  levels: number,
+): void {
+  if (levels < 2) return;
+  const pipeline = mipBlitPipeline(device, pipelines, format);
+  const sampler = device.createSampler({
+    label: 'mip.sampler',
+    magFilter: 'linear',
+    minFilter: 'linear',
+  });
+  const encoder = device.createCommandEncoder({ label: 'mip.chain' });
+  for (let level = 1; level < levels; level++) {
+    const source = texture.createView({ baseMipLevel: level - 1, mipLevelCount: 1 });
+    const target = texture.createView({ baseMipLevel: level, mipLevelCount: 1 });
+    const pass = encoder.beginRenderPass({
+      label: `mip.level${level}`,
+      colorAttachments: [
+        { view: target, loadOp: 'clear', storeOp: 'store', clearValue: [0, 0, 0, 0] },
+      ],
+    });
+    pass.setPipeline(pipeline);
+    pass.setBindGroup(
+      0,
+      device.createBindGroup({
+        layout: pipeline.getBindGroupLayout(0),
+        entries: [
+          { binding: 0, resource: source },
+          { binding: 1, resource: sampler },
+        ],
+      }),
+    );
+    pass.draw(3);
+    pass.end();
+  }
+  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.
+ */
+function mipBlitPipeline(
+  device: GPUDevice,
+  pipelines: MipPipelines,
+  format: GPUTextureFormat,
+): GPURenderPipeline {
+  return pipelines.get(`surface.mip:${format}`, () => ({
+    label: `surface.mip:${format}`,
+    layout: 'auto' as const,
+    vertex: {
+      module: shaderModule(device, { label: 'surface.mip', code: MIP_WGSL }),
+      entryPoint: 'vertexMain',
+    },
+    fragment: {
+      module: shaderModule(device, { label: 'surface.mip', code: MIP_WGSL }),
+      entryPoint: 'fragmentMain',
+      targets: [{ format }],
+    },
+    primitive: { topology: 'triangle-list' as const },
+  }));
+}
+
 function sourceSize(source: TexImageSource): { width: number; height: number } {
   const candidate = source as {
     width?: number;
@@ -201,57 +295,6 @@ export class GpuSurfaceTexture {
    * 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 },
-    }));
+    generateMipChain(this.device, this.pipelines, texture, this.format, this.levels);
   }
 }