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

package/src/wgpuSurface.test.ts

@@ -1,9 +1,10 @@
+import type { WgpuRenderState } from '@flighthq/types/contract';
 import { beforeAll, describe, expect, it } from 'vitest';
 
 import { getWgpuRenderStateRuntime } from './wgpuRenderState';
 import {
   acquireWgpuFrameCaptureTexture,
-  createSurfaceFromWgpuRenderState,
+  createBitmapFromWgpuRenderState,
   enableWgpuFrameCapture,
   encodeWgpuFrameCapture,
 } from './wgpuSurface';
@@ -22,13 +23,62 @@ describe('acquireWgpuFrameCaptureTexture', () => {
   });
 });
 
-describe('createSurfaceFromWgpuRenderState', () => {
+describe('createBitmapFromWgpuRenderState', () => {
   it('throws when frame capture was never enabled (no buffer to read)', async () => {
     const state = await createWgpuRenderStateForTest();
-    await expect(createSurfaceFromWgpuRenderState(state)).rejects.toThrow(/enableWgpuFrameCapture/);
+    await expect(createBitmapFromWgpuRenderState(state)).rejects.toThrow(/enableWgpuFrameCapture/);
+  });
+
+  it('reads the mapped buffer within the bound', async () => {
+    const state = await createWgpuRenderStateForTest();
+    installCaptureBuffer(state, () => Promise.resolve());
+
+    const bitmap = await createBitmapFromWgpuRenderState(state, 1_000);
+
+    expect(bitmap.width).toBe(1);
+    expect(bitmap.height).toBe(1);
+  });
+
+  it('fails by name when the buffer never maps, instead of awaiting forever', async () => {
+    // The driver failure this bounds: mapAsync neither resolves nor rejects. Before the bound, the
+    // caller sat here until something outside it gave up and reported a stall with no location.
+    const state = await createWgpuRenderStateForTest();
+    installCaptureBuffer(state, () => new Promise<void>(() => {}));
+
+    await expect(createBitmapFromWgpuRenderState(state, 25)).rejects.toThrow(/did not map within 25ms/);
+  });
+
+  it('leaves the wait unbounded when the caller passes 0', async () => {
+    const state = await createWgpuRenderStateForTest();
+    let settle = (): void => {};
+    installCaptureBuffer(state, () => new Promise<void>((resolve) => (settle = resolve)));
+
+    let done = false;
+    const pending = createBitmapFromWgpuRenderState(state, 0).then(() => (done = true));
+    await new Promise((resolve) => setTimeout(resolve, 40));
+    expect(done).toBe(false);
+
+    settle();
+    await pending;
+    expect(done).toBe(true);
   });
 });
 
+// Installs a 1×1 retained capture buffer whose map step the caller controls, so the map bound can be
+// exercised without a GPU. The mock device's buffers carry no map surface of their own.
+function installCaptureBuffer(state: WgpuRenderState, mapAsync: () => Promise<void>): void {
+  const runtime = getWgpuRenderStateRuntime(state);
+  runtime.frameCaptureBuffer = {
+    mapAsync,
+    getMappedRange: () => new ArrayBuffer(256),
+    unmap: () => {},
+    destroy: () => {},
+  } as unknown as GPUBuffer;
+  runtime.frameCaptureWidth = 1;
+  runtime.frameCaptureHeight = 1;
+  runtime.frameCaptureBytesPerRow = 256;
+}
+
 describe('enableWgpuFrameCapture', () => {
   it('sets the capture flag on the render state runtime', async () => {
     const state = await createWgpuRenderStateForTest();
@@ -46,4 +96,46 @@ describe('encodeWgpuFrameCapture', () => {
     encodeWgpuFrameCapture(state, encoder);
     expect(copied).toBe(false);
   });
+
+  it('skips the copy while a readback holds the buffer, and resumes once it lets go', async () => {
+    // The writer/reader handshake over the single retained buffer: an animating scene must not keep
+    // enqueueing copies into a buffer a readback has mapped or is waiting to map.
+    const state = await createWgpuRenderStateForTest();
+    enableWgpuFrameCapture(state);
+    acquireWgpuFrameCaptureTexture(state);
+    const runtime = getWgpuRenderStateRuntime(state);
+    let mapState: GPUBufferMapState = 'unmapped';
+    installCaptureBuffer(state, () => Promise.resolve());
+    Object.defineProperty(runtime.frameCaptureBuffer, 'mapState', { get: () => mapState });
+
+    let copies = 0;
+    const encoder = { copyTextureToBuffer: () => copies++ } as unknown as GPUCommandEncoder;
+
+    mapState = 'pending';
+    encodeWgpuFrameCapture(state, encoder);
+    mapState = 'mapped';
+    encodeWgpuFrameCapture(state, encoder);
+    expect(copies).toBe(0);
+
+    mapState = 'unmapped';
+    encodeWgpuFrameCapture(state, encoder);
+    expect(copies).toBe(1);
+  });
+
+  it('still copies when the implementation reports no map state at all', async () => {
+    // Fails safe in the direction that keeps capturing: an undefined mapState must not read as "busy"
+    // and silence every copy for the rest of the run.
+    const state = await createWgpuRenderStateForTest();
+    enableWgpuFrameCapture(state);
+    acquireWgpuFrameCaptureTexture(state);
+    installCaptureBuffer(state, () => Promise.resolve());
+    Object.defineProperty(getWgpuRenderStateRuntime(state).frameCaptureBuffer, 'mapState', {
+      get: () => undefined,
+    });
+
+    let copies = 0;
+    encodeWgpuFrameCapture(state, { copyTextureToBuffer: () => copies++ } as unknown as GPUCommandEncoder);
+
+    expect(copies).toBe(1);
+  });
 });

package/src/wgpuTextureResolver.test.ts

@@ -0,0 +1,209 @@
+import { createEntity } from '@flighthq/entity/contract';
+import type { Image, RenderTexture, Texture, TextureSource } from '@flighthq/types/contract';
+import {
+  BitmapTextureSourceKind,
+  CompressedImageTextureSourceKind,
+  ImageTextureSourceKind,
+  RenderTargetTextureSourceKind,
+} from '@flighthq/types/contract';
+
+import { renderWgpuBackground, submitWgpuRenderPass } from './wgpuBackground';
+import { getWgpuRenderStateRuntime } from './wgpuRenderState';
+import { renderIntoWgpuRenderTexture } from './wgpuRenderTexture';
+import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+import {
+  registerWgpuImageTextureResolver,
+  registerWgpuBitmapTextureResolver,
+  registerWgpuCompressedImageTextureResolver,
+  registerWgpuRenderTextureResolver,
+  registerStandardWgpuTextureResolvers,
+  registerWgpuTextureResolver,
+  resolveWgpuTexture,
+} from './wgpuTextureResolver';
+
+beforeAll(() => {
+  installWgpuMock();
+});
+
+function imageResource(source: CanvasImageSource = document.createElement('canvas')): Image {
+  return {
+    height: 4,
+    alphaType: 'straight',
+    gamut: 'srgb',
+    kind: ImageTextureSourceKind,
+    source,
+    version: 0,
+    width: 4,
+  } as unknown as Image;
+}
+
+function textureSource(kind: string): TextureSource {
+  return {
+    height: 4,
+    kind,
+    version: 0,
+    width: 4,
+  } as unknown as TextureSource;
+}
+
+function textureWithImage(image: TextureSource | null): Texture {
+  return {
+    colorSpace: 'srgb',
+    flipX: false,
+    flipY: false,
+    sampler: {
+      anisotropy: 1,
+      magFilter: 'linear',
+      minFilter: 'linear',
+      mipmaps: false,
+      wrapU: 'clamp-to-edge',
+      wrapV: 'clamp-to-edge',
+    },
+    dimension: '2d',
+    source: image,
+    uvOffset: { x: 0, y: 0 },
+    uvRotation: 0,
+    uvScale: { x: 1, y: 1 },
+    version: 0,
+  } as unknown as Texture;
+}
+
+function renderTexture(): RenderTexture {
+  const texture = textureWithImage(null);
+  texture.colorSpace = 'linear';
+  if (texture.dimension !== '2d') throw new Error('test texture must be 2d');
+  texture.source = createEntity({
+    alphaType: 'straight' as const,
+    gamut: 'srgb' as const,
+    height: 8,
+    kind: RenderTargetTextureSourceKind,
+    version: 0,
+    width: 8,
+  });
+  return texture as RenderTexture;
+}
+
+describe('registerStandardWgpuTextureResolvers', () => {
+  it('registers bitmap, image, and render texture sources without compressed images', async () => {
+    const state = await createWgpuRenderStateForTest();
+    registerStandardWgpuTextureResolvers(state);
+    expect([...getWgpuRenderStateRuntime(state).wgpuTextureResolverRegistry!.keys()]).toEqual([
+      BitmapTextureSourceKind,
+      ImageTextureSourceKind,
+      RenderTargetTextureSourceKind,
+    ]);
+  });
+});
+
+describe('registerWgpuBitmapTextureResolver', () => {
+  it('registers only the Bitmap source key', async () => {
+    const state = await createWgpuRenderStateForTest();
+    registerWgpuBitmapTextureResolver(state);
+    expect([...getWgpuRenderStateRuntime(state).wgpuTextureResolverRegistry!.keys()]).toEqual([
+      BitmapTextureSourceKind,
+    ]);
+  });
+});
+
+describe('registerWgpuCompressedImageTextureResolver', () => {
+  it('registers only the CompressedImage source key', async () => {
+    const state = await createWgpuRenderStateForTest();
+    registerWgpuCompressedImageTextureResolver(state);
+    expect([...getWgpuRenderStateRuntime(state).wgpuTextureResolverRegistry!.keys()]).toEqual([
+      CompressedImageTextureSourceKind,
+    ]);
+  });
+});
+
+describe('registerWgpuImageTextureResolver', () => {
+  it('resolves and caches a declared still-image source', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const texture = textureWithImage(imageResource());
+    registerWgpuImageTextureResolver(state);
+
+    const first = resolveWgpuTexture(state, texture);
+    expect(first).not.toBeNull();
+    expect(resolveWgpuTexture(state, texture)).toBe(first);
+  });
+
+  // The sample format comes from the PAIR (what the content is, what the destination composites in), not
+  // from an override. One sRGB texture therefore realizes two ways: decoded for a linear-working path
+  // (3D), byte-through for an encoded-working one (2D), cached apart so both can be live at once.
+  it('derives the sample format from the texture and working color spaces', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const createTexture = vi.spyOn(state.device, 'createTexture');
+    const texture = textureWithImage(imageResource());
+    registerWgpuImageTextureResolver(state);
+
+    const decoded = resolveWgpuTexture(state, texture, false, 'linear');
+    expect(createTexture).toHaveBeenLastCalledWith(expect.objectContaining({ format: 'rgba8unorm-srgb' }));
+
+    const byteThrough = resolveWgpuTexture(state, texture, false, 'srgb');
+    expect(byteThrough).not.toBe(decoded);
+    expect(createTexture).toHaveBeenLastCalledWith(expect.objectContaining({ format: 'rgba8unorm' }));
+
+    // Linear content never decodes, whichever space the destination works in.
+    const linearTexture = textureWithImage(imageResource());
+    (linearTexture as { colorSpace: string }).colorSpace = 'linear';
+    resolveWgpuTexture(state, linearTexture, false, 'linear');
+    expect(createTexture).toHaveBeenLastCalledWith(expect.objectContaining({ format: 'rgba8unorm' }));
+
+    expect(resolveWgpuTexture(state, texture, false, 'linear')).toBe(decoded);
+  });
+
+  it('resolves a host video through the image source kind', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const source = document.createElement('video');
+    Object.defineProperties(source, {
+      readyState: { value: 4 },
+      videoHeight: { value: 8 },
+      videoWidth: { value: 8 },
+    });
+    const image = imageResource(source);
+    const texture = textureWithImage(image);
+    registerWgpuImageTextureResolver(state);
+    expect(resolveWgpuTexture(state, texture)).not.toBeNull();
+  });
+});
+
+describe('registerWgpuRenderTextureResolver', () => {
+  it('returns a render target only after it has been rendered', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const texture = renderTexture();
+    registerWgpuRenderTextureResolver(state);
+    expect(resolveWgpuTexture(state, texture)).toBeNull();
+
+    renderWgpuBackground(state);
+    renderIntoWgpuRenderTexture(state, texture, () => {});
+    expect(resolveWgpuTexture(state, texture)).not.toBeNull();
+    submitWgpuRenderPass(state);
+  });
+});
+
+describe('registerWgpuTextureResolver', () => {
+  it('is state-scoped, last-write-wins by string kind, and removable', async () => {
+    const a = await createWgpuRenderStateForTest();
+    const b = await createWgpuRenderStateForTest();
+    const image = textureSource('acme.generated');
+    const texture = textureWithImage(image);
+    const first = vi.fn(() => ({ first: true }) as never);
+    const second = vi.fn(() => ({ second: true }) as never);
+
+    registerWgpuTextureResolver(a, image.kind, first);
+    expect(resolveWgpuTexture(a, texture)).toEqual({ first: true });
+    expect(resolveWgpuTexture(b, texture)).toBeNull();
+
+    registerWgpuTextureResolver(a, image.kind, second);
+    expect(resolveWgpuTexture(a, texture)).toEqual({ second: true });
+
+    registerWgpuTextureResolver(a, image.kind, null);
+    expect(resolveWgpuTexture(a, texture)).toBeNull();
+  });
+});
+
+describe('resolveWgpuTexture', () => {
+  it('returns null without an exact registered source kind', async () => {
+    const state = await createWgpuRenderStateForTest();
+    expect(resolveWgpuTexture(state, textureWithImage(null))).toBeNull();
+  });
+});

package/src/wgpuTextureUpload.test.ts

@@ -1,4 +1,4 @@
-import type { ImageResource } from '@flighthq/types/contract';
+import type { Image } from '@flighthq/types/contract';
 
 import { uploadWgpuTextureData, uploadWgpuTextureElement, uploadWgpuTextureImageResource } from './wgpuTextureUpload';
 
@@ -28,7 +28,9 @@ describe('uploadWgpuTextureElement', () => {
   it('drives copyExternalImageToTexture with the external source', () => {
     const device = makeDevice();
     const texture = {} as GPUTexture;
-    const source = {} as GPUCopyExternalImageSource;
+    const source = document.createElement('canvas');
+    source.width = 4;
+    source.height = 4;
     uploadWgpuTextureElement(device, texture, [0, 0, 0], 4, 4, source);
     expect(device.queue.copyExternalImageToTexture).toHaveBeenCalledWith(
       { source },
@@ -36,25 +38,38 @@ describe('uploadWgpuTextureElement', () => {
       [4, 4, 1],
     );
   });
+
+  it('skips a copy with a zero-sized extent', () => {
+    const device = makeDevice();
+    const source = document.createElement('canvas');
+    source.width = 4;
+    source.height = 4;
+    uploadWgpuTextureElement(device, {} as GPUTexture, [0, 0, 0], 0, 4, source);
+    expect(device.queue.copyExternalImageToTexture).not.toHaveBeenCalled();
+  });
+
+  it('skips a copy when the browser cannot snapshot the source', () => {
+    const device = makeDevice();
+    const canvas = document.createElement('canvas');
+    canvas.width = 4;
+    canvas.height = 4;
+    vi.mocked(device.queue.copyExternalImageToTexture).mockImplementation(() => {
+      throw new TypeError('Failed to copy content from external image.');
+    });
+    expect(() => uploadWgpuTextureElement(device, {} as GPUTexture, [0, 0, 0], 4, 4, canvas)).not.toThrow();
+  });
 });
 
 describe('uploadWgpuTextureImageResource', () => {
   it('takes the element path when the resource carries a source', () => {
     const device = makeDevice();
     const texture = {} as GPUTexture;
-    const image = { source: {} as CanvasImageSource, data: null, width: 4, height: 4 } as ImageResource;
+    const source = document.createElement('canvas');
+    source.width = 4;
+    source.height = 4;
+    const image = { source, width: 4, height: 4 } as unknown as Image;
     uploadWgpuTextureImageResource(device, texture, [0, 0, 0], image);
     expect(device.queue.copyExternalImageToTexture).toHaveBeenCalledTimes(1);
     expect(device.queue.writeTexture).not.toHaveBeenCalled();
   });
-
-  it('takes the raw-pixel path when the resource is data-only', () => {
-    const device = makeDevice();
-    const texture = {} as GPUTexture;
-    const data = new Uint8ClampedArray(4 * 4 * 4);
-    const image = { source: null, data, width: 4, height: 4 } as ImageResource;
-    uploadWgpuTextureImageResource(device, texture, [0, 0, 0], image);
-    expect(device.queue.writeTexture).toHaveBeenCalledTimes(1);
-    expect(device.queue.copyExternalImageToTexture).not.toHaveBeenCalled();
-  });
 });