@flighthq/render-wgpu 0.3.0-next.906.07cea63 → 0.3.1-next.209.43ef1bc

package/dist/wgpuTextureResolver.js

@@ -0,0 +1,67 @@
+import { getTextureSampleColorSpace, getTextureSource, getTextureSourceKind } from '@flighthq/texture/contract';
+import { BitmapTextureSourceKind, CompressedImageTextureSourceKind, ImageTextureSourceKind, RenderRegistry, RenderTargetTextureSourceKind, } from '@flighthq/types/contract';
+import { bindWgpuBitmapTexture, bindWgpuCompressedImageTexture, bindWgpuImageResourceTexture } from './wgpuDraw';
+import { getWgpuRenderStateRuntime } from './wgpuRenderState';
+import { bindWgpuRenderTexture } from './wgpuRenderTexture';
+export function registerStandardWgpuTextureResolvers(state) {
+    registerWgpuBitmapTextureResolver(state);
+    registerWgpuImageTextureResolver(state);
+    registerWgpuRenderTextureResolver(state);
+}
+export function registerWgpuBitmapTextureResolver(state) {
+    registerWgpuTextureResolver(state, BitmapTextureSourceKind, resolveWgpuBitmapTexture);
+}
+export function registerWgpuCompressedImageTextureResolver(state) {
+    registerWgpuTextureResolver(state, CompressedImageTextureSourceKind, resolveWgpuCompressedImageTexture);
+}
+export function registerWgpuImageTextureResolver(state) {
+    registerWgpuTextureResolver(state, ImageTextureSourceKind, resolveWgpuImageTexture);
+}
+export function registerWgpuRenderTextureResolver(state) {
+    registerWgpuTextureResolver(state, RenderTargetTextureSourceKind, resolveWgpuRenderTexture);
+}
+// Registers or replaces one declared source-kind resolver on this render state. Map.set is
+// last-write-wins; passing null removes the key.
+export function registerWgpuTextureResolver(state, sourceKind, resolver) {
+    const runtime = getWgpuRenderStateRuntime(state);
+    const registry = (runtime.wgpuTextureResolverRegistry ??= new Map());
+    if (resolver === null)
+        registry.delete(sourceKind);
+    else
+        registry.set(sourceKind, resolver);
+}
+// Resolves through one keyed lookup using the source's declared kind. Resolution may realize, upload,
+// and cache the GPU entry, but unlike the GL twin it does not bind command-pass state; the draw caller
+// binds the returned entry's group explicitly.
+export function resolveWgpuTexture(state, texture, premultiply = false, workingColorSpace = 'linear') {
+    const sourceKind = getTextureSourceKind(texture);
+    if (sourceKind === null)
+        return null;
+    const runtime = getWgpuRenderStateRuntime(state);
+    const resolver = runtime.wgpuTextureResolverRegistry?.get(sourceKind);
+    if (resolver === undefined) {
+        runtime.registryMiss?.(RenderRegistry.TextureResolver, sourceKind);
+        return null;
+    }
+    return resolver(state, texture, premultiply, getTextureSampleColorSpace(texture.colorSpace, workingColorSpace));
+}
+function resolveWgpuBitmapTexture(state, texture, premultiply, colorSpace) {
+    const bitmap = getTextureSource(texture);
+    return bitmap === null
+        ? null
+        : bindWgpuBitmapTexture(state, bitmap, texture.sampler.mipmaps, premultiply, colorSpace);
+}
+function resolveWgpuCompressedImageTexture(state, texture, _premultiply, colorSpace) {
+    const image = getTextureSource(texture);
+    return image === null ? null : bindWgpuCompressedImageTexture(state, image, colorSpace);
+}
+function resolveWgpuImageTexture(state, texture, premultiply, colorSpace) {
+    const image = getTextureSource(texture);
+    return image === null
+        ? null
+        : bindWgpuImageResourceTexture(state, image, texture.sampler.mipmaps, premultiply, colorSpace);
+}
+function resolveWgpuRenderTexture(state, texture) {
+    return bindWgpuRenderTexture(state, texture);
+}
+//# sourceMappingURL=wgpuTextureResolver.js.map

package/dist/wgpuTextureResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wgpuTextureResolver.js","sourceRoot":"","sources":["../src/wgpuTextureResolver.ts"],"names":[],"mappings":"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"}

package/dist/wgpuTextureUpload.d.ts

@@ -1,5 +1,5 @@
-import type { ImageResource } from '@flighthq/types/contract';
+import type { Image } from '@flighthq/types/contract';
 export declare function uploadWgpuTextureData(device: GPUDevice, texture: GPUTexture, origin: GPUOrigin3D, width: number, height: number, data: Readonly<Uint8ClampedArray<ArrayBuffer>>): void;
 export declare function uploadWgpuTextureElement(device: GPUDevice, texture: GPUTexture, origin: GPUOrigin3D, width: number, height: number, source: GPUCopyExternalImageSource): void;
-export declare function uploadWgpuTextureImageResource(device: GPUDevice, texture: GPUTexture, origin: GPUOrigin3D, image: Readonly<ImageResource>): void;
+export declare function uploadWgpuTextureImageResource(device: GPUDevice, texture: GPUTexture, origin: GPUOrigin3D, image: Readonly<Image>): void;
 //# sourceMappingURL=wgpuTextureUpload.d.ts.map

package/dist/wgpuTextureUpload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wgpuTextureUpload.d.ts","sourceRoot":"","sources":["../src/wgpuTextureUpload.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAS9D,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,QAAQ,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC,GAC7C,IAAI,CAON;AAID,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,0BAA0B,GACjC,IAAI,CAEN;AAID,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,QAAQ,CAAC,aAAa,CAAC,GAC7B,IAAI,CAaN"}
+{"version":3,"file":"wgpuTextureUpload.d.ts","sourceRoot":"","sources":["../src/wgpuTextureUpload.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAC;AAWtD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,QAAQ,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC,GAC7C,IAAI,CAON;AAID,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,0BAA0B,GACjC,IAAI,CAEN;AAGD,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,GACrB,IAAI,CASN"}

package/dist/wgpuTextureUpload.js

@@ -1,25 +1,20 @@
+import { tryCopyWgpuExternalImageToTexture } from './wgpuExternalImageSource';
 // Texel-upload primitives for one texture region. Each writes into `texture` at `origin` (the [x, y, z]
 // where z selects a cube-array layer / cube face). The wgpu mirror of render-gl's glTextureUpload; the
 // caller owns texture creation and format.
 // Uploads rgba8 CPU pixels through queue.writeTexture — the portable bedrock upload, reimplemented 1:1 by
 // a native backend. `bytesPerRow` is width*4: a tightly-packed rgba8unorm (4 bytes/texel) region, which is
-// exactly what a Surface's `data` holds.
+// exactly what a Bitmap's `data` holds.
 export function uploadWgpuTextureData(device, texture, origin, width, height, data) {
     device.queue.writeTexture({ texture, origin }, data, { bytesPerRow: width * 4, rowsPerImage: height }, [width, height, 1]);
 }
 // Uploads a decoded DOM element through queue.copyExternalImageToTexture — the web fast-path (GPU-side
 // copy, no CPU staging). Absent on non-web hosts.
 export function uploadWgpuTextureElement(device, texture, origin, width, height, source) {
-    device.queue.copyExternalImageToTexture({ source }, { texture, origin }, [width, height, 1]);
+    tryCopyWgpuExternalImageToTexture(device.queue, { source }, { texture, origin }, width, height);
 }
-// Dispatches an ImageResource to the element fast-path when a decoded `source` is present, else the
-// portable `data` path (a generated Surface). Assumes the resource has pixels in at least one form.
+// Uploads a host-backed Image through the decoded-element fast path.
 export function uploadWgpuTextureImageResource(device, texture, origin, image) {
-    if (image.source !== null) {
-        uploadWgpuTextureElement(device, texture, origin, image.width, image.height, image.source);
-    }
-    else {
-        uploadWgpuTextureData(device, texture, origin, image.width, image.height, image.data);
-    }
+    uploadWgpuTextureElement(device, texture, origin, image.width, image.height, image.source);
 }
 //# sourceMappingURL=wgpuTextureUpload.js.map

package/dist/wgpuTextureUpload.js.map

@@ -1 +1 @@
-{"version":3,"file":"wgpuTextureUpload.js","sourceRoot":"","sources":["../src/wgpuTextureUpload.ts"],"names":[],"mappings":"AAEA,wGAAwG;AACxG,uGAAuG;AACvG,2CAA2C;AAE3C,0GAA0G;AAC1G,2GAA2G;AAC3G,yCAAyC;AACzC,MAAM,UAAU,qBAAqB,CACnC,MAAiB,EACjB,OAAmB,EACnB,MAAmB,EACnB,KAAa,EACb,MAAc,EACd,IAA8C;IAE9C,MAAM,CAAC,KAAK,CAAC,YAAY,CACvB,EAAE,OAAO,EAAE,MAAM,EAAE,EACnB,IAAsC,EACtC,EAAE,WAAW,EAAE,KAAK,GAAG,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,EAChD,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CACnB,CAAC;AACJ,CAAC;AAED,uGAAuG;AACvG,kDAAkD;AAClD,MAAM,UAAU,wBAAwB,CACtC,MAAiB,EACjB,OAAmB,EACnB,MAAmB,EACnB,KAAa,EACb,MAAc,EACd,MAAkC;IAElC,MAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;AAC/F,CAAC;AAED,oGAAoG;AACpG,oGAAoG;AACpG,MAAM,UAAU,8BAA8B,CAC5C,MAAiB,EACjB,OAAmB,EACnB,MAAmB,EACnB,KAA8B;IAE9B,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC1B,wBAAwB,CACtB,MAAM,EACN,OAAO,EACP,MAAM,EACN,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,MAAoC,CAC3C,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,qBAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAK,CAAC,CAAC;IACzF,CAAC;AACH,CAAC"}
+{"version":3,"file":"wgpuTextureUpload.js","sourceRoot":"","sources":["../src/wgpuTextureUpload.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iCAAiC,EAAE,MAAM,2BAA2B,CAAC;AAE9E,wGAAwG;AACxG,uGAAuG;AACvG,2CAA2C;AAE3C,0GAA0G;AAC1G,2GAA2G;AAC3G,wCAAwC;AACxC,MAAM,UAAU,qBAAqB,CACnC,MAAiB,EACjB,OAAmB,EACnB,MAAmB,EACnB,KAAa,EACb,MAAc,EACd,IAA8C;IAE9C,MAAM,CAAC,KAAK,CAAC,YAAY,CACvB,EAAE,OAAO,EAAE,MAAM,EAAE,EACnB,IAAsC,EACtC,EAAE,WAAW,EAAE,KAAK,GAAG,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,EAChD,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CACnB,CAAC;AACJ,CAAC;AAED,uGAAuG;AACvG,kDAAkD;AAClD,MAAM,UAAU,wBAAwB,CACtC,MAAiB,EACjB,OAAmB,EACnB,MAAmB,EACnB,KAAa,EACb,MAAc,EACd,MAAkC;IAElC,iCAAiC,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAClG,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,8BAA8B,CAC5C,MAAiB,EACjB,OAAmB,EACnB,MAAmB,EACnB,KAAsB;IAEtB,wBAAwB,CACtB,MAAM,EACN,OAAO,EACP,MAAM,EACN,KAAK,CAAC,KAAK,EACX,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,MAAoC,CAC3C,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@flighthq/render-wgpu",
-  "version": "0.3.0-next.906.07cea63",
+  "version": "0.3.1-next.209.43ef1bc",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,12 +38,16 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/color": "0.3.0-next.906.07cea63",
-    "@flighthq/scene2d": "0.3.0-next.906.07cea63",
-    "@flighthq/geometry": "0.3.0-next.906.07cea63",
-    "@flighthq/render": "0.3.0-next.906.07cea63",
-    "@flighthq/surface": "0.3.0-next.906.07cea63",
-    "@flighthq/types": "0.3.0-next.906.07cea63"
+    "@flighthq/color": "0.3.1-next.209.43ef1bc",
+    "@flighthq/entity": "0.3.1-next.209.43ef1bc",
+    "@flighthq/scene2d": "0.3.1-next.209.43ef1bc",
+    "@flighthq/geometry": "0.3.1-next.209.43ef1bc",
+    "@flighthq/log": "0.3.1-next.209.43ef1bc",
+    "@flighthq/render": "0.3.1-next.209.43ef1bc",
+    "@flighthq/signals": "0.3.1-next.209.43ef1bc",
+    "@flighthq/bitmap": "0.3.1-next.209.43ef1bc",
+    "@flighthq/texture": "0.3.1-next.209.43ef1bc",
+    "@flighthq/types": "0.3.1-next.209.43ef1bc"
   },
   "devDependencies": {
     "@webgpu/types": "*",

package/src/enableWgpuTextureResolverGuards.test.ts

@@ -0,0 +1,65 @@
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
+import { createTexture } from '@flighthq/texture/contract';
+import type { Image } from '@flighthq/types/contract';
+
+import {
+  areWgpuTextureResolverGuardsEnabled,
+  enableWgpuTextureResolverGuards,
+} from './enableWgpuTextureResolverGuards';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+import { registerWgpuTextureResolver, resolveWgpuTexture } from './wgpuTextureResolver';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('areWgpuTextureResolverGuardsEnabled', () => {
+  it('reports whether diagnostics were installed for the state', async () => {
+    const state = await createWgpuRenderStateForTest();
+    expect(areWgpuTextureResolverGuardsEnabled(state)).toBe(false);
+
+    enableWgpuTextureResolverGuards(state);
+    expect(areWgpuTextureResolverGuardsEnabled(state)).toBe(true);
+  });
+});
+
+describe('enableWgpuTextureResolverGuards', () => {
+  it('is idempotent', async () => {
+    const state = await createWgpuRenderStateForTest();
+    enableWgpuTextureResolverGuards(state);
+    enableWgpuTextureResolverGuards(state);
+    expect(areWgpuTextureResolverGuardsEnabled(state)).toBe(true);
+  });
+
+  it('warns once for a missing resolver and stays silent for a registered resolver returning null', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const missing = textureWithKind('acme.missing.wgpu');
+    const registered = textureWithKind('acme.registered.wgpu');
+    const sink = createMemoryLogSink(4);
+    addLogSink(sink.sink);
+    enableWgpuTextureResolverGuards(state);
+    registerWgpuTextureResolver(state, 'acme.registered.wgpu', () => null);
+    try {
+      expect(resolveWgpuTexture(state, missing)).toBeNull();
+      expect(resolveWgpuTexture(state, missing)).toBeNull();
+      expect(resolveWgpuTexture(state, registered)).toBeNull();
+
+      const entries = getMemoryLogSinkEntries(sink);
+      expect(entries).toHaveLength(1);
+      expect(entries[0]?.data).toMatchObject({
+        kind: 'acme.missing.wgpu',
+        message:
+          'resolveWgpuTexture: texture source kind has no registered resolver — call registerWgpuTextureResolver(state, sourceKind, resolver)',
+      });
+    } finally {
+      removeLogSink(sink.sink);
+    }
+  });
+});
+
+function textureWithKind(kind: string) {
+  return createTexture({
+    dimension: '2d',
+    source: { kind } as Image,
+  });
+}

package/src/explainWgpuTextureResolution.test.ts

@@ -0,0 +1,36 @@
+import { createEntity } from '@flighthq/entity/contract';
+import { createTexture } from '@flighthq/texture/contract';
+import type { TextureSource } from '@flighthq/types/contract';
+
+import { explainWgpuTextureResolution } from './explainWgpuTextureResolution';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+import { registerWgpuTextureResolver } from './wgpuTextureResolver';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+describe('explainWgpuTextureResolution', () => {
+  it('distinguishes missing kinds, missing resolvers, and registered resolvers', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const texture = createTexture({
+      dimension: '2d',
+      source: createEntity({ height: 1, kind: 'acme.test', version: 0, width: 1 }) as TextureSource,
+    });
+
+    expect(explainWgpuTextureResolution(state, createTexture())).toEqual({
+      kind: null,
+      status: 'missing-kind',
+    });
+    expect(explainWgpuTextureResolution(state, texture)).toEqual({
+      kind: 'acme.test',
+      status: 'missing-resolver',
+    });
+
+    registerWgpuTextureResolver(state, 'acme.test', () => null);
+    expect(explainWgpuTextureResolution(state, texture)).toEqual({
+      kind: 'acme.test',
+      status: 'registered',
+    });
+  });
+});

package/src/wgpuCompressedTexture.test.ts

@@ -1,4 +1,5 @@
-import type { ImageResource, TextureContainer, WgpuCompressedTextureSupport } from '@flighthq/types/contract';
+import type { CompressedImage, TextureContainer, WgpuCompressedTextureSupport } from '@flighthq/types/contract';
+import { CompressedImageTextureSourceKind } from '@flighthq/types/contract';
 
 import {
   detectWgpuCompressedTextureSupport,
@@ -8,7 +9,7 @@ import {
   registerWgpuCompressedTextureUpload,
   uploadWgpuCompressedTextureContainer,
 } from './wgpuCompressedTexture';
-import { bindWgpuImageResourceTexture } from './wgpuDraw';
+import { bindWgpuCompressedImageTexture } from './wgpuDraw';
 import { getWgpuRenderStateRuntime } from './wgpuRenderState';
 import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
 
@@ -29,6 +30,16 @@ function container(overrides: Partial<TextureContainer> = {}): TextureContainer
   };
 }
 
+function compressedImage(): CompressedImage {
+  return {
+    compressed: { container: container(), payload: new Uint8Array(8) },
+    height: 4,
+    kind: CompressedImageTextureSourceKind,
+    version: 1,
+    width: 4,
+  } as unknown as CompressedImage;
+}
+
 describe('detectWgpuCompressedTextureSupport', () => {
   it('reads the three WebGPU compression features', async () => {
     const state = await createWgpuRenderStateForTest();
@@ -69,7 +80,7 @@ describe('registerWgpuCompressedTextureDecoder', () => {
 });
 
 describe('registerWgpuCompressedTextureUpload', () => {
-  it('installs and clears the ImageResource upload seam', async () => {
+  it('installs and clears the CompressedImage upload seam', async () => {
     const state = await createWgpuRenderStateForTest();
     registerWgpuCompressedTextureUpload(state);
     expect(getWgpuRenderStateRuntime(state).compressedTextureUpload).toBeTypeOf('function');
@@ -77,23 +88,14 @@ describe('registerWgpuCompressedTextureUpload', () => {
     expect(getWgpuRenderStateRuntime(state).compressedTextureUpload).toBeNull();
   });
 
-  it('lets the normal image binder consume a compressed-only resource', async () => {
+  it('lets the compressed-image binder consume its source', async () => {
     const state = await createWgpuRenderStateForTest();
     registerWgpuCompressedTextureUpload(state);
     registerWgpuCompressedTextureDecoder(state, (_format, width, height) => {
       return new Uint8ClampedArray(width * height * 4);
     });
-    const image = {
-      alphaType: 'straight',
-      compressed: { container: container(), payload: new Uint8Array(8) },
-      data: null,
-      height: 4,
-      source: null,
-      version: 1,
-      width: 4,
-    } as unknown as ImageResource;
     const writeTexture = vi.spyOn(state.device.queue, 'writeTexture');
-    expect(bindWgpuImageResourceTexture(state, image).view).toBeDefined();
+    expect(bindWgpuCompressedImageTexture(state, compressedImage())?.view).toBeDefined();
     expect(writeTexture).toHaveBeenCalledTimes(1);
   });
 
@@ -109,18 +111,9 @@ describe('registerWgpuCompressedTextureUpload', () => {
       }
       return rgba;
     });
-    const image = {
-      alphaType: 'straight',
-      compressed: { container: container(), payload: new Uint8Array(8) },
-      data: null,
-      height: 4,
-      source: null,
-      version: 1,
-      width: 4,
-    } as unknown as ImageResource;
     const writeTexture = vi.spyOn(state.device.queue, 'writeTexture');
 
-    const entry = bindWgpuImageResourceTexture(state, image);
+    const entry = bindWgpuCompressedImageTexture(state, compressedImage())!;
 
     expect(entry.straightAlpha).toBe(false);
     expect(Array.from(writeTexture.mock.calls[0][1] as Uint8ClampedArray).slice(0, 4)).toEqual([128, 32, 0, 128]);
@@ -130,17 +123,7 @@ describe('registerWgpuCompressedTextureUpload', () => {
     const state = await createWgpuRenderStateForTest();
     (state.device.features as Set<GPUFeatureName>).add('texture-compression-bc');
     registerWgpuCompressedTextureUpload(state);
-    const image = {
-      alphaType: 'straight',
-      compressed: { container: container(), payload: new Uint8Array(8) },
-      data: null,
-      height: 4,
-      source: null,
-      version: 1,
-      width: 4,
-    } as unknown as ImageResource;
-
-    expect(bindWgpuImageResourceTexture(state, image).straightAlpha).toBe(true);
+    expect(bindWgpuCompressedImageTexture(state, compressedImage())?.straightAlpha).toBe(true);
   });
 });