@driftengine/ui2d 4.13.0 → 4.13.1

package/README.md

@@ -2,7 +2,7 @@
 
 The 2D layer: quads with a texture on them, batched, in the order you drew them.
 
-**Cost: 10.1 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it
+**Cost: 10.6 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it
 drifts more than 3% — the number is derived from the same floors that gate asserts, so a README
 quoting a stale one is a red suite rather than a thing somebody notices.
 

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export type { SpriteBatch, SpritePlacement, SpriteRun, UvRect } from './spriteBa
 export { DEFAULT_SPRITE_CAPACITY, DEFAULT_SPRITE_SLOTS, createSpritePass } from './spritePass.ts';
 export type { SpritePass, SpritePassOptions } from './spritePass.ts';
 export { DEFAULT_SPRITE_TEXTURE_OPTIONS } from './spriteTexture.ts';
-export type { SpriteImage, SpriteTextureOptions } from './spriteTexture.ts';
+export type { SpriteImage, SpriteRegion, SpriteTextureOptions } from './spriteTexture.ts';
 export { createSpriteFrame, frameOf, gridSheet, namedSheet, sheetFrame, sheetFrameHeight, sheetFrameWidth, } from './spriteSheet.ts';
 export type { SheetEntry, SpriteFrame, SpriteSheet } from './spriteSheet.ts';
 export { TILE_EMPTY, createTilemap, drawTilemap, setTile, tileAt } from './tilemap.ts';

package/dist/spriteGl.d.ts

@@ -12,6 +12,21 @@ export interface Webgl2Sprites {
 export declare function createWebgl2Sprites(gl: WebGL2RenderingContext, capacity: number, slots: number, label: string): Webgl2Sprites;
 /** Replace a texture slot. The previous texture in that slot is deleted. */
 export declare function setWebgl2SpriteTexture(gl: WebGL2RenderingContext, sprites: Webgl2Sprites, slot: number, source: TexImageSource, options: SpriteTextureOptions): void;
+/**
+ * Copy one rectangle of `source` into the slot's texture at the same place: the WebGL2 half of
+ * `SpritePass.updateTexture`, which checks that the slot holds a texture of `source`'s size and has
+ * clipped the rectangle to it. See `updateGpuSpriteTexture` for why it exists.
+ *
+ * **The rectangle is chosen by the unpack state, and the state is put back to zero.** WebGL2 reads a
+ * sub-rectangle of a canvas or a bitmap through `UNPACK_SKIP_PIXELS`, `UNPACK_SKIP_ROWS` and
+ * `UNPACK_ROW_LENGTH`, set to the image's own width so a row is read as a row of the image. That is
+ * context state every other upload on this context reads too, core's included, so leaving it set
+ * would have the next texture anywhere in the engine start at this rectangle's corner. A chain,
+ * where the slot has one, is generated again, since its lower levels mixed the texels just replaced.
+ */
+export declare function updateWebgl2SpriteTexture(gl: WebGL2RenderingContext, sprites: Webgl2Sprites, slot: number, source: TexImageSource & {
+    readonly width: number;
+}, x: number, y: number, width: number, height: number, mipmap: boolean): void;
 /**
  * Fill a slot with one opaque white texel, from an array rather than an image.
  *

package/dist/spriteGl.js

@@ -132,6 +132,36 @@ export function setWebgl2SpriteTexture(gl, sprites, slot, source, options) {
     gl.activeTexture(gl.TEXTURE0);
     sprites.textures[slot] = texture;
 }
+/**
+ * Copy one rectangle of `source` into the slot's texture at the same place: the WebGL2 half of
+ * `SpritePass.updateTexture`, which checks that the slot holds a texture of `source`'s size and has
+ * clipped the rectangle to it. See `updateGpuSpriteTexture` for why it exists.
+ *
+ * **The rectangle is chosen by the unpack state, and the state is put back to zero.** WebGL2 reads a
+ * sub-rectangle of a canvas or a bitmap through `UNPACK_SKIP_PIXELS`, `UNPACK_SKIP_ROWS` and
+ * `UNPACK_ROW_LENGTH`, set to the image's own width so a row is read as a row of the image. That is
+ * context state every other upload on this context reads too, core's included, so leaving it set
+ * would have the next texture anywhere in the engine start at this rectangle's corner. A chain,
+ * where the slot has one, is generated again, since its lower levels mixed the texels just replaced.
+ */
+export function updateWebgl2SpriteTexture(gl, sprites, slot, source, x, y, width, height, mipmap) {
+    const texture = sprites.textures[slot];
+    if (texture === null || texture === undefined)
+        return;
+    gl.activeTexture(gl.TEXTURE0 + SPRITE_UNIT);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.pixelStorei(gl.UNPACK_ROW_LENGTH, source.width);
+    gl.pixelStorei(gl.UNPACK_SKIP_PIXELS, x);
+    gl.pixelStorei(gl.UNPACK_SKIP_ROWS, y);
+    gl.texSubImage2D(gl.TEXTURE_2D, 0, x, y, width, height, gl.RGBA, gl.UNSIGNED_BYTE, source);
+    gl.pixelStorei(gl.UNPACK_ROW_LENGTH, 0);
+    gl.pixelStorei(gl.UNPACK_SKIP_PIXELS, 0);
+    gl.pixelStorei(gl.UNPACK_SKIP_ROWS, 0);
+    if (mipmap)
+        gl.generateMipmap(gl.TEXTURE_2D);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    gl.activeTexture(gl.TEXTURE0);
+}
 /**
  * Fill a slot with one opaque white texel, from an array rather than an image.
  *

package/dist/spriteGpu.d.ts

@@ -5,6 +5,9 @@ import type { SpriteImage, SpriteTextureOptions } from './spriteTexture.ts';
 export interface GpuSpriteSlot {
     readonly texture: GPUTexture;
     readonly bindGroup: GPUBindGroup;
+    /** Kept so a partial update can rebuild the chain it overwrote part of. */
+    readonly format: GPUTextureFormat;
+    readonly levels: number;
 }
 /** Pipelines by colour format, then depth format, then sample count: a lookup that allocates nothing. */
 type PipelinesByTarget = Map<GPUTextureFormat, Map<GPUTextureFormat, Map<number, GPURenderPipeline>>>;
@@ -49,6 +52,21 @@ export declare function createGpuSprites(device: GPUDevice, format: GPUTextureFo
  */
 export declare function spritePipelineFor(device: GPUDevice, sprites: GpuSprites, format: GPUTextureFormat, depthFormat: GPUTextureFormat, samples: number): GPURenderPipeline;
 export declare function setGpuSpriteTexture(device: GPUDevice, sprites: GpuSprites, slot: number, source: SpriteImage, options: SpriteTextureOptions): void;
+/**
+ * Copy one rectangle of `source` into the slot's texture at the same place, keeping the texture and
+ * its bind group: the WebGPU half of `SpritePass.updateTexture`, which checks that the slot holds a
+ * texture of `source`'s size before it calls this, and has clipped the rectangle to it.
+ *
+ * **Why this exists.** `setGpuSpriteTexture` destroys the slot's texture, makes it again at full size
+ * and copies the whole image in, so an atlas painted one picture at a time sent every texel of the
+ * atlas for each picture: measured by a consumer at about 100 ms for a 5120-texel side. This sends
+ * the rectangle. A chain, where the slot has one, is rendered again from level zero, because a lower
+ * level mixes the texels just replaced with their neighbours; that is GPU work rather than an upload.
+ *
+ * **Ordered like `setTexture`, on the queue**: a copy issued after a draw that reads the slot was
+ * recorded, and before that frame is submitted, is what the draw sees. Paint before `drawPass`.
+ */
+export declare function updateGpuSpriteTexture(device: GPUDevice, sprites: GpuSprites, slot: number, source: SpriteImage, x: number, y: number, width: number, height: number): void;
 /** The same one white texel, written straight into a texture. See the WebGL2 half for why. */
 export declare function setGpuWhiteTexture(device: GPUDevice, sprites: GpuSprites, slot: number): void;
 export declare function uploadGpuInstances(device: GPUDevice, sprites: GpuSprites, batch: SpriteBatch): void;

package/dist/spriteGpu.js

@@ -243,8 +243,47 @@ export function setGpuSpriteTexture(device, sprites, slot, source, options) {
             { binding: FRAG.textures.uSpriteTexture.sampler, resource: sampler },
         ],
     });
-    sprites.slots[slot] = { texture, bindGroup };
+    sprites.slots[slot] = { texture, bindGroup, format, levels };
 }
+/**
+ * Copy one rectangle of `source` into the slot's texture at the same place, keeping the texture and
+ * its bind group: the WebGPU half of `SpritePass.updateTexture`, which checks that the slot holds a
+ * texture of `source`'s size before it calls this, and has clipped the rectangle to it.
+ *
+ * **Why this exists.** `setGpuSpriteTexture` destroys the slot's texture, makes it again at full size
+ * and copies the whole image in, so an atlas painted one picture at a time sent every texel of the
+ * atlas for each picture: measured by a consumer at about 100 ms for a 5120-texel side. This sends
+ * the rectangle. A chain, where the slot has one, is rendered again from level zero, because a lower
+ * level mixes the texels just replaced with their neighbours; that is GPU work rather than an upload.
+ *
+ * **Ordered like `setTexture`, on the queue**: a copy issued after a draw that reads the slot was
+ * recorded, and before that frame is submitted, is what the draw sees. Paint before `drawPass`.
+ */
+export function updateGpuSpriteTexture(device, sprites, slot, source, x, y, width, height) {
+    const held = sprites.slots[slot];
+    if (held === null || held === undefined)
+        return;
+    /* Refilled rather than built: a timer's digits are an update every frame. */
+    COPY_SOURCE.source = source;
+    COPY_ORIGIN.x = x;
+    COPY_ORIGIN.y = y;
+    COPY_TARGET.texture = held.texture;
+    COPY_SIZE.width = width;
+    COPY_SIZE.height = height;
+    device.queue.copyExternalImageToTexture(COPY_SOURCE, COPY_TARGET, COPY_SIZE);
+    /* Let go of the caller's canvas until the next copy, rather than holding it alive here. */
+    COPY_SOURCE.source = EMPTY_SOURCE;
+    generateMipChain(device, sprites.mipPipelines, held.texture, held.format, held.levels);
+}
+/* The one origin both ends of the copy share: a rectangle lands where it was in the image. */
+const COPY_ORIGIN = { x: 0, y: 0 };
+const EMPTY_SOURCE = null;
+const COPY_SOURCE = { source: EMPTY_SOURCE, origin: COPY_ORIGIN, flipY: false };
+const COPY_TARGET = {
+    texture: null,
+    origin: COPY_ORIGIN,
+};
+const COPY_SIZE = { width: 0, height: 0 };
 /** The same one white texel, written straight into a texture. See the WebGL2 half for why. */
 export function setGpuWhiteTexture(device, sprites, slot) {
     const texture = device.createTexture({
@@ -265,7 +304,7 @@ export function setGpuWhiteTexture(device, sprites, slot) {
             { binding: FRAG.textures.uSpriteTexture.sampler, resource: sprites.samplers.nearest },
         ],
     });
-    sprites.slots[slot] = { texture, bindGroup };
+    sprites.slots[slot] = { texture, bindGroup, format: 'rgba8unorm', levels: 1 };
 }
 export function uploadGpuInstances(device, sprites, batch) {
     if (batch.count === 0)

package/dist/spritePass.d.ts

@@ -2,7 +2,7 @@
 import type { PassDefinition } from '@driftengine/core';
 import type { Affine2D } from './camera2d.ts';
 import type { SpriteBatch } from './spriteBatch.ts';
-import type { SpriteImage, SpriteTextureOptions } from './spriteTexture.ts';
+import type { SpriteImage, SpriteRegion, SpriteTextureOptions } from './spriteTexture.ts';
 /** Sprites a frame, if the caller does not say. Four thousand quads is 224 KB of instance data. */
 export declare const DEFAULT_SPRITE_CAPACITY = 4096;
 /**
@@ -50,5 +50,27 @@ export interface SpritePass extends PassDefinition {
     setTransform(affine: Affine2D): void;
     /** Fill a texture slot. Safe before the pass is registered; applied when it gets a device. */
     setTexture(slot: number, source: SpriteImage, options?: SpriteTextureOptions): void;
+    /**
+     * Copy `region` of `source` into the slot's texture at the same place, keeping the rest: what an
+     * atlas painted one picture at a time sends, instead of all of itself.
+     *
+     * The slot must hold a texture made from an image of `source`'s size, through `setTexture`; it
+     * keeps the options it was made with. Otherwise, or before the pass has a device, this does what
+     * `setTexture` does with the slot's options (the default ones for an empty slot), so a caller
+     * never has to ask which. The region is clipped to the image, and an empty one copies nothing. A
+     * slot with a mip chain has the chain rebuilt.
+     *
+     * **The saving, measured by a consumer painting a 2D layer into atlases**: `setTexture` sends the
+     * whole image and, on WebGPU, makes the texture again, about 100 ms for a 5120-texel side, while
+     * the pictures new on that frame covered about 6 of its 26 million texels and a typical later
+     * frame changes a timer's digits. Call it before `drawPass` in a frame, as `setTexture` is.
+     *
+     * **Paint such an atlas into a 2D context made with `willReadFrequently: true`.** On WebGPU a
+     * canvas drawn on the GPU is transferred whole before any part of it is copied, measured at 66 ms
+     * for one 256 by 64 rectangle of a 5120-texel atlas against 0.4 ms from a canvas kept in memory;
+     * WebGL2 copies a rectangle quickly from either. What the option gives up is painting on the GPU,
+     * which matters for a canvas redrawn whole every frame and not for an atlas painted in pieces.
+     */
+    updateTexture(slot: number, source: SpriteImage, region: SpriteRegion): void;
 }
 export declare function createSpritePass(options?: SpritePassOptions): SpritePass;

package/dist/spritePass.js

@@ -3,8 +3,8 @@ import { interfaceGrade } from '@driftengine/core';
 import { SPRITE_BINDINGS } from './shaders/generated/sprite.wgsl.js';
 import { createAffine2D } from './camera2d.js';
 import { createSpriteBatch, resetSpriteBatch } from './spriteBatch.js';
-import { createWebgl2Sprites, disposeWebgl2Sprites, drawWebgl2Sprites, setWebgl2SpriteTexture, setWebgl2WhiteTexture, uploadWebgl2Instances, } from './spriteGl.js';
-import { createGpuSprites, disposeGpuSprites, drawGpuSprites, spritePipelineFor, setGpuSpriteTexture, setGpuWhiteTexture, uploadGpuInstances, } from './spriteGpu.js';
+import { createWebgl2Sprites, disposeWebgl2Sprites, drawWebgl2Sprites, setWebgl2SpriteTexture, updateWebgl2SpriteTexture, setWebgl2WhiteTexture, uploadWebgl2Instances, } from './spriteGl.js';
+import { createGpuSprites, disposeGpuSprites, drawGpuSprites, spritePipelineFor, setGpuSpriteTexture, updateGpuSpriteTexture, setGpuWhiteTexture, uploadGpuInstances, } from './spriteGpu.js';
 import { DEFAULT_SPRITE_TEXTURE_OPTIONS } from './spriteTexture.js';
 const VERT = SPRITE_BINDINGS.SPRITE_VERT;
 const FRAG = SPRITE_BINDINGS.SPRITE_FRAG;
@@ -37,6 +37,21 @@ export function createSpritePass(options = {}) {
     let device = null;
     let clipCorrection = IDENTITY_CLIP;
     const pending = [];
+    /* What each slot was made from, so an update knows whether a partial copy fits it. */
+    const held = Array.from({ length: slots }, () => null);
+    function setTexture(slot, source, textureOptions) {
+        if (slot < 0 || slot >= slots) {
+            throw new RangeError(`${label}: slot ${slot} is outside the ${slots} this pass has`);
+        }
+        const options = textureOptions ?? DEFAULT_SPRITE_TEXTURE_OPTIONS;
+        held[slot] = { width: source.width, height: source.height, options };
+        const entry = { slot, source, options };
+        if (gl === null && gpu === null) {
+            pending.push(entry);
+            return;
+        }
+        applyTexture(entry);
+    }
     const applyTexture = (entry) => {
         if (gl !== null && context !== null) {
             setWebgl2SpriteTexture(context, gl, entry.slot, entry.source, entry.options);
@@ -56,20 +71,32 @@ export function createSpritePass(options = {}) {
         setTransform(affine) {
             toNdc.set(affine);
         },
-        setTexture(slot, source, textureOptions) {
-            if (slot < 0 || slot >= slots) {
-                throw new RangeError(`${label}: slot ${slot} is outside the ${slots} this pass has`);
+        setTexture,
+        updateTexture(slot, source, region) {
+            const was = slot >= 0 && slot < slots ? held[slot] : null;
+            if (was === null ||
+                was === undefined ||
+                was.width !== source.width ||
+                was.height !== source.height ||
+                (gl === null && gpu === null)) {
+                setTexture(slot, source, was?.options);
+                return;
             }
-            const entry = {
-                slot,
-                source,
-                options: textureOptions ?? DEFAULT_SPRITE_TEXTURE_OPTIONS,
-            };
-            if (gl === null && gpu === null) {
-                pending.push(entry);
+            /* Whole texels inside the image: a rectangle reaching past an edge copies what is inside it. */
+            const x0 = Math.max(0, Math.floor(region.x));
+            const y0 = Math.max(0, Math.floor(region.y));
+            const x1 = Math.min(source.width, Math.ceil(region.x + region.width));
+            const y1 = Math.min(source.height, Math.ceil(region.y + region.height));
+            if (x1 <= x0 || y1 <= y0)
+                return;
+            if (gl !== null && context !== null) {
+                const mipmap = was.options.mipmap === true;
+                updateWebgl2SpriteTexture(context, gl, slot, source, x0, y0, x1 - x0, y1 - y0, mipmap);
                 return;
             }
-            applyTexture(entry);
+            if (gpu !== null && device !== null) {
+                updateGpuSpriteTexture(device, gpu, slot, source, x0, y0, x1 - x0, y1 - y0);
+            }
         },
         init(passDevice) {
             /*

package/dist/spriteTexture.d.ts

@@ -12,6 +12,16 @@
  * ask the caller how big the image it just handed over is.
  */
 export type SpriteImage = ImageBitmap | HTMLCanvasElement | OffscreenCanvas;
+/**
+ * A rectangle of a sprite image, in its texels from the top left: what `updateTexture` copies, from
+ * the image into the slot's texture at the same place.
+ */
+export interface SpriteRegion {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
 export interface SpriteTextureOptions {
     /**
      * `srgb` is right for anything painted to be looked at, which is every sprite sheet — the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/ui2d",
-  "version": "4.13.0",
+  "version": "4.13.1",
   "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": "4.13.0"
+    "@driftengine/core": "4.13.1"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/index.ts

@@ -25,7 +25,7 @@ export { DEFAULT_SPRITE_CAPACITY, DEFAULT_SPRITE_SLOTS, createSpritePass } from
 export type { SpritePass, SpritePassOptions } from './spritePass.ts';
 
 export { DEFAULT_SPRITE_TEXTURE_OPTIONS } from './spriteTexture.ts';
-export type { SpriteImage, SpriteTextureOptions } from './spriteTexture.ts';
+export type { SpriteImage, SpriteRegion, SpriteTextureOptions } from './spriteTexture.ts';
 
 export {
   createSpriteFrame,

package/src/spriteGl.ts

@@ -169,6 +169,45 @@ export function setWebgl2SpriteTexture(
   sprites.textures[slot] = texture;
 }
 
+/**
+ * Copy one rectangle of `source` into the slot's texture at the same place: the WebGL2 half of
+ * `SpritePass.updateTexture`, which checks that the slot holds a texture of `source`'s size and has
+ * clipped the rectangle to it. See `updateGpuSpriteTexture` for why it exists.
+ *
+ * **The rectangle is chosen by the unpack state, and the state is put back to zero.** WebGL2 reads a
+ * sub-rectangle of a canvas or a bitmap through `UNPACK_SKIP_PIXELS`, `UNPACK_SKIP_ROWS` and
+ * `UNPACK_ROW_LENGTH`, set to the image's own width so a row is read as a row of the image. That is
+ * context state every other upload on this context reads too, core's included, so leaving it set
+ * would have the next texture anywhere in the engine start at this rectangle's corner. A chain,
+ * where the slot has one, is generated again, since its lower levels mixed the texels just replaced.
+ */
+export function updateWebgl2SpriteTexture(
+  gl: WebGL2RenderingContext,
+  sprites: Webgl2Sprites,
+  slot: number,
+  source: TexImageSource & { readonly width: number },
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  mipmap: boolean,
+): void {
+  const texture = sprites.textures[slot];
+  if (texture === null || texture === undefined) return;
+  gl.activeTexture(gl.TEXTURE0 + SPRITE_UNIT);
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  gl.pixelStorei(gl.UNPACK_ROW_LENGTH, source.width);
+  gl.pixelStorei(gl.UNPACK_SKIP_PIXELS, x);
+  gl.pixelStorei(gl.UNPACK_SKIP_ROWS, y);
+  gl.texSubImage2D(gl.TEXTURE_2D, 0, x, y, width, height, gl.RGBA, gl.UNSIGNED_BYTE, source);
+  gl.pixelStorei(gl.UNPACK_ROW_LENGTH, 0);
+  gl.pixelStorei(gl.UNPACK_SKIP_PIXELS, 0);
+  gl.pixelStorei(gl.UNPACK_SKIP_ROWS, 0);
+  if (mipmap) gl.generateMipmap(gl.TEXTURE_2D);
+  gl.bindTexture(gl.TEXTURE_2D, null);
+  gl.activeTexture(gl.TEXTURE0);
+}
+
 /**
  * Fill a slot with one opaque white texel, from an array rather than an image.
  *

package/src/spriteGpu.ts

@@ -37,6 +37,9 @@ const TEXTURE_USAGE = 4 | 2 | 16; // TEXTURE_BINDING | COPY_DST | RENDER_ATTACHM
 export interface GpuSpriteSlot {
   readonly texture: GPUTexture;
   readonly bindGroup: GPUBindGroup;
+  /** Kept so a partial update can rebuild the chain it overwrote part of. */
+  readonly format: GPUTextureFormat;
+  readonly levels: number;
 }
 
 /** Pipelines by colour format, then depth format, then sample count: a lookup that allocates nothing. */
@@ -331,9 +334,62 @@ export function setGpuSpriteTexture(
       { binding: FRAG.textures.uSpriteTexture.sampler, resource: sampler },
     ],
   });
-  sprites.slots[slot] = { texture, bindGroup };
+  sprites.slots[slot] = { texture, bindGroup, format, levels };
 }
 
+/**
+ * Copy one rectangle of `source` into the slot's texture at the same place, keeping the texture and
+ * its bind group: the WebGPU half of `SpritePass.updateTexture`, which checks that the slot holds a
+ * texture of `source`'s size before it calls this, and has clipped the rectangle to it.
+ *
+ * **Why this exists.** `setGpuSpriteTexture` destroys the slot's texture, makes it again at full size
+ * and copies the whole image in, so an atlas painted one picture at a time sent every texel of the
+ * atlas for each picture: measured by a consumer at about 100 ms for a 5120-texel side. This sends
+ * the rectangle. A chain, where the slot has one, is rendered again from level zero, because a lower
+ * level mixes the texels just replaced with their neighbours; that is GPU work rather than an upload.
+ *
+ * **Ordered like `setTexture`, on the queue**: a copy issued after a draw that reads the slot was
+ * recorded, and before that frame is submitted, is what the draw sees. Paint before `drawPass`.
+ */
+export function updateGpuSpriteTexture(
+  device: GPUDevice,
+  sprites: GpuSprites,
+  slot: number,
+  source: SpriteImage,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+): void {
+  const held = sprites.slots[slot];
+  if (held === null || held === undefined) return;
+  /* Refilled rather than built: a timer's digits are an update every frame. */
+  COPY_SOURCE.source = source as GPUCopyExternalImageSource;
+  COPY_ORIGIN.x = x;
+  COPY_ORIGIN.y = y;
+  COPY_TARGET.texture = held.texture;
+  COPY_SIZE.width = width;
+  COPY_SIZE.height = height;
+  device.queue.copyExternalImageToTexture(COPY_SOURCE, COPY_TARGET, COPY_SIZE);
+  /* Let go of the caller's canvas until the next copy, rather than holding it alive here. */
+  COPY_SOURCE.source = EMPTY_SOURCE;
+  generateMipChain(device, sprites.mipPipelines, held.texture, held.format, held.levels);
+}
+
+/* The one origin both ends of the copy share: a rectangle lands where it was in the image. */
+const COPY_ORIGIN = { x: 0, y: 0 };
+const EMPTY_SOURCE = null as unknown as GPUCopyExternalImageSource;
+const COPY_SOURCE: {
+  source: GPUCopyExternalImageSource;
+  origin: typeof COPY_ORIGIN;
+  flipY: boolean;
+} = { source: EMPTY_SOURCE, origin: COPY_ORIGIN, flipY: false };
+const COPY_TARGET: { texture: GPUTexture; origin: typeof COPY_ORIGIN } = {
+  texture: null as unknown as GPUTexture,
+  origin: COPY_ORIGIN,
+};
+const COPY_SIZE = { width: 0, height: 0 };
+
 /** The same one white texel, written straight into a texture. See the WebGL2 half for why. */
 export function setGpuWhiteTexture(device: GPUDevice, sprites: GpuSprites, slot: number): void {
   const texture = device.createTexture({
@@ -359,7 +415,7 @@ export function setGpuWhiteTexture(device: GPUDevice, sprites: GpuSprites, slot:
       { binding: FRAG.textures.uSpriteTexture.sampler, resource: sprites.samplers.nearest },
     ],
   });
-  sprites.slots[slot] = { texture, bindGroup };
+  sprites.slots[slot] = { texture, bindGroup, format: 'rgba8unorm', levels: 1 };
 }
 
 export function uploadGpuInstances(

package/src/spritePass.ts

@@ -13,6 +13,7 @@ import {
   disposeWebgl2Sprites,
   drawWebgl2Sprites,
   setWebgl2SpriteTexture,
+  updateWebgl2SpriteTexture,
   setWebgl2WhiteTexture,
   uploadWebgl2Instances,
 } from './spriteGl.ts';
@@ -23,12 +24,13 @@ import {
   drawGpuSprites,
   spritePipelineFor,
   setGpuSpriteTexture,
+  updateGpuSpriteTexture,
   setGpuWhiteTexture,
   uploadGpuInstances,
 } from './spriteGpu.ts';
 import type { GpuSprites } from './spriteGpu.ts';
 import { DEFAULT_SPRITE_TEXTURE_OPTIONS } from './spriteTexture.ts';
-import type { SpriteImage, SpriteTextureOptions } from './spriteTexture.ts';
+import type { SpriteImage, SpriteRegion, SpriteTextureOptions } from './spriteTexture.ts';
 
 const VERT = SPRITE_BINDINGS.SPRITE_VERT;
 const FRAG = SPRITE_BINDINGS.SPRITE_FRAG;
@@ -86,6 +88,34 @@ export interface SpritePass extends PassDefinition {
   setTransform(affine: Affine2D): void;
   /** Fill a texture slot. Safe before the pass is registered; applied when it gets a device. */
   setTexture(slot: number, source: SpriteImage, options?: SpriteTextureOptions): void;
+  /**
+   * Copy `region` of `source` into the slot's texture at the same place, keeping the rest: what an
+   * atlas painted one picture at a time sends, instead of all of itself.
+   *
+   * The slot must hold a texture made from an image of `source`'s size, through `setTexture`; it
+   * keeps the options it was made with. Otherwise, or before the pass has a device, this does what
+   * `setTexture` does with the slot's options (the default ones for an empty slot), so a caller
+   * never has to ask which. The region is clipped to the image, and an empty one copies nothing. A
+   * slot with a mip chain has the chain rebuilt.
+   *
+   * **The saving, measured by a consumer painting a 2D layer into atlases**: `setTexture` sends the
+   * whole image and, on WebGPU, makes the texture again, about 100 ms for a 5120-texel side, while
+   * the pictures new on that frame covered about 6 of its 26 million texels and a typical later
+   * frame changes a timer's digits. Call it before `drawPass` in a frame, as `setTexture` is.
+   *
+   * **Paint such an atlas into a 2D context made with `willReadFrequently: true`.** On WebGPU a
+   * canvas drawn on the GPU is transferred whole before any part of it is copied, measured at 66 ms
+   * for one 256 by 64 rectangle of a 5120-texel atlas against 0.4 ms from a canvas kept in memory;
+   * WebGL2 copies a rectangle quickly from either. What the option gives up is painting on the GPU,
+   * which matters for a canvas redrawn whole every frame and not for an atlas painted in pieces.
+   */
+  updateTexture(slot: number, source: SpriteImage, region: SpriteRegion): void;
+}
+
+interface HeldTexture {
+  width: number;
+  height: number;
+  options: SpriteTextureOptions;
 }
 
 interface PendingTexture {
@@ -112,6 +142,26 @@ export function createSpritePass(options: SpritePassOptions = {}): SpritePass {
   let device: GPUDevice | null = null;
   let clipCorrection: Float32Array = IDENTITY_CLIP;
   const pending: PendingTexture[] = [];
+  /* What each slot was made from, so an update knows whether a partial copy fits it. */
+  const held: (HeldTexture | null)[] = Array.from({ length: slots }, () => null);
+
+  function setTexture(
+    slot: number,
+    source: SpriteImage,
+    textureOptions?: SpriteTextureOptions,
+  ): void {
+    if (slot < 0 || slot >= slots) {
+      throw new RangeError(`${label}: slot ${slot} is outside the ${slots} this pass has`);
+    }
+    const options = textureOptions ?? DEFAULT_SPRITE_TEXTURE_OPTIONS;
+    held[slot] = { width: source.width, height: source.height, options };
+    const entry: PendingTexture = { slot, source, options };
+    if (gl === null && gpu === null) {
+      pending.push(entry);
+      return;
+    }
+    applyTexture(entry);
+  }
 
   const applyTexture = (entry: PendingTexture): void => {
     if (gl !== null && context !== null) {
@@ -136,20 +186,34 @@ export function createSpritePass(options: SpritePassOptions = {}): SpritePass {
       toNdc.set(affine);
     },
 
-    setTexture(slot: number, source: SpriteImage, textureOptions?: SpriteTextureOptions): void {
-      if (slot < 0 || slot >= slots) {
-        throw new RangeError(`${label}: slot ${slot} is outside the ${slots} this pass has`);
+    setTexture,
+
+    updateTexture(slot: number, source: SpriteImage, region: SpriteRegion): void {
+      const was = slot >= 0 && slot < slots ? held[slot] : null;
+      if (
+        was === null ||
+        was === undefined ||
+        was.width !== source.width ||
+        was.height !== source.height ||
+        (gl === null && gpu === null)
+      ) {
+        setTexture(slot, source, was?.options);
+        return;
       }
-      const entry: PendingTexture = {
-        slot,
-        source,
-        options: textureOptions ?? DEFAULT_SPRITE_TEXTURE_OPTIONS,
-      };
-      if (gl === null && gpu === null) {
-        pending.push(entry);
+      /* Whole texels inside the image: a rectangle reaching past an edge copies what is inside it. */
+      const x0 = Math.max(0, Math.floor(region.x));
+      const y0 = Math.max(0, Math.floor(region.y));
+      const x1 = Math.min(source.width, Math.ceil(region.x + region.width));
+      const y1 = Math.min(source.height, Math.ceil(region.y + region.height));
+      if (x1 <= x0 || y1 <= y0) return;
+      if (gl !== null && context !== null) {
+        const mipmap = was.options.mipmap === true;
+        updateWebgl2SpriteTexture(context, gl, slot, source, x0, y0, x1 - x0, y1 - y0, mipmap);
         return;
       }
-      applyTexture(entry);
+      if (gpu !== null && device !== null) {
+        updateGpuSpriteTexture(device, gpu, slot, source, x0, y0, x1 - x0, y1 - y0);
+      }
     },
 
     init(passDevice: PassDevice): void {

package/src/spriteTexture.ts

@@ -14,6 +14,17 @@
  */
 export type SpriteImage = ImageBitmap | HTMLCanvasElement | OffscreenCanvas;
 
+/**
+ * A rectangle of a sprite image, in its texels from the top left: what `updateTexture` copies, from
+ * the image into the slot's texture at the same place.
+ */
+export interface SpriteRegion {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
 export interface SpriteTextureOptions {
   /**
    * `srgb` is right for anything painted to be looked at, which is every sprite sheet — the