@flighthq/render-wgpu 0.5.1-next.1069.554a2ac → 0.5.1-next.1201.9b49dee

package/src/wgpuRenderTarget.test.ts

@@ -1,170 +1,41 @@
-import { createMatrix } from '@flighthq/geometry/contract';
-import type { WgpuRenderTarget } from '@flighthq/types/contract';
+import type { WgpuRenderTarget, WgpuScreenRenderTarget } from '@flighthq/types/contract';
 
-import { renderWgpuBackground, submitWgpuRenderPass } from './wgpuBackground';
-import { resolveWgpuSmoothingBindGroup } from './wgpuDraw';
-import { getWgpuRenderStateDeviceResources, getWgpuRenderStateRuntime } from './wgpuRenderState';
+import { beginWgpuRenderPass, endWgpuRenderPass } from './wgpuRenderPass';
+import { getWgpuRenderStateRuntime } from './wgpuRenderState';
+import { declareWgpuRenderTargetColorSpace, getWgpuRenderTargetSupersampleScale } from './wgpuRenderTarget';
 import {
-  beginWgpuRenderPass,
-  createWgpuRenderTarget,
-  declareWgpuRenderTargetColorSpace,
-  destroyWgpuRenderTarget,
-  drawWgpuRenderTargetResult,
-  endWgpuRenderPass,
-  getWgpuRenderTargetSupersampleScale,
-  initializeWgpuRenderTarget,
-  resizeWgpuRenderTarget,
-  setWgpuRenderTransform2D,
-} from './wgpuRenderTarget';
-import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+  beginWgpuScreenRenderPassForTest,
+  createWgpuRenderStateForTest,
+  createWgpuScreenRenderTargetForTest,
+  installWgpuMock,
+} from './wgpuTestHelper';
+import { createWgpuTextureRenderTarget } from './wgpuTextureRenderTarget';
 
 beforeAll(() => {
   installWgpuMock();
 });
 
-describe('beginWgpuRenderPass', () => {
-  it('sets the render target viewport', async () => {
-    const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
-    const target = createWgpuRenderTarget(state, 64, 64);
-    beginWgpuRenderPass(state, target);
-    expect(getWgpuRenderStateRuntime(state).renderTargetViewport?.width).toBe(64);
-    endWgpuRenderPass(state);
-    submitWgpuRenderPass(state);
-  });
-
-  it('switches the render target and restores it on end', async () => {
-    const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
-
-    const target = createWgpuRenderTarget(state, 128, 128);
-    beginWgpuRenderPass(state, target);
-
-    const runtime = getWgpuRenderStateRuntime(state);
-    expect(runtime.renderTargetViewport?.width).toBe(128);
-
-    endWgpuRenderPass(state);
-    expect(runtime.renderTargetViewport).toBeNull();
-
-    submitWgpuRenderPass(state);
-  });
-});
-
-describe('createWgpuRenderTarget', () => {
-  it('returns a target with texture, view, binding cache, and depth-stencil', async () => {
-    const state = await createWgpuRenderStateForTest();
-    const target = createWgpuRenderTarget(state, 256, 256);
-    expect(target.texture).toBeDefined();
-    expect(target.view).toBeDefined();
-    expect(target.bindings).toBeDefined();
-    expect(target.depthStencilTexture).toBeDefined();
-    expect(target.width).toBe(256);
-    expect(target.height).toBe(256);
-  });
-
-  it('clamps to minimum 1×1', async () => {
-    const state = await createWgpuRenderStateForTest();
-    const target = createWgpuRenderTarget(state, 0, 0);
-    expect(target.width).toBe(1);
-    expect(target.height).toBe(1);
-  });
-
-  it('defaults to sRGB and accepts a linear content declaration', async () => {
-    const state = await createWgpuRenderStateForTest();
-    expect(createWgpuRenderTarget(state, 16, 16).colorSpace).toBe('srgb');
-    expect(createWgpuRenderTarget(state, 16, 16, state.format, 'linear').colorSpace).toBe('linear');
-  });
-
-  it('realizes four coverage samples as a 2x extent in each axis', async () => {
-    const state = await createWgpuRenderStateForTest();
-    const target = createWgpuRenderTarget(state, 64, 48, state.format, 'srgb', 4);
-    expect(target.width).toBe(128);
-    expect(target.height).toBe(96);
-    expect(target.sampleCount).toBe(4);
-    expect(target.texture.width).toBe(128);
-    expect(target.texture.height).toBe(96);
-  });
-});
-
 describe('declareWgpuRenderTargetColorSpace', () => {
-  it('decodes a nonblack packed sRGB clear when the target is created as linear', async () => {
-    const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
-    const runtime = getWgpuRenderStateRuntime(state);
-    const beginRenderPass = vi.spyOn(runtime.commandEncoder!, 'beginRenderPass');
-    const target = createWgpuRenderTarget(state, 32, 32, state.format, 'linear');
-    target.clearColors = [0x0a0c10ff];
-
-    beginWgpuRenderPass(state, target);
-    const attachment = Array.from(beginRenderPass.mock.calls.at(-1)![0].colorAttachments)[0]!;
-    const linearClear = attachment.clearValue as GPUColorDict;
-    expect(beginRenderPass).toHaveBeenCalledTimes(1);
-    expect(linearClear.r).toBeCloseTo(0.00303527);
-    expect(linearClear.g).toBeCloseTo(0.00367651);
-    expect(linearClear.b).toBeCloseTo(0.00518152);
-    expect(linearClear.a).toBe(1);
-
-    endWgpuRenderPass(state);
-    submitWgpuRenderPass(state);
-  });
-
-  it('stamps the current target and restores the enclosing target on end', async () => {
+  it('stamps the innermost open target and reports false outside a pass', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
-    const outer = createWgpuRenderTarget(state, 32, 32);
-    const inner = createWgpuRenderTarget(state, 16, 16);
+    const outer = createWgpuTextureRenderTarget(state, 32, 32);
+    const inner = createWgpuTextureRenderTarget(state, 16, 16);
 
     expect(declareWgpuRenderTargetColorSpace(state, 'linear')).toBe(false);
-    beginWgpuRenderPass(state, outer);
+
+    const screenPass = beginWgpuScreenRenderPassForTest(state);
+    const outerPass = beginWgpuRenderPass(state, outer);
     expect(declareWgpuRenderTargetColorSpace(state, 'linear')).toBe(true);
-    beginWgpuRenderPass(state, inner);
+    const innerPass = beginWgpuRenderPass(state, inner);
     expect(declareWgpuRenderTargetColorSpace(state, 'linear')).toBe(true);
-    endWgpuRenderPass(state);
+
+    endWgpuRenderPass(innerPass);
     expect(getWgpuRenderStateRuntime(state).currentRenderTarget).toBe(outer);
-    endWgpuRenderPass(state);
-    expect(getWgpuRenderStateRuntime(state).currentRenderTarget).toBeNull();
+    endWgpuRenderPass(outerPass);
+    endWgpuRenderPass(screenPass);
+
     expect(outer.colorSpace).toBe('linear');
     expect(inner.colorSpace).toBe('linear');
-    submitWgpuRenderPass(state);
-  });
-});
-
-describe('destroyWgpuRenderTarget', () => {
-  it('calls destroy on texture and depth-stencil', async () => {
-    const state = await createWgpuRenderStateForTest();
-    const target = createWgpuRenderTarget(state, 64, 64);
-    const destroyTexture = vi.spyOn(target.texture, 'destroy');
-    const destroyDepth = vi.spyOn(target.depthStencilTexture, 'destroy');
-    destroyWgpuRenderTarget(state, target);
-    expect(destroyTexture).toHaveBeenCalled();
-    expect(destroyDepth).toHaveBeenCalled();
-  });
-});
-
-describe('drawWgpuRenderTargetResult', () => {
-  it('does not throw with an open render pass', async () => {
-    const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
-    const target = createWgpuRenderTarget(state, 64, 64);
-    const fakeNode = {
-      alpha: 1,
-      material: null,
-      transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 },
-    };
-    expect(() => drawWgpuRenderTargetResult(state, fakeNode, target, createMatrix())).not.toThrow();
-    submitWgpuRenderPass(state);
-  });
-});
-
-describe('endWgpuRenderPass', () => {
-  it('restores null renderTargetViewport', async () => {
-    const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
-    const target = createWgpuRenderTarget(state, 32, 32);
-    beginWgpuRenderPass(state, target);
-    endWgpuRenderPass(state);
-    expect(getWgpuRenderStateRuntime(state).renderTargetViewport).toBeNull();
-    submitWgpuRenderPass(state);
   });
 });
 
@@ -173,9 +44,22 @@ describe('getWgpuRenderTargetSupersampleScale', () => {
   // if the 2D projection divides by that physical width it maps logical x = 800 to NDC 0, and the scene
   // fills a quarter of its own target. Measured on effect-sepia before the repair: the WebGPU frame
   // equalled the WebGL frame sampled at (2x, 2y) on 12 of 12 grid points; after, 48 of 48 matched 1:1.
-  it('reports 2 for a supersampled target and 1 for a single-sample one', () => {
-    expect(getWgpuRenderTargetSupersampleScale({ sampleCount: 4 } as WgpuRenderTarget)).toBe(2);
-    expect(getWgpuRenderTargetSupersampleScale({ sampleCount: 1 } as WgpuRenderTarget)).toBe(1);
+  it('reports 2 for a supersampled texture target and 1 for a single-sample one', () => {
+    expect(getWgpuRenderTargetSupersampleScale({ context: null, sampleCount: 4 } as WgpuRenderTarget)).toBe(2);
+    expect(getWgpuRenderTargetSupersampleScale({ context: null, sampleCount: 1 } as WgpuRenderTarget)).toBe(1);
+  });
+
+  // A screen target reaches supersampling by a different route — an antialias option rather than a sample
+  // count — and the two must resolve to one number, or the scissor and the projection disagree about which
+  // coordinate space the frame is in.
+  it('reads a screen target from its antialias option, not its sample count', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const plain = createWgpuScreenRenderTargetForTest(state);
+    const antialiased = createWgpuScreenRenderTargetForTest(state, { antialias: true });
+
+    expect(getWgpuRenderTargetSupersampleScale(plain)).toBe(1);
+    expect(getWgpuRenderTargetSupersampleScale(antialiased)).toBe(2);
+    expect(antialiased.sampleCount).toBe(1);
   });
 
   // Dividing the physical extent by the scale has to land back on the logical extent exactly, or the
@@ -189,77 +73,18 @@ describe('getWgpuRenderTargetSupersampleScale', () => {
       [1, 4],
     ] as const) {
       const physical = Math.max(1, Math.ceil(logical)) * (sampleCount === 4 ? 2 : 1);
-      const scale = getWgpuRenderTargetSupersampleScale({ sampleCount } as WgpuRenderTarget);
+      const scale = getWgpuRenderTargetSupersampleScale({ context: null, sampleCount } as WgpuRenderTarget);
 
       expect(physical / scale).toBe(logical);
     }
   });
-});
 
-describe('initializeWgpuRenderTarget', () => {
-  it('is the construction initializer of createWgpuRenderTarget', () => {
-    expect(typeof initializeWgpuRenderTarget).toBe('function');
-  });
-});
-
-describe('resizeWgpuRenderTarget', () => {
-  it('preserves the allocation when dimensions are unchanged', async () => {
-    const state = await createWgpuRenderStateForTest();
-    const target = createWgpuRenderTarget(state, 64, 64);
-    const texture = target.texture;
-    const depthStencilTexture = target.depthStencilTexture;
-    const sampler = getWgpuRenderStateDeviceResources(state).linearSampler;
-    const bindGroup = resolveWgpuSmoothingBindGroup(state, target, true);
-
-    resizeWgpuRenderTarget(state, target, 64, 64);
-
-    expect(target.texture).toBe(texture);
-    expect(target.depthStencilTexture).toBe(depthStencilTexture);
-    // The view survived, so its cached bindings must survive with it.
-    expect(target.bindings.get(sampler)).toBe(bindGroup);
-  });
-
-  it('updates width, height, and drops bindings that referenced the old view', async () => {
-    const state = await createWgpuRenderStateForTest();
-    const target = createWgpuRenderTarget(state, 64, 64);
-    const previousBindGroup = resolveWgpuSmoothingBindGroup(state, target, true);
-    resizeWgpuRenderTarget(state, target, 200, 150);
-    expect(target.width).toBe(200);
-    expect(target.height).toBe(150);
-    // Reallocation replaces the view, so every binding over the old one is dropped and rebuilt.
-    expect(target.bindings.size).toBe(0);
-    expect(resolveWgpuSmoothingBindGroup(state, target, true)).not.toBe(previousBindGroup);
-  });
-
-  it('reallocates when the effective sample count changes', async () => {
-    const state = await createWgpuRenderStateForTest();
-    const target = createWgpuRenderTarget(state, 64, 48);
-    const previousTexture = target.texture;
-
-    resizeWgpuRenderTarget(state, target, 64, 48, 4);
-
-    expect(target.width).toBe(128);
-    expect(target.height).toBe(96);
-    expect(target.sampleCount).toBe(4);
-    expect(target.texture).not.toBe(previousTexture);
-  });
-});
-describe('setWgpuRenderTransform2D', () => {
-  it('installs a copy of the transform, restored by the enclosing pass', async () => {
+  it('inverts the screen allocator exactly for a supersampled surface', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
-    const original = state.renderTransform2D;
-    const target = createWgpuRenderTarget(state, 32, 32);
-    const bake = createMatrix();
-    bake.tx = 42;
-
-    beginWgpuRenderPass(state, target);
-    setWgpuRenderTransform2D(state, bake);
-    expect(state.renderTransform2D?.tx).toBe(42);
-    expect(state.renderTransform2D).not.toBe(bake);
-    endWgpuRenderPass(state);
+    const screen: WgpuScreenRenderTarget = createWgpuScreenRenderTargetForTest(state, { antialias: true }, 801, 599);
 
-    expect(state.renderTransform2D).toBe(original);
-    submitWgpuRenderPass(state);
+    expect(screen.width).toBe(1602);
+    expect(screen.width / getWgpuRenderTargetSupersampleScale(screen)).toBe(801);
+    expect(screen.height / getWgpuRenderTargetSupersampleScale(screen)).toBe(599);
   });
 });

package/src/wgpuRenderTargetPool.test.ts

@@ -1,9 +1,9 @@
 import {
-  acquireWgpuRenderTarget,
+  acquireWgpuTextureRenderTarget,
   createWgpuRenderTargetPool,
   destroyWgpuRenderTargetPool,
   initializeWgpuRenderTargetPool,
-  releaseWgpuRenderTarget,
+  releaseWgpuTextureRenderTarget,
 } from './wgpuRenderTargetPool';
 import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
 
@@ -11,22 +11,22 @@ beforeAll(() => {
   installWgpuMock();
 });
 
-describe('acquireWgpuRenderTarget', () => {
+describe('acquireWgpuTextureRenderTarget', () => {
   it('reuses a released target matching width, height, and format', async () => {
     const state = await createWgpuRenderStateForTest();
     const pool = createWgpuRenderTargetPool();
-    const first = acquireWgpuRenderTarget(state, pool, { width: 64, height: 64 });
-    releaseWgpuRenderTarget(pool, first);
-    const second = acquireWgpuRenderTarget(state, pool, { width: 64, height: 64 });
+    const first = acquireWgpuTextureRenderTarget(state, pool, { width: 64, height: 64 });
+    releaseWgpuTextureRenderTarget(pool, first);
+    const second = acquireWgpuTextureRenderTarget(state, pool, { width: 64, height: 64 });
     expect(second).toBe(first);
   });
 
   it('allocates a distinct target when no free target matches the format', async () => {
     const state = await createWgpuRenderStateForTest();
     const pool = createWgpuRenderTargetPool();
-    const eight = acquireWgpuRenderTarget(state, pool, { width: 64, height: 64 });
-    releaseWgpuRenderTarget(pool, eight);
-    const hdr = acquireWgpuRenderTarget(state, pool, { width: 64, height: 64, format: 'rgba16float' });
+    const eight = acquireWgpuTextureRenderTarget(state, pool, { width: 64, height: 64 });
+    releaseWgpuTextureRenderTarget(pool, eight);
+    const hdr = acquireWgpuTextureRenderTarget(state, pool, { width: 64, height: 64, format: 'rgba16float' });
     expect(hdr).not.toBe(eight);
     expect(hdr.format).toBe('rgba16float');
   });
@@ -34,26 +34,26 @@ describe('acquireWgpuRenderTarget', () => {
   it('realizes and pools a four-sample request at twice the extent in each axis', async () => {
     const state = await createWgpuRenderStateForTest();
     const pool = createWgpuRenderTargetPool();
-    const supersampled = acquireWgpuRenderTarget(state, pool, { width: 64, height: 48, sampleCount: 4 });
+    const supersampled = acquireWgpuTextureRenderTarget(state, pool, { width: 64, height: 48, sampleCount: 4 });
     expect(supersampled.width).toBe(128);
     expect(supersampled.height).toBe(96);
     expect(supersampled.sampleCount).toBe(4);
 
-    releaseWgpuRenderTarget(pool, supersampled);
-    const singleSampled = acquireWgpuRenderTarget(state, pool, { width: 128, height: 96 });
+    releaseWgpuTextureRenderTarget(pool, supersampled);
+    const singleSampled = acquireWgpuTextureRenderTarget(state, pool, { width: 128, height: 96 });
     expect(singleSampled).not.toBe(supersampled);
 
-    const reused = acquireWgpuRenderTarget(state, pool, { width: 64, height: 48, sampleCount: 4 });
+    const reused = acquireWgpuTextureRenderTarget(state, pool, { width: 64, height: 48, sampleCount: 4 });
     expect(reused).toBe(supersampled);
   });
 
   it('re-stamps the logical color space when reusing storage', async () => {
     const state = await createWgpuRenderStateForTest();
     const pool = createWgpuRenderTargetPool();
-    const first = acquireWgpuRenderTarget(state, pool, { width: 64, height: 64, colorSpace: 'linear' });
+    const first = acquireWgpuTextureRenderTarget(state, pool, { width: 64, height: 64, colorSpace: 'linear' });
     expect(first.colorSpace).toBe('linear');
-    releaseWgpuRenderTarget(pool, first);
-    const reused = acquireWgpuRenderTarget(state, pool, { width: 64, height: 64 });
+    releaseWgpuTextureRenderTarget(pool, first);
+    const reused = acquireWgpuTextureRenderTarget(state, pool, { width: 64, height: 64 });
     expect(reused).toBe(first);
     expect(reused.colorSpace).toBe('srgb');
   });
@@ -69,8 +69,8 @@ describe('destroyWgpuRenderTargetPool', () => {
   it('clears the free list', async () => {
     const state = await createWgpuRenderStateForTest();
     const pool = createWgpuRenderTargetPool();
-    releaseWgpuRenderTarget(pool, acquireWgpuRenderTarget(state, pool, { width: 32, height: 32 }));
-    destroyWgpuRenderTargetPool(state, pool);
+    releaseWgpuTextureRenderTarget(pool, acquireWgpuTextureRenderTarget(state, pool, { width: 32, height: 32 }));
+    destroyWgpuRenderTargetPool(pool);
     expect(pool.free.length).toBe(0);
   });
 });
@@ -80,12 +80,12 @@ describe('initializeWgpuRenderTargetPool', () => {
     expect(typeof initializeWgpuRenderTargetPool).toBe('function');
   });
 });
-describe('releaseWgpuRenderTarget', () => {
+describe('releaseWgpuTextureRenderTarget', () => {
   it('returns the target to the free list', async () => {
     const state = await createWgpuRenderStateForTest();
     const pool = createWgpuRenderTargetPool();
-    const target = acquireWgpuRenderTarget(state, pool, { width: 16, height: 16 });
-    releaseWgpuRenderTarget(pool, target);
+    const target = acquireWgpuTextureRenderTarget(state, pool, { width: 16, height: 16 });
+    releaseWgpuTextureRenderTarget(pool, target);
     expect(pool.free).toContain(target);
   });
 });

package/src/wgpuRenderTexture.test.ts

@@ -1,7 +1,7 @@
-import type { RenderTexture } from '@flighthq/types/contract';
+import type { RenderTargetClear, RenderTexture } from '@flighthq/types/contract';
 import { RenderTargetTextureSourceKind } from '@flighthq/types/contract';
 
-import { renderWgpuBackground, submitWgpuRenderPass } from './wgpuBackground';
+import { submitWgpuFrame } from './wgpuFrame';
 import { getWgpuRenderStateRuntime } from './wgpuRenderState';
 import {
   bindWgpuRenderTexture,
@@ -14,7 +14,7 @@ import {
   setWgpuRenderTextureGuard,
   writeWgpuRenderTextureTarget,
 } from './wgpuRenderTexture';
-import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+import { beginWgpuScreenRenderPassForTest, createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
 
 beforeAll(() => {
   installWgpuMock();
@@ -48,10 +48,10 @@ describe('bindWgpuRenderTexture', () => {
     const renderTexture = texture();
     expect(bindWgpuRenderTexture(state, renderTexture)).toBeNull();
 
-    renderWgpuBackground(state);
-    renderIntoWgpuRenderTexture(state, renderTexture, () => {});
+    beginWgpuScreenRenderPassForTest(state);
+    renderIntoWgpuRenderTexture(state, renderTexture, () => {}, TRANSPARENT_CLEAR);
     expect(bindWgpuRenderTexture(state, renderTexture)).not.toBeNull();
-    submitWgpuRenderPass(state);
+    submitWgpuFrame(state);
   });
 });
 
@@ -59,15 +59,15 @@ describe('destroyWgpuRenderTexture', () => {
   it('destroys and removes the hidden target', async () => {
     const state = await createWgpuRenderStateForTest();
     const renderTexture = texture();
-    renderWgpuBackground(state);
-    renderIntoWgpuRenderTexture(state, renderTexture, () => {});
+    beginWgpuScreenRenderPassForTest(state);
+    renderIntoWgpuRenderTexture(state, renderTexture, () => {}, TRANSPARENT_CLEAR);
     const entry = getWgpuRenderStateRuntime(state).context.wgpuRenderTextureCache!.get(renderTexture)!;
     const destroy = vi.spyOn(entry.target.texture, 'destroy');
 
     destroyWgpuRenderTexture(state, renderTexture);
     expect(destroy).toHaveBeenCalled();
     expect(bindWgpuRenderTexture(state, renderTexture)).toBeNull();
-    submitWgpuRenderPass(state);
+    submitWgpuFrame(state);
   });
 });
 
@@ -109,10 +109,10 @@ describe('isWgpuRenderTextureReady', () => {
     const state = await createWgpuRenderStateForTest();
     const renderTexture = texture();
     expect(isWgpuRenderTextureReady(state, renderTexture)).toBe(false);
-    renderWgpuBackground(state);
-    renderIntoWgpuRenderTexture(state, renderTexture, () => {});
+    beginWgpuScreenRenderPassForTest(state);
+    renderIntoWgpuRenderTexture(state, renderTexture, () => {}, TRANSPARENT_CLEAR);
     expect(isWgpuRenderTextureReady(state, renderTexture)).toBe(true);
-    submitWgpuRenderPass(state);
+    submitWgpuFrame(state);
   });
 });
 
@@ -120,16 +120,16 @@ describe('renderIntoWgpuRenderTexture', () => {
   it('restores the enclosing pass and bumps version after success', async () => {
     const state = await createWgpuRenderStateForTest();
     const renderTexture = texture();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const enclosingPass = getWgpuRenderStateRuntime(state).renderPass;
 
-    renderIntoWgpuRenderTexture(state, renderTexture, () => {});
+    renderIntoWgpuRenderTexture(state, renderTexture, () => {}, TRANSPARENT_CLEAR);
 
     expect(renderTexture.version).toBe(1);
     expect(renderTexture.colorSpace).toBe('linear');
     expect(getWgpuRenderStateRuntime(state).renderPass).not.toBeNull();
     expect(getWgpuRenderStateRuntime(state).renderPass).not.toBe(enclosingPass);
-    submitWgpuRenderPass(state);
+    submitWgpuFrame(state);
   });
 });
 
@@ -176,3 +176,5 @@ describe('writeWgpuRenderTextureTarget', () => {
     expect(target.sampleCount).toBe(4);
   });
 });
+
+const TRANSPARENT_CLEAR: Readonly<RenderTargetClear> = { color: [0, 0, 0, 0], depth: 1.0, stencil: 0 };

package/src/wgpuScissor.test.ts

@@ -1,4 +1,4 @@
-import { renderWgpuBackground } from './wgpuBackground';
+import { beginWgpuRenderPass, endWgpuRenderPass } from './wgpuRenderPass';
 import { getWgpuRenderStateRuntime } from './wgpuRenderState';
 import {
   applyWgpuScissorRect,
@@ -6,7 +6,8 @@ import {
   pushWgpuScissorRect,
   setWgpuRenderPassScissorRect,
 } from './wgpuScissor';
-import { createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+import { beginWgpuScreenRenderPassForTest, createWgpuRenderStateForTest, installWgpuMock } from './wgpuTestHelper';
+import { createWgpuTextureRenderTarget } from './wgpuTextureRenderTarget';
 
 beforeAll(() => {
   installWgpuMock();
@@ -15,7 +16,7 @@ beforeAll(() => {
 describe('applyWgpuScissorRect', () => {
   it('calls setScissorRect on the pass when a rect is active', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const runtime = getWgpuRenderStateRuntime(state);
     runtime.currentScissorRect = { x: 10, y: 20, width: 100, height: 50 };
     const calls: number[][] = [];
@@ -27,7 +28,7 @@ describe('applyWgpuScissorRect', () => {
 
   it('is a no-op when currentScissorRect is null', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const calls: number[][] = [];
     const fakePass = { setScissorRect: (...args: number[]) => calls.push(args) } as unknown as GPURenderPassEncoder;
     applyWgpuScissorRect(state, fakePass);
@@ -36,7 +37,7 @@ describe('applyWgpuScissorRect', () => {
 
   it('clamps dimensions to at least 1×1', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const runtime = getWgpuRenderStateRuntime(state);
     runtime.currentScissorRect = { x: 0, y: 0, width: 0, height: 0 };
     const calls: number[][] = [];
@@ -49,14 +50,14 @@ describe('applyWgpuScissorRect', () => {
 describe('popWgpuScissorRect', () => {
   it('is a no-op when the stack is empty', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     expect(() => popWgpuScissorRect(state)).not.toThrow();
     expect(getWgpuRenderStateRuntime(state).currentScissorRect).toBeNull();
   });
 
   it('restores the previous rect after a push/pop pair', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const r1 = { x: 0, y: 0, width: 100, height: 100 };
     const r2 = { x: 10, y: 10, width: 50, height: 50 };
     pushWgpuScissorRect(state, r1);
@@ -72,7 +73,7 @@ describe('popWgpuScissorRect', () => {
 describe('pushWgpuScissorRect', () => {
   it('sets currentScissorRect on first push', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const rect = { x: 5, y: 10, width: 80, height: 40 };
     pushWgpuScissorRect(state, rect);
     expect(getWgpuRenderStateRuntime(state).currentScissorRect).toEqual(rect);
@@ -80,7 +81,7 @@ describe('pushWgpuScissorRect', () => {
 
   it('stacks previous rect when pushing a second rect', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const r1 = { x: 0, y: 0, width: 100, height: 100 };
     const r2 = { x: 20, y: 20, width: 60, height: 60 };
     pushWgpuScissorRect(state, r1);
@@ -93,7 +94,7 @@ describe('pushWgpuScissorRect', () => {
 
   it('copies the rect so mutation of the original does not affect the pushed value', async () => {
     const state = await createWgpuRenderStateForTest();
-    renderWgpuBackground(state);
+    beginWgpuScreenRenderPassForTest(state);
     const rect = { x: 0, y: 0, width: 50, height: 50 };
     pushWgpuScissorRect(state, rect);
     rect.width = 999;
@@ -102,13 +103,42 @@ describe('pushWgpuScissorRect', () => {
 });
 
 describe('setWgpuRenderPassScissorRect', () => {
-  it('scales logical coordinates on the acquired supersample surface', async () => {
-    const state = await createWgpuRenderStateForTest({ antialias: true });
-    renderWgpuBackground(state);
+  it('scales logical coordinates onto a supersampled screen surface', async () => {
+    const state = await createWgpuRenderStateForTest();
+    beginWgpuScreenRenderPassForTest(state, { color: [0, 0, 0, 0] }, { antialias: true });
+    const setScissorRect = vi.fn();
+
+    setWgpuRenderPassScissorRect(state, { setScissorRect } as unknown as GPURenderPassEncoder, 3, 5, 7, 11);
+
+    expect(setScissorRect).toHaveBeenCalledWith(6, 10, 14, 22);
+  });
+
+  // Logical is one coordinate space, so a supersampled OFFSCREEN target scales its scissors by the same
+  // factor its storage was grown by. It previously passed them through unscaled while the screen scaled
+  // them, which left a clip inside a sampleCount-4 effect target covering a quarter of its intended area.
+  it('scales them onto a supersampled texture target by the same rule', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const outer = beginWgpuScreenRenderPassForTest(state);
+    const pass = beginWgpuRenderPass(state, createWgpuTextureRenderTarget(state, 64, 64, state.format, 'srgb', 4));
     const setScissorRect = vi.fn();
 
     setWgpuRenderPassScissorRect(state, { setScissorRect } as unknown as GPURenderPassEncoder, 3, 5, 7, 11);
 
     expect(setScissorRect).toHaveBeenCalledWith(6, 10, 14, 22);
+    endWgpuRenderPass(pass);
+    endWgpuRenderPass(outer);
+  });
+
+  it('passes them through unscaled on a target with no supersample', async () => {
+    const state = await createWgpuRenderStateForTest();
+    const outer = beginWgpuScreenRenderPassForTest(state);
+    const pass = beginWgpuRenderPass(state, createWgpuTextureRenderTarget(state, 64, 64));
+    const setScissorRect = vi.fn();
+
+    setWgpuRenderPassScissorRect(state, { setScissorRect } as unknown as GPURenderPassEncoder, 3, 5, 7, 11);
+
+    expect(setScissorRect).toHaveBeenCalledWith(3, 5, 7, 11);
+    endWgpuRenderPass(pass);
+    endWgpuRenderPass(outer);
   });
 });