@flighthq/render-gl 0.1.0

package/src/glReadback.test.ts

@@ -0,0 +1,82 @@
+import type { GlRenderTarget } from '@flighthq/types';
+
+import { readGlRenderTargetPixels } from './glReadback';
+import { createGlState } from './glTestHelper';
+
+function makeTarget(overrides?: Partial<GlRenderTarget>): GlRenderTarget {
+  return {
+    width: 4,
+    height: 4,
+    format: 'rgba8',
+    sampleCount: 1,
+    framebuffer: {} as WebGLFramebuffer,
+    resolveFramebuffer: null,
+    textures: [{} as WebGLTexture],
+    texture: {} as WebGLTexture,
+    depthTexture: null,
+    colorRenderbuffers: [],
+    depthStencilRenderbuffer: null,
+    ...overrides,
+  } as GlRenderTarget;
+}
+
+describe('readGlRenderTargetPixels', () => {
+  it('returns false for a zero-width target', () => {
+    const { state } = createGlState();
+    const target = makeTarget({ width: 0, height: 4 });
+    const out = new Uint8Array(16);
+    expect(readGlRenderTargetPixels(state, target, 0, 0, 1, 1, out)).toBe(false);
+  });
+
+  it('returns false for a zero-height target', () => {
+    const { state } = createGlState();
+    const target = makeTarget({ width: 4, height: 0 });
+    const out = new Uint8Array(16);
+    expect(readGlRenderTargetPixels(state, target, 0, 0, 1, 1, out)).toBe(false);
+  });
+
+  it('returns false when the framebuffer is incomplete', () => {
+    const { state } = createGlState();
+    const target = makeTarget();
+    vi.spyOn(state.gl, 'checkFramebufferStatus').mockReturnValue(state.gl.FRAMEBUFFER_INCOMPLETE_ATTACHMENT ?? 36054);
+    const out = new Uint8Array(16);
+    expect(readGlRenderTargetPixels(state, target, 0, 0, 1, 1, out)).toBe(false);
+  });
+
+  it('returns true and calls readPixels when the framebuffer is complete', () => {
+    const { state } = createGlState();
+    const target = makeTarget();
+    vi.spyOn(state.gl, 'checkFramebufferStatus').mockReturnValue(state.gl.FRAMEBUFFER_COMPLETE ?? 36053);
+    const readPixelsSpy = vi.spyOn(state.gl, 'readPixels').mockImplementation(() => {});
+    const out = new Uint8Array(16);
+    const result = readGlRenderTargetPixels(state, target, 0, 0, 4, 4, out);
+    expect(result).toBe(true);
+    expect(readPixelsSpy).toHaveBeenCalled();
+  });
+
+  it('uses FLOAT type for Float32Array output', () => {
+    const { state } = createGlState();
+    const target = makeTarget({ format: 'rgba32f' });
+    vi.spyOn(state.gl, 'checkFramebufferStatus').mockReturnValue(state.gl.FRAMEBUFFER_COMPLETE ?? 36053);
+    const readPixelsSpy = vi.spyOn(state.gl, 'readPixels').mockImplementation(() => {});
+    const out = new Float32Array(16);
+    readGlRenderTargetPixels(state, target, 0, 0, 4, 4, out);
+    const glConst = state.gl;
+    expect(readPixelsSpy).toHaveBeenCalledWith(0, 0, 4, 4, expect.any(Number), glConst.FLOAT, out);
+  });
+
+  it('uses the resolveFramebuffer when present', () => {
+    const { state } = createGlState();
+    const resolveFbo = {} as WebGLFramebuffer;
+    const drawFbo = {} as WebGLFramebuffer;
+    const target = makeTarget({ framebuffer: drawFbo, resolveFramebuffer: resolveFbo });
+    const bindSpy = vi.spyOn(state.gl, 'bindFramebuffer');
+    vi.spyOn(state.gl, 'readPixels').mockImplementation(() => {});
+    const out = new Uint8Array(16);
+    readGlRenderTargetPixels(state, target, 0, 0, 1, 1, out);
+    // Verify the resolve FBO (not the draw FBO) was bound for reading.
+    const boundFbos = bindSpy.mock.calls.map((call) => call[1]);
+    expect(boundFbos).toContain(resolveFbo);
+    expect(boundFbos).not.toContain(drawFbo);
+  });
+});

package/src/glRenderState.test.ts

@@ -0,0 +1,186 @@
+import { BlendMode } from '@flighthq/types';
+
+import {
+  createGlRenderState,
+  createGlRenderStateRuntime,
+  destroyGlRenderState,
+  getGlRenderStateRuntime,
+  invalidateGlRenderStateCache,
+} from './glRenderState';
+import { makeGL } from './glTestHelper';
+
+function makeCanvas() {
+  const canvas = document.createElement('canvas');
+  canvas.width = 200;
+  canvas.height = 100;
+  const gl = makeGL();
+  canvas.getContext = vi.fn().mockReturnValue(gl) as typeof canvas.getContext;
+  return { canvas, gl };
+}
+
+describe('createGlRenderState', () => {
+  it('throws when Gl2 context is unavailable', () => {
+    const canvas = document.createElement('canvas');
+    canvas.getContext = vi.fn().mockReturnValue(null) as typeof canvas.getContext;
+    expect(() => createGlRenderState(canvas)).toThrow('Failed to get WebGL2 context.');
+  });
+
+  it('stores the canvas on the returned state', () => {
+    const { canvas } = makeCanvas();
+    const state = createGlRenderState(canvas);
+    expect(state.canvas).toBe(canvas);
+  });
+
+  it('stores the GL context on the returned state', () => {
+    const { canvas, gl } = makeCanvas();
+    const state = createGlRenderState(canvas);
+    expect(state.gl).toBe(gl);
+  });
+
+  it('initializes runtime currentBlendMode to null', () => {
+    const { canvas } = makeCanvas();
+    const state = createGlRenderState(canvas);
+    expect(getGlRenderStateRuntime(state).currentBlendMode).toBeNull();
+  });
+
+  it('initializes runtime currentProgram to null', () => {
+    const { canvas } = makeCanvas();
+    const state = createGlRenderState(canvas);
+    expect(getGlRenderStateRuntime(state).currentProgram).toBeNull();
+  });
+
+  it('initializes runtime currentTexture to null', () => {
+    const { canvas } = makeCanvas();
+    const state = createGlRenderState(canvas);
+    expect(getGlRenderStateRuntime(state).currentTexture).toBeNull();
+  });
+
+  it('enables blending during initialization', () => {
+    const { canvas, gl } = makeCanvas();
+    createGlRenderState(canvas);
+    expect(gl.enable).toHaveBeenCalledWith((gl as unknown as { BLEND: number }).BLEND);
+  });
+
+  it('disables depth testing during initialization', () => {
+    const { canvas, gl } = makeCanvas();
+    createGlRenderState(canvas);
+    expect(gl.disable).toHaveBeenCalledWith((gl as unknown as { DEPTH_TEST: number }).DEPTH_TEST);
+  });
+
+  it('sets the default premultiplied-alpha blend function', () => {
+    const { canvas, gl } = makeCanvas();
+    createGlRenderState(canvas);
+    const g = gl as unknown as { ONE: number; ONE_MINUS_SRC_ALPHA: number };
+    expect(gl.blendFunc).toHaveBeenCalledWith(g.ONE, g.ONE_MINUS_SRC_ALPHA);
+  });
+
+  it('requests an anti-aliased context by default', () => {
+    const { canvas } = makeCanvas();
+    createGlRenderState(canvas);
+    const attribs = (canvas.getContext as ReturnType<typeof vi.fn>).mock.calls[0][1] as WebGLContextAttributes;
+    expect(attribs.antialias).toBe(true);
+  });
+
+  it('disables the anti-aliased context when antialias is false', () => {
+    const { canvas } = makeCanvas();
+    createGlRenderState(canvas, { antialias: false });
+    const attribs = (canvas.getContext as ReturnType<typeof vi.fn>).mock.calls[0][1] as WebGLContextAttributes;
+    expect(attribs.antialias).toBe(false);
+  });
+
+  it('applies the backgroundColor option', () => {
+    const { canvas } = makeCanvas();
+    const state = createGlRenderState(canvas, { backgroundColor: 0xff0000ff });
+    expect(state.backgroundColor).toBe(0xff0000ff);
+  });
+
+  it('uses the provided pixelRatio option', () => {
+    const { canvas } = makeCanvas();
+    const state = createGlRenderState(canvas, { pixelRatio: 2 });
+    expect(state.pixelRatio).toBe(2);
+  });
+
+  it('defaults roundPixels to false', () => {
+    const { canvas } = makeCanvas();
+    const state = createGlRenderState(canvas);
+    expect(state.roundPixels).toBe(false);
+  });
+
+  it('applies the roundPixels option', () => {
+    const { canvas } = makeCanvas();
+    const state = createGlRenderState(canvas, { roundPixels: true });
+    expect(state.roundPixels).toBe(true);
+  });
+});
+
+describe('createGlRenderStateRuntime', () => {
+  it('returns a runtime carrying the base entity-runtime binding slot', () => {
+    const runtime = createGlRenderStateRuntime();
+    expect(runtime.binding).toBeNull();
+  });
+});
+
+describe('destroyGlRenderState', () => {
+  it('deletes the state-owned shader programs and buffers', () => {
+    const { canvas, gl } = makeCanvas();
+    const state = createGlRenderState(canvas);
+    const deleteProgram = vi.spyOn(gl, 'deleteProgram');
+    const deleteBuffer = vi.spyOn(gl, 'deleteBuffer');
+
+    destroyGlRenderState(state);
+
+    expect(deleteProgram).toHaveBeenCalled();
+    expect(deleteBuffer).toHaveBeenCalled();
+  });
+
+  it('is safe to call twice (Gl deletes are no-ops on already-deleted resources)', () => {
+    const { canvas } = makeCanvas();
+    const state = createGlRenderState(canvas);
+    destroyGlRenderState(state);
+    expect(() => destroyGlRenderState(state)).not.toThrow();
+  });
+});
+
+describe('getGlRenderStateRuntime', () => {
+  it('returns the runtime attached by createGlRenderState', () => {
+    const { canvas } = makeCanvas();
+    const state = createGlRenderState(canvas);
+    const runtime = getGlRenderStateRuntime(state);
+    expect(runtime).toBeDefined();
+    expect(runtime.defaultBitmapShader).toBeDefined();
+  });
+
+  it('resolves the same runtime object on repeated calls', () => {
+    const { canvas } = makeCanvas();
+    const state = createGlRenderState(canvas);
+    expect(getGlRenderStateRuntime(state)).toBe(getGlRenderStateRuntime(state));
+  });
+});
+
+describe('invalidateGlRenderStateCache', () => {
+  it('nulls the cached GL binding slots so the next draw re-binds from scratch', () => {
+    const { canvas } = makeCanvas();
+    const state = createGlRenderState(canvas);
+    const runtime = getGlRenderStateRuntime(state);
+
+    // Simulate a full frame of render-gl activity plus a sibling renderer (scene-gl) binding raw GL
+    // state the cache never observed: the cache now points at bindings that are no longer current.
+    runtime.currentProgram = {} as WebGLProgram;
+    runtime.currentTexture = {} as WebGLTexture;
+    runtime.currentFramebuffer = {} as WebGLFramebuffer;
+    runtime.currentBlendMode = BlendMode.Add;
+    runtime.currentMaskDepth = 3;
+    runtime.currentScissorRect = { x: 0, y: 0, width: 1, height: 1 };
+    runtime.renderTargetViewport = { width: 4, height: 4 };
+
+    invalidateGlRenderStateCache(state);
+
+    expect(runtime.currentProgram).toBeNull();
+    expect(runtime.currentTexture).toBeNull();
+    expect(runtime.currentFramebuffer).toBeNull();
+    expect(runtime.currentBlendMode).toBeNull();
+    expect(runtime.currentMaskDepth).toBe(0);
+    expect(runtime.currentScissorRect).toBeNull();
+    expect(runtime.renderTargetViewport).toBeNull();
+  });
+});

package/src/glRenderTarget.test.ts

@@ -0,0 +1,317 @@
+import { createDisplayObject } from '@flighthq/displayobject';
+import { createMatrix } from '@flighthq/geometry';
+import { getOrCreateRenderProxy2D } from '@flighthq/render';
+
+import { getGlRenderStateRuntime } from './glRenderState';
+import {
+  beginGlRenderTarget,
+  createGlRenderTarget,
+  destroyGlRenderTarget,
+  drawGlRenderTargetResult,
+  endGlRenderTarget,
+  resizeGlRenderTarget,
+  resolveGlRenderTarget,
+} from './glRenderTarget';
+import { createGlState } from './glTestHelper';
+
+function makeState() {
+  const { state: _state, gl: _gl } = createGlState();
+
+  const mockFramebuffer = {} as WebGLFramebuffer;
+  const mockTexture = {} as WebGLTexture;
+
+  const gl = Object.assign(_gl as unknown as Record<string, unknown>, {
+    FRAMEBUFFER: 36160,
+    COLOR_ATTACHMENT0: 36064,
+    createFramebuffer: vi.fn(() => mockFramebuffer),
+    bindFramebuffer: vi.fn(),
+    framebufferTexture2D: vi.fn(),
+    deleteFramebuffer: vi.fn(),
+    deleteTexture: vi.fn(),
+    createTexture: vi.fn(() => mockTexture),
+  }) as unknown as WebGL2RenderingContext;
+
+  const state = _state;
+  const runtime = getGlRenderStateRuntime(state);
+  runtime.currentFramebuffer = null;
+  runtime.renderTargetViewport = null;
+
+  return { state, gl };
+}
+
+describe('beginGlRenderTarget', () => {
+  it('binds the target framebuffer', () => {
+    const { state, gl } = makeState();
+    const target = createGlRenderTarget(state, { width: 64, height: 48 });
+    vi.clearAllMocks();
+
+    beginGlRenderTarget(state, target, createMatrix());
+
+    expect(vi.mocked(gl.bindFramebuffer)).toHaveBeenCalledWith(
+      (gl as unknown as { FRAMEBUFFER: number }).FRAMEBUFFER,
+      target.framebuffer,
+    );
+  });
+
+  it('sets renderTargetViewport to the target dimensions', () => {
+    const { state } = makeState();
+    const target = createGlRenderTarget(state, { width: 64, height: 48 });
+
+    beginGlRenderTarget(state, target, createMatrix());
+
+    expect(getGlRenderStateRuntime(state).renderTargetViewport).toEqual({ width: 64, height: 48 });
+  });
+
+  it('sets renderTransform2D to the provided transform', () => {
+    const { state } = makeState();
+    const target = createGlRenderTarget(state, { width: 64, height: 48 });
+    const renderTransform = createMatrix();
+    renderTransform.tx = 10;
+    renderTransform.ty = 20;
+
+    beginGlRenderTarget(state, target, renderTransform);
+
+    expect(state.renderTransform2D!.tx).toBe(10);
+    expect(state.renderTransform2D!.ty).toBe(20);
+  });
+
+  it('supports nested begin calls', () => {
+    const { state } = makeState();
+    const targetA = createGlRenderTarget(state, { width: 64, height: 48 });
+    const targetB = createGlRenderTarget(state, { width: 32, height: 32 });
+
+    beginGlRenderTarget(state, targetA, createMatrix());
+    beginGlRenderTarget(state, targetB, createMatrix());
+
+    expect(getGlRenderStateRuntime(state).renderTargetViewport).toEqual({ width: 32, height: 32 });
+
+    endGlRenderTarget(state);
+    expect(getGlRenderStateRuntime(state).renderTargetViewport).toEqual({ width: 64, height: 48 });
+  });
+});
+
+describe('createGlRenderTarget', () => {
+  it('returns a render target with the requested dimensions', () => {
+    const { state } = makeState();
+    const target = createGlRenderTarget(state, { width: 128, height: 64 });
+    expect(target.width).toBe(128);
+    expect(target.height).toBe(64);
+  });
+
+  it('enforces a minimum size of 1', () => {
+    const { state } = makeState();
+    const target = createGlRenderTarget(state, { width: 0, height: 0 });
+    expect(target.width).toBe(1);
+    expect(target.height).toBe(1);
+  });
+
+  it('ceils fractional dimensions', () => {
+    const { state } = makeState();
+    const target = createGlRenderTarget(state, { width: 10.3, height: 20.9 });
+    expect(target.width).toBe(11);
+    expect(target.height).toBe(21);
+  });
+
+  it('calls createFramebuffer and createTexture', () => {
+    const { state, gl } = makeState();
+    createGlRenderTarget(state, { width: 64, height: 64 });
+    expect(vi.mocked(gl.createFramebuffer)).toHaveBeenCalled();
+    expect(vi.mocked(gl.createTexture)).toHaveBeenCalled();
+  });
+
+  it('resets currentTexture to null after creation', () => {
+    const { state } = makeState();
+    const runtime = getGlRenderStateRuntime(state);
+    runtime.currentTexture = {} as WebGLTexture;
+    createGlRenderTarget(state, { width: 32, height: 32 });
+    expect(runtime.currentTexture).toBeNull();
+  });
+});
+
+describe('destroyGlRenderTarget', () => {
+  it('deletes the framebuffer and texture', () => {
+    const { state, gl } = makeState();
+    const target = createGlRenderTarget(state, { width: 32, height: 32 });
+    const { framebuffer, texture } = target;
+
+    destroyGlRenderTarget(state, target);
+
+    expect(vi.mocked(gl.deleteFramebuffer)).toHaveBeenCalledWith(framebuffer);
+    expect(vi.mocked(gl.deleteTexture)).toHaveBeenCalledWith(texture);
+  });
+});
+
+describe('drawGlRenderTargetResult', () => {
+  it('is a no-op when target dimensions are zero', () => {
+    const { state, gl } = makeState();
+    const node = getOrCreateRenderProxy2D(state, createDisplayObject());
+    const target = createGlRenderTarget(state, { width: 1, height: 1 });
+    target.width = 0;
+    vi.clearAllMocks();
+
+    drawGlRenderTargetResult(state, node, target, createMatrix());
+
+    expect(vi.mocked(gl.bindTexture)).not.toHaveBeenCalled();
+  });
+
+  it('composites a valid target without throwing', () => {
+    const { state } = makeState();
+    const node = getOrCreateRenderProxy2D(state, createDisplayObject());
+    node.alpha = 1;
+    const target = createGlRenderTarget(state, { width: 64, height: 48 });
+
+    expect(() => drawGlRenderTargetResult(state, node, target, createMatrix())).not.toThrow();
+  });
+
+  it('binds the target texture', () => {
+    const { state, gl } = makeState();
+    const node = getOrCreateRenderProxy2D(state, createDisplayObject());
+    const target = createGlRenderTarget(state, { width: 64, height: 48 });
+    vi.clearAllMocks();
+
+    drawGlRenderTargetResult(state, node, target, createMatrix());
+
+    expect(vi.mocked(gl.bindTexture)).toHaveBeenCalledWith(
+      (gl as unknown as { TEXTURE_2D: number }).TEXTURE_2D,
+      target.texture,
+    );
+  });
+});
+
+describe('endGlRenderTarget', () => {
+  it('restores the previous framebuffer', () => {
+    const { state, gl } = makeState();
+    const target = createGlRenderTarget(state, { width: 64, height: 48 });
+
+    beginGlRenderTarget(state, target, createMatrix());
+    vi.clearAllMocks();
+    endGlRenderTarget(state);
+
+    expect(vi.mocked(gl.bindFramebuffer)).toHaveBeenCalledWith(
+      (gl as unknown as { FRAMEBUFFER: number }).FRAMEBUFFER,
+      null,
+    );
+  });
+
+  it('restores renderTargetViewport to null', () => {
+    const { state } = makeState();
+    const target = createGlRenderTarget(state, { width: 64, height: 48 });
+
+    beginGlRenderTarget(state, target, createMatrix());
+    endGlRenderTarget(state);
+
+    expect(getGlRenderStateRuntime(state).renderTargetViewport).toBeNull();
+  });
+
+  it('restores the original renderTransform2D', () => {
+    const { state } = makeState();
+    const originalTransform = state.renderTransform2D;
+    const target = createGlRenderTarget(state, { width: 64, height: 48 });
+    const renderTransform = createMatrix();
+    renderTransform.tx = 99;
+
+    beginGlRenderTarget(state, target, renderTransform);
+    endGlRenderTarget(state);
+
+    expect(state.renderTransform2D).toBe(originalTransform);
+  });
+
+  it('without a matching begin is a no-op', () => {
+    const { state, gl } = makeState();
+    expect(() => endGlRenderTarget(state)).not.toThrow();
+    expect(vi.mocked(gl.bindFramebuffer)).not.toHaveBeenCalled();
+  });
+});
+
+describe('resizeGlRenderTarget', () => {
+  it('updates the target dimensions', () => {
+    const { state } = makeState();
+    const target = createGlRenderTarget(state, { width: 64, height: 64 });
+
+    resizeGlRenderTarget(state, target, 256, 128);
+
+    expect(target.width).toBe(256);
+    expect(target.height).toBe(128);
+  });
+
+  it('enforces a minimum size of 1', () => {
+    const { state } = makeState();
+    const target = createGlRenderTarget(state, { width: 64, height: 64 });
+
+    resizeGlRenderTarget(state, target, 0, 0);
+
+    expect(target.width).toBe(1);
+    expect(target.height).toBe(1);
+  });
+
+  it('reallocates the texture storage', () => {
+    const { state, gl } = makeState();
+    const target = createGlRenderTarget(state, { width: 64, height: 64 });
+    vi.clearAllMocks();
+
+    resizeGlRenderTarget(state, target, 128, 128);
+
+    expect(vi.mocked(gl.bindTexture)).toHaveBeenCalledWith(
+      (gl as unknown as { TEXTURE_2D: number }).TEXTURE_2D,
+      target.texture,
+    );
+    expect(vi.mocked(gl.texImage2D)).toHaveBeenCalled();
+  });
+});
+
+describe('resolveGlRenderTarget', () => {
+  it('is a no-op for a single-sample target', () => {
+    const { state, gl } = makeState();
+    const target = createGlRenderTarget(state, { width: 64, height: 48 });
+    expect(target.sampleCount).toBe(1);
+    vi.clearAllMocks();
+
+    resolveGlRenderTarget(state, target);
+
+    expect(vi.mocked(gl.bindFramebuffer)).not.toHaveBeenCalled();
+  });
+
+  it('is a no-op when the target has no resolve framebuffer', () => {
+    const { state, gl } = makeState();
+    const target = createGlRenderTarget(state, { width: 64, height: 48 });
+    // Force the MSAA sample-count gate open but leave resolveFramebuffer null.
+    target.sampleCount = 4;
+    target.resolveFramebuffer = null;
+    vi.clearAllMocks();
+
+    resolveGlRenderTarget(state, target);
+
+    expect(vi.mocked(gl.bindFramebuffer)).not.toHaveBeenCalled();
+  });
+
+  it('blits each color attachment and flushes for an MSAA target', () => {
+    const { state, gl } = makeState();
+    const target = createGlRenderTarget(state, { width: 64, height: 48 });
+    target.sampleCount = 4;
+    target.resolveFramebuffer = {} as WebGLFramebuffer;
+    // Two color attachments resolve as two separate blits.
+    target.textures = [{} as WebGLTexture, {} as WebGLTexture];
+
+    const blit = vi.fn();
+    const readBuffer = vi.fn();
+    const drawBuffers = vi.fn();
+    const flush = vi.fn();
+    Object.assign(gl as unknown as Record<string, unknown>, {
+      READ_FRAMEBUFFER: 36008,
+      DRAW_FRAMEBUFFER: 36009,
+      COLOR_BUFFER_BIT: 16384,
+      NEAREST: 9728,
+      NONE: 0,
+      blitFramebuffer: blit,
+      readBuffer,
+      drawBuffers,
+      flush,
+    });
+
+    resolveGlRenderTarget(state, target);
+
+    expect(blit).toHaveBeenCalledTimes(2);
+    expect(readBuffer).toHaveBeenCalledTimes(2);
+    expect(flush).toHaveBeenCalledTimes(1);
+  });
+});

package/src/glRenderTargetPool.test.ts

@@ -0,0 +1,97 @@
+import {
+  acquireGlRenderTarget,
+  createGlRenderTargetPool,
+  destroyGlRenderTargetPool,
+  releaseGlRenderTarget,
+} from './glRenderTargetPool';
+import { createGlState } from './glTestHelper';
+
+describe('acquireGlRenderTarget', () => {
+  it('allocates a new target when the pool is empty', () => {
+    const { state } = createGlState();
+    const pool = createGlRenderTargetPool();
+    const target = acquireGlRenderTarget(state, pool, { width: 64, height: 48 });
+    expect(target.width).toBe(64);
+    expect(target.height).toBe(48);
+    expect(pool.free.length).toBe(0);
+  });
+
+  it('reuses a matching released target instead of allocating', () => {
+    const { state } = createGlState();
+    const pool = createGlRenderTargetPool();
+    const first = acquireGlRenderTarget(state, pool, { width: 64, height: 48 });
+    releaseGlRenderTarget(pool, first);
+
+    const reused = acquireGlRenderTarget(state, pool, { width: 64, height: 48 });
+    expect(reused).toBe(first);
+    expect(pool.free.length).toBe(0);
+  });
+
+  it('allocates a new target when the free target has different dimensions', () => {
+    const { state } = createGlState();
+    const pool = createGlRenderTargetPool();
+    const first = acquireGlRenderTarget(state, pool, { width: 64, height: 48 });
+    releaseGlRenderTarget(pool, first);
+
+    const other = acquireGlRenderTarget(state, pool, { width: 128, height: 48 });
+    expect(other).not.toBe(first);
+    // The mismatched target stays parked in the free list.
+    expect(pool.free).toContain(first);
+  });
+
+  it('matches the ceiled, clamped descriptor dimensions', () => {
+    const { state } = createGlState();
+    const pool = createGlRenderTargetPool();
+    const first = acquireGlRenderTarget(state, pool, { width: 10.2, height: 0 });
+    releaseGlRenderTarget(pool, first);
+
+    // 10.2 -> 11, 0 -> 1; an equivalent descriptor must hit the same parked target.
+    const reused = acquireGlRenderTarget(state, pool, { width: 10.9, height: 0.4 });
+    expect(reused).toBe(first);
+  });
+});
+
+describe('createGlRenderTargetPool', () => {
+  it('returns a pool with an empty free list', () => {
+    const pool = createGlRenderTargetPool();
+    expect(pool.free).toEqual([]);
+  });
+});
+
+describe('destroyGlRenderTargetPool', () => {
+  it('destroys every parked target and empties the free list', () => {
+    const { state, gl } = createGlState();
+    const pool = createGlRenderTargetPool();
+    const a = acquireGlRenderTarget(state, pool, { width: 32, height: 32 });
+    const b = acquireGlRenderTarget(state, pool, { width: 16, height: 16 });
+    releaseGlRenderTarget(pool, a);
+    releaseGlRenderTarget(pool, b);
+
+    const deleteSpy = vi.spyOn(gl, 'deleteFramebuffer');
+    destroyGlRenderTargetPool(state, pool);
+
+    expect(deleteSpy).toHaveBeenCalledWith(a.framebuffer);
+    expect(deleteSpy).toHaveBeenCalledWith(b.framebuffer);
+    expect(pool.free.length).toBe(0);
+  });
+
+  it('is a no-op on an empty pool', () => {
+    const { state } = createGlState();
+    const pool = createGlRenderTargetPool();
+    expect(() => destroyGlRenderTargetPool(state, pool)).not.toThrow();
+  });
+});
+
+describe('releaseGlRenderTarget', () => {
+  it('returns the target to the free list without destroying it', () => {
+    const { state, gl } = createGlState();
+    const pool = createGlRenderTargetPool();
+    const target = acquireGlRenderTarget(state, pool, { width: 64, height: 64 });
+
+    const deleteSpy = vi.spyOn(gl, 'deleteFramebuffer');
+    releaseGlRenderTarget(pool, target);
+
+    expect(pool.free).toContain(target);
+    expect(deleteSpy).not.toHaveBeenCalled();
+  });
+});