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

package/src/glRenderPass.test.ts

@@ -2,16 +2,30 @@ import { allocateEntity, finishEntity } from '@flighthq/entity/contract';
 import { createMatrix } from '@flighthq/geometry/contract';
 import { getOrCreateRenderProxy2D } from '@flighthq/render/contract';
 import { createDisplayObject } from '@flighthq/scene2d/contract';
-import type { GlContext, GlRenderTarget, Viewport } from '@flighthq/types/contract';
-
-import { beginGlRenderPass, endGlRenderPass, setGlRenderTransform2D } from './glRenderPass';
-import { createGlOffscreenRenderState } from './glRenderState';
-import { getGlRenderStateRuntime } from './glRenderState';
+import type {
+  GlContext,
+  GlRenderPass,
+  GlRenderTarget,
+  GlTextureRenderTarget,
+  Viewport,
+} from '@flighthq/types/contract';
+
+import { clearGlRenderTarget, clearGlRenderTargetAttachments, fillGlRect } from './glFullscreenPass';
+import {
+  acquireGlRenderPassHandle,
+  beginGlRenderPass,
+  endGlRenderPass,
+  getGlCurrentRenderPass,
+  releaseGlRenderPassHandle,
+  setGlRenderTransform2D,
+} from './glRenderPass';
+import { createGlRenderState, getGlRenderStateRuntime } from './glRenderState';
+import { drawGlTextureRenderTargetResult } from './glRenderTarget';
 import { createGlState } from './glTestHelper';
 
-function makeTarget(overrides?: Partial<GlRenderTarget>): GlRenderTarget {
+function makeTarget(overrides?: Partial<GlTextureRenderTarget>): GlTextureRenderTarget {
   const texture = { id: 'c0' } as unknown as WebGLTexture;
-  const out = allocateEntity<GlRenderTarget>();
+  const out = allocateEntity<GlTextureRenderTarget>();
   out.requestedAxes = {
     width: 32,
     height: 16,
@@ -29,8 +43,6 @@ function makeTarget(overrides?: Partial<GlRenderTarget>): GlRenderTarget {
   out.colorFormats = ['rgba8'];
   out.depth = 'depth-stencil';
   out.colorSpace = 'srgb';
-  out.clearColors = [];
-  out.clearDepth = 1;
   out.sampleCount = 1;
   out.framebuffer = {} as WebGLFramebuffer;
   out.resolveFramebuffer = null;
@@ -43,57 +55,93 @@ function makeTarget(overrides?: Partial<GlRenderTarget>): GlRenderTarget {
   return finishEntity(out);
 }
 
+describe('acquireGlRenderPassHandle', () => {
+  it('returns a pass with the given gl, state, and target', () => {
+    const { state, gl } = createGlState();
+    const target = makeTarget();
+
+    const handle = acquireGlRenderPassHandle(gl, state, target);
+
+    expect(handle.gl).toBe(gl);
+    expect(handle.state).toBe(state);
+    expect(handle.target).toBe(target);
+  });
+
+  it('reuses a previously released handle from the same context', () => {
+    const { state, gl } = createGlState();
+    const target = makeTarget();
+
+    const first = acquireGlRenderPassHandle(gl, state, target);
+    releaseGlRenderPassHandle(gl, first);
+    const second = acquireGlRenderPassHandle(gl, state, target);
+
+    expect(second).toBe(first);
+  });
+});
+
 describe('beginGlRenderPass', () => {
-  it('clears every color attachment and depth by default', () => {
+  it('clears color and depth when clear descriptor specifies both', () => {
     const { state, gl } = createGlState();
     const clearColor = vi.spyOn(gl, 'clearBufferfv');
     const clearDepth = vi.spyOn(gl, 'clearBufferfi');
 
-    beginGlRenderPass(state, makeTarget());
+    beginGlRenderPass(state, makeTarget(), { color: [0, 0, 0, 0], depth: 1.0, stencil: 0 });
 
     expect(clearColor).toHaveBeenCalledWith(gl.COLOR, 0, expect.anything());
     expect(clearDepth).toHaveBeenCalledWith(gl.DEPTH_STENCIL, 0, 1, 0);
   });
 
-  it('spares color when preserveColor is true, still clears depth', () => {
+  it('preserves everything when no clear descriptor is given', () => {
     const { state, gl } = createGlState();
     const clearColor = vi.spyOn(gl, 'clearBufferfv');
     const clearDepth = vi.spyOn(gl, 'clearBufferfi');
 
-    beginGlRenderPass(state, makeTarget(), { preserveColor: true });
+    beginGlRenderPass(state, makeTarget());
+
+    expect(clearColor).not.toHaveBeenCalled();
+    expect(clearDepth).not.toHaveBeenCalled();
+  });
+
+  it('preserves color when color is omitted from clear descriptor', () => {
+    const { state, gl } = createGlState();
+    const clearColor = vi.spyOn(gl, 'clearBufferfv');
+    const clearDepth = vi.spyOn(gl, 'clearBufferfi');
+
+    beginGlRenderPass(state, makeTarget(), { depth: 1.0, stencil: 0 });
 
     expect(clearColor).not.toHaveBeenCalled();
     expect(clearDepth).toHaveBeenCalled();
   });
 
-  it('spares depth when preserveDepth is true, still clears color', () => {
+  it('preserves depth when depth is omitted from clear descriptor', () => {
     const { state, gl } = createGlState();
     const clearColor = vi.spyOn(gl, 'clearBufferfv');
     const clearDepth = vi.spyOn(gl, 'clearBufferfi');
 
-    beginGlRenderPass(state, makeTarget(), { preserveDepth: true });
+    beginGlRenderPass(state, makeTarget(), { color: [0, 0, 0, 0] });
 
     expect(clearColor).toHaveBeenCalled();
     expect(clearDepth).not.toHaveBeenCalled();
   });
 
-  it('preserves per attachment location when preserveColor is an array', () => {
+  it('clears per-attachment with colors array, skipping undefined entries', () => {
     const { state, gl } = createGlState();
     const c0 = { id: 'c0' } as unknown as WebGLTexture;
     const c1 = { id: 'c1' } as unknown as WebGLTexture;
     const clearColor = vi.spyOn(gl, 'clearBufferfv');
 
-    // Keep location 0, clear location 1 — the MRT / G-buffer path.
-    beginGlRenderPass(state, makeTarget({ textures: [c0, c1], texture: c0 }), { preserveColor: [true, false] });
+    beginGlRenderPass(state, makeTarget({ textures: [c0, c1], texture: c0 }), {
+      colors: [undefined, [0, 0, 0, 0]],
+    });
 
     expect(clearColor.mock.calls.map((c) => c[1])).toEqual([1]);
   });
 
-  it("uses the target's packed clearColor over the background color when present", () => {
-    const { state, gl } = createGlState({ backgroundColorRgba: [0, 0, 0, 1] });
+  it('writes float RGBA values directly to clearBufferfv', () => {
+    const { state, gl } = createGlState();
     const clearColor = vi.spyOn(gl, 'clearBufferfv');
 
-    beginGlRenderPass(state, makeTarget({ clearColors: [0xff0000ff] })); // opaque red
+    beginGlRenderPass(state, makeTarget(), { color: [1, 0, 0, 1] });
 
     const rgba = clearColor.mock.calls[0][2] as Float32Array;
     expect(rgba[0]).toBeCloseTo(1);
@@ -117,7 +165,7 @@ describe('beginGlRenderPass', () => {
     const target = makeTarget({ width: 100, height: 80 });
     const viewport = makeViewport(10, 20, 30, 40);
 
-    beginGlRenderPass(state, target, undefined, viewport);
+    beginGlRenderPass(state, target, { color: [0, 0, 0, 0] }, viewport);
 
     expect(gl.viewport).toHaveBeenLastCalledWith(10, 20, 30, 40);
     expect(gl.enable).toHaveBeenCalledWith(gl.SCISSOR_TEST);
@@ -171,10 +219,10 @@ describe('beginGlRenderPass', () => {
     const runtime = getGlRenderStateRuntime(state);
 
     beginGlRenderPass(state, outer);
-    beginGlRenderPass(state, inner);
+    const innerPass = beginGlRenderPass(state, inner);
     expect(runtime.currentRenderTarget).toBe(inner);
 
-    endGlRenderPass(state);
+    endGlRenderPass(innerPass);
     expect(runtime.currentRenderTarget).toBe(outer);
     expect(runtime.renderTargetViewport).toEqual({ height: 48, width: 64, x: 0, y: 0 });
   });
@@ -188,14 +236,14 @@ describe('beginGlRenderPass', () => {
     const outer = makeTarget({ width: 64, height: 48 });
     const inner = makeTarget({ width: 32, height: 24 });
 
-    beginGlRenderPass(outerState, outer);
-    beginGlRenderPass(innerState, inner);
-    endGlRenderPass(innerState);
+    const outerPass = beginGlRenderPass(outerState, outer);
+    const innerPass = beginGlRenderPass(innerState, inner);
+    endGlRenderPass(innerPass);
 
     expect(vi.mocked(gl.bindFramebuffer).mock.calls.at(-1)?.[1]).toBe(outer.framebuffer);
     expect(getGlRenderStateRuntime(outerState).currentRenderTarget).toBe(outer);
     expect(getGlRenderStateRuntime(innerState).currentRenderTarget).toBeNull();
-    endGlRenderPass(outerState);
+    endGlRenderPass(outerPass);
   });
 
   it('rejects a same-target contour pass across render states sharing one context', () => {
@@ -206,7 +254,7 @@ describe('beginGlRenderPass', () => {
     (innerState as { gl: GlContext }).gl = gl;
     const target = makeTarget({ width: 64, height: 48 });
 
-    beginGlRenderPass(outerState, target);
+    const outerPass = beginGlRenderPass(outerState, target);
     getGlRenderStateRuntime(outerState).currentMaskDepth = 1;
 
     expect(() => beginGlRenderPass(innerState, target)).toThrow(
@@ -214,7 +262,7 @@ describe('beginGlRenderPass', () => {
     );
     expect(getGlRenderStateRuntime(outerState).currentRenderTarget).toBe(target);
     expect(getGlRenderStateRuntime(innerState).currentRenderTarget).toBeNull();
-    endGlRenderPass(outerState);
+    endGlRenderPass(outerPass);
   });
 });
 
@@ -224,8 +272,8 @@ describe('endGlRenderPass', () => {
     const target = makeTarget();
     const bindFramebuffer = vi.spyOn(gl, 'bindFramebuffer');
 
-    beginGlRenderPass(state, target);
-    endGlRenderPass(state);
+    const pass = beginGlRenderPass(state, target);
+    endGlRenderPass(pass);
 
     // The pass began with the canvas default bound (null); ending restores it.
     expect(bindFramebuffer.mock.calls.at(-1)?.[1]).toBe(null);
@@ -235,8 +283,8 @@ describe('endGlRenderPass', () => {
     const { state } = createGlState();
     const target = makeTarget();
 
-    beginGlRenderPass(state, target);
-    endGlRenderPass(state);
+    const pass = beginGlRenderPass(state, target);
+    endGlRenderPass(pass);
 
     expect(getGlRenderStateRuntime(state).renderTargetViewport).toBeNull();
   });
@@ -246,8 +294,8 @@ describe('endGlRenderPass', () => {
     const target = makeTarget({ width: 100, height: 80 });
 
     beginGlRenderPass(state, target, undefined, makeViewport(10, 20, 30, 40));
-    beginGlRenderPass(state, target, undefined, makeViewport(15, 25, 10, 10));
-    endGlRenderPass(state);
+    const innerPass = beginGlRenderPass(state, target, undefined, makeViewport(15, 25, 10, 10));
+    endGlRenderPass(innerPass);
 
     expect(gl.viewport).toHaveBeenLastCalledWith(10, 20, 30, 40);
     expect(gl.scissor).toHaveBeenLastCalledWith(10, 20, 30, 40);
@@ -265,12 +313,12 @@ describe('endGlRenderPass', () => {
     runtime.scissorStack!.push(outerClip);
     runtime.clipForms.push('rect');
 
-    beginGlRenderPass(state, makeTarget({ width: 100, height: 80 }));
+    const innerPass = beginGlRenderPass(state, makeTarget({ width: 100, height: 80 }));
     expect(runtime.clipForms).toEqual([]);
     expect(runtime.currentMaskDepth).toBe(0);
 
     // An inner renderGlScene2D.finalize now has no enclosing entry to drain.
-    endGlRenderPass(state);
+    endGlRenderPass(innerPass);
     expect(runtime.currentScissorRect).toBe(outerClip);
     expect(runtime.scissorStack).toEqual([{ height: 40, width: 30, x: 10, y: 20 }, outerClip]);
     expect(runtime.clipForms).toEqual(['rect']);
@@ -284,11 +332,11 @@ describe('endGlRenderPass', () => {
     });
     vi.mocked(gl.getParameter).mockImplementation((parameter) => (parameter === gl.DEPTH_WRITEMASK ? depthMask : null));
 
-    beginGlRenderPass(state, makeTarget(), { preserveDepth: true });
+    beginGlRenderPass(state, makeTarget(), { color: [0, 0, 0, 0] });
     gl.depthMask(false);
-    beginGlRenderPass(state, makeTarget());
+    const innerPass = beginGlRenderPass(state, makeTarget(), { depth: 1.0, stencil: 0 });
     expect(depthMask).toBe(true);
-    endGlRenderPass(state);
+    endGlRenderPass(innerPass);
 
     expect(depthMask).toBe(false);
   });
@@ -299,12 +347,12 @@ describe('endGlRenderPass', () => {
     runtime.clipForms = ['contour'];
     runtime.currentMaskDepth = 1;
 
-    beginGlRenderPass(state, makeTarget());
+    const pass = beginGlRenderPass(state, makeTarget());
     expect(runtime.clipForms).toEqual([]);
     expect(runtime.currentMaskDepth).toBe(0);
     expect(gl.disable).toHaveBeenCalledWith(gl.STENCIL_TEST);
 
-    endGlRenderPass(state);
+    endGlRenderPass(pass);
     expect(runtime.clipForms).toEqual(['contour']);
     expect(runtime.currentMaskDepth).toBe(1);
     expect(gl.enable).toHaveBeenCalledWith(gl.STENCIL_TEST);
@@ -316,8 +364,8 @@ describe('endGlRenderPass', () => {
   it('disables scissor when the outer partial pass returns to the canvas', () => {
     const { state, gl } = createGlState();
 
-    beginGlRenderPass(state, makeTarget(), undefined, makeViewport(1, 2, 10, 8));
-    endGlRenderPass(state);
+    const pass = beginGlRenderPass(state, makeTarget(), undefined, makeViewport(1, 2, 10, 8));
+    endGlRenderPass(pass);
 
     expect(gl.disable).toHaveBeenCalledWith(gl.SCISSOR_TEST);
     expect(getGlRenderStateRuntime(state).currentScissorRect).toBeNull();
@@ -326,7 +374,8 @@ describe('endGlRenderPass', () => {
 
   it('throws when there is no matching begin', () => {
     const { state } = createGlState();
-    expect(() => endGlRenderPass(state)).toThrow('without a matching beginGlRenderPass');
+    const mockPass = { gl: state.gl, state, target: {} as GlRenderTarget } as GlRenderPass;
+    expect(() => endGlRenderPass(mockPass)).toThrow('without a matching beginGlRenderPass');
   });
 });
 
@@ -334,6 +383,34 @@ function makeViewport(x: number, y: number, width: number, height: number): View
   return { devicePixelRatio: 1, height, width, x, y } as Viewport;
 }
 
+describe('getGlCurrentRenderPass', () => {
+  it('returns null when no pass is active', () => {
+    const { state } = createGlState();
+
+    expect(getGlCurrentRenderPass(state)).toBeNull();
+  });
+
+  it('returns the active pass during a render pass', () => {
+    const { state } = createGlState();
+    const target = makeTarget();
+
+    const pass = beginGlRenderPass(state, target);
+
+    expect(getGlCurrentRenderPass(state)).toBe(pass);
+    endGlRenderPass(pass);
+  });
+
+  it('returns null after the pass ends', () => {
+    const { state } = createGlState();
+    const target = makeTarget();
+
+    const pass = beginGlRenderPass(state, target);
+    endGlRenderPass(pass);
+
+    expect(getGlCurrentRenderPass(state)).toBeNull();
+  });
+});
+
 describe('offscreen 2D projection basis', () => {
   // Pins the property a downstream report claimed was broken: that an offscreen state's 2D pass projects
   // into the BOUND TARGET's dimensions rather than the shared context's drawing buffer. Reading the
@@ -341,26 +418,26 @@ describe('offscreen 2D projection basis', () => {
   // looking plausible, so this asserts the pass actually populates its explicit viewport.
   it('derives the viewport from the target, not from the shared drawing buffer', () => {
     const { state } = createGlState();
-    const offscreen = createGlOffscreenRenderState(state.contextState, state.pipeline);
+    const offscreen = createGlRenderState(state.gl, state.pipeline);
     const runtime = getGlRenderStateRuntime(offscreen);
     expect(offscreen.gl).toBe(state.gl);
     expect([state.gl.drawingBufferWidth, state.gl.drawingBufferHeight]).toEqual([200, 100]);
 
-    beginGlRenderPass(offscreen, makeTarget({ width: 64, height: 32 }));
+    const pass = beginGlRenderPass(offscreen, makeTarget({ width: 64, height: 32 }));
 
     expect(runtime.renderTargetViewport).toEqual({ height: 32, width: 64, x: 0, y: 0 });
-    endGlRenderPass(offscreen);
+    endGlRenderPass(pass);
   });
 
   it('restores the previous basis when the pass ends', () => {
     // Guards the guard: a pass that set the viewport and never restored it would satisfy the test above
     // while leaving every later screen draw projecting into the offscreen target's dimensions.
     const { state } = createGlState();
-    const offscreen = createGlOffscreenRenderState(state.contextState, state.pipeline);
+    const offscreen = createGlRenderState(state.gl, state.pipeline);
     const runtime = getGlRenderStateRuntime(offscreen);
 
-    beginGlRenderPass(offscreen, makeTarget({ width: 64, height: 32 }));
-    endGlRenderPass(offscreen);
+    const pass = beginGlRenderPass(offscreen, makeTarget({ width: 64, height: 32 }));
+    endGlRenderPass(pass);
 
     expect(runtime.renderTargetViewport).toBe(null);
   });
@@ -370,7 +447,7 @@ describe('offscreen 2D projection basis', () => {
     // compensation. Identity is the correct neutral for both, and the two constructors agreeing is what
     // makes an offscreen pass behave like a screen pass until a caller deliberately changes it.
     const { state } = createGlState();
-    const offscreen = createGlOffscreenRenderState(state.contextState, state.pipeline);
+    const offscreen = createGlRenderState(state.gl, state.pipeline);
 
     // Field-by-field, not toEqual: a Matrix is entity-backed and carries runtime identity beyond its
     // public fields, so two structurally identical matrices are not deeply equal.
@@ -381,6 +458,30 @@ describe('offscreen 2D projection basis', () => {
   });
 });
 
+describe('releaseGlRenderPassHandle', () => {
+  it('returns a handle to the pool for reuse', () => {
+    const { state, gl } = createGlState();
+    const target = makeTarget();
+
+    const handle = acquireGlRenderPassHandle(gl, state, target);
+    releaseGlRenderPassHandle(gl, handle);
+    const reused = acquireGlRenderPassHandle(gl, state, target);
+
+    expect(reused).toBe(handle);
+  });
+
+  it('creates the pool lazily on first release', () => {
+    const { state, gl } = createGlState();
+    const target = makeTarget();
+    const handle = acquireGlRenderPassHandle(gl, state, target);
+
+    releaseGlRenderPassHandle(gl, handle);
+
+    const second = acquireGlRenderPassHandle(gl, state, target);
+    expect(second).toBe(handle);
+  });
+});
+
 describe('setGlRenderTransform2D', () => {
   it('installs a copy of the transform as the 2D root device transform', () => {
     const { state } = createGlState();
@@ -401,10 +502,10 @@ describe('setGlRenderTransform2D', () => {
     const cacheTransform = createMatrix();
     cacheTransform.tx = 99;
 
-    beginGlRenderPass(state, target, { preserveColor: true });
+    const pass = beginGlRenderPass(state, target, { depth: 1.0, stencil: 0 });
     setGlRenderTransform2D(state, cacheTransform);
     expect(state.renderTransform2D?.tx).toBe(99);
-    endGlRenderPass(state);
+    endGlRenderPass(pass);
 
     expect(state.renderTransform2D).toBe(original);
   });
@@ -419,3 +520,75 @@ describe('setGlRenderTransform2D', () => {
     expect(proxy.lastLocalTransformId).toBe(-1);
   });
 });
+
+describe('zero-compat ratchet', () => {
+  it('clearGlRenderTarget takes (target, clear) — no state parameter', () => {
+    expect(clearGlRenderTarget).toHaveLength(2);
+  });
+
+  it('clearGlRenderTargetAttachments takes (target, clear) — no state parameter', () => {
+    expect(clearGlRenderTargetAttachments).toHaveLength(2);
+  });
+
+  it('fillGlRect first parameter is a pass, not state', () => {
+    const { state } = createGlState();
+    const target = makeTarget();
+    const pass = beginGlRenderPass(state, target);
+    expect(pass.gl).toBe(state.gl);
+    expect(pass.state).toBe(state);
+    expect(pass.target).toBe(target);
+    endGlRenderPass(pass);
+  });
+
+  it('drawGlTextureRenderTargetResult first parameter is a pass', () => {
+    expect(drawGlTextureRenderTargetResult).toHaveLength(4);
+  });
+
+  it('beginGlRenderPass returns a GlRenderPass with gl, state, and target', () => {
+    const { state } = createGlState();
+    const target = makeTarget();
+    const pass = beginGlRenderPass(state, target);
+    expect(pass).toHaveProperty('gl');
+    expect(pass).toHaveProperty('state');
+    expect(pass).toHaveProperty('target');
+    expect(pass.gl).toBe(state.gl);
+    expect(pass.state).toBe(state);
+    expect(pass.target).toBe(target);
+    endGlRenderPass(pass);
+  });
+
+  it('endGlRenderPass accepts GlRenderPass only', () => {
+    expect(endGlRenderPass).toHaveLength(1);
+  });
+
+  it('getGlCurrentRenderPass tracks the active pass on the state', () => {
+    const { state } = createGlState();
+    const target = makeTarget();
+    expect(getGlCurrentRenderPass(state)).toBeNull();
+    const pass = beginGlRenderPass(state, target);
+    expect(getGlCurrentRenderPass(state)).toBe(pass);
+    endGlRenderPass(pass);
+    expect(getGlCurrentRenderPass(state)).toBeNull();
+  });
+
+  it('pooled handles are reused across begin/end cycles', () => {
+    const { state, gl } = createGlState();
+    const target = makeTarget();
+    const first = beginGlRenderPass(state, target);
+    endGlRenderPass(first);
+    const second = beginGlRenderPass(state, target);
+    expect(second).toBe(first);
+    endGlRenderPass(second);
+  });
+
+  it('screen and offscreen states share the context pass pool', () => {
+    const { state, gl } = createGlState();
+    const offscreen = createGlRenderState(state.gl, state.pipeline);
+    const target = makeTarget();
+    const screenPass = beginGlRenderPass(state, target);
+    endGlRenderPass(screenPass);
+    const offscreenPass = beginGlRenderPass(offscreen, target);
+    expect(offscreenPass).toBe(screenPass);
+    endGlRenderPass(offscreenPass);
+  });
+});