@flighthq/render-gl 0.3.0 → 0.3.1-next.1050.9114695

package/src/glRenderStateBracket.test.ts

@@ -23,6 +23,9 @@ type TestGlState = {
   blendSrcRgb: number;
   cullFace: boolean;
   cullFaceMode: number;
+  frontFace: number;
+  stencilTest: boolean;
+  stencilWriteMask: number;
   currentRenderTarget: GlRenderTarget | null;
   depthFunc: number;
   depthMask: boolean;
@@ -58,6 +61,9 @@ const OUTER_STATE: TestGlState = {
   blendSrcRgb: 1,
   cullFace: false,
   cullFaceMode: 0x0405,
+  frontFace: 0x0900, // GL_CW — a host that does not use Flight's default
+  stencilTest: true, // enabled on purpose: a fixture that starts disabled cannot tell 'restored' from 'left off'
+  stencilWriteMask: 0x0f,
   currentRenderTarget: { name: 'outer-target' } as unknown as GlRenderTarget,
   depthFunc: 0x0203,
   depthMask: false,
@@ -86,6 +92,9 @@ const MIDDLE_STATE: TestGlState = {
   blendSrcRgb: 1,
   cullFace: true,
   cullFaceMode: 0x0404,
+  frontFace: 0x0901, // GL_CCW
+  stencilTest: false,
+  stencilWriteMask: 0xff,
   currentRenderTarget: { name: 'middle-target' } as unknown as GlRenderTarget,
   depthFunc: 0x0201,
   depthMask: true,
@@ -136,6 +145,57 @@ describe('popGlRenderState', () => {
     expectTestGlState(fixture, OUTER_STATE);
   });
 
+  it('restores a two-sided stencil configuration without collapsing the back face onto the front', () => {
+    const fixture = createStatefulGl();
+    const gl = fixture.gl;
+    applyTestGlState(fixture, OUTER_STATE);
+    // A host driving two-sided stencil — the case stencilOpSeparate exists for. Every back-face value
+    // differs from its front counterpart, so a restore that writes both faces from the front's saved
+    // values cannot pass by coincidence: it would report the front correct and the back overwritten.
+    gl.stencilOpSeparate(gl.FRONT, 0x1e00, 0x1e00, 0x1e01); // KEEP, KEEP, REPLACE
+    gl.stencilOpSeparate(gl.BACK, 0x1e02, 0x1e03, 0x150a); // INCR, DECR, INVERT
+    gl.stencilFuncSeparate(gl.FRONT, 0x0201, 1, 0xf0); // LESS
+    gl.stencilFuncSeparate(gl.BACK, 0x0204, 2, 0x0f); // GREATER
+    gl.stencilMaskSeparate(gl.FRONT, 0xaa);
+    gl.stencilMaskSeparate(gl.BACK, 0x55);
+    const host = new Map(fixture.parameters);
+    pushGlRenderState(fixture.state);
+
+    // What Flight's own 2D clip pass writes: separate wrap ops per face, then a symmetric gate.
+    gl.stencilOpSeparate(gl.FRONT, 0x1e00, 0x1e00, 0x8507); // INCR_WRAP
+    gl.stencilOpSeparate(gl.BACK, 0x1e00, 0x1e00, 0x8508); // DECR_WRAP
+    gl.stencilFunc(0x0207, 0, 0xff); // ALWAYS, both faces
+    gl.stencilMask(0xff);
+    popGlRenderState(fixture.state);
+
+    for (const parameter of TWO_SIDED_STENCIL_PARAMETERS) {
+      expect([parameter, fixture.parameters.get(gl[parameter])]).toEqual([parameter, host.get(gl[parameter])]);
+    }
+  });
+
+  it('restores colour-write, clear-colour, and upload-premultiply state Flight leaves behind', () => {
+    const fixture = createStatefulGl();
+    const gl = fixture.gl;
+    applyTestGlState(fixture, OUTER_STATE);
+    // A host whose own settings all differ from both the GL defaults and from what Flight will set,
+    // so neither 'never restored' nor 'reset to the default' can pass as restoration.
+    gl.colorMask(true, false, true, false);
+    gl.clearColor(0.25, 0.5, 0.75, 1);
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+    pushGlRenderState(fixture.state);
+
+    // What Flight's own passes do: mask colour off while rasterizing clip coverage, clear a target,
+    // and premultiply a texture upload. None of these puts the previous value back.
+    gl.colorMask(false, false, false, false);
+    gl.clearColor(0, 0, 0, 0);
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, true);
+    popGlRenderState(fixture.state);
+
+    expect(fixture.parameters.get(gl.COLOR_WRITEMASK)).toEqual([true, false, true, false]);
+    expect(fixture.parameters.get(gl.COLOR_CLEAR_VALUE)).toEqual([0.25, 0.5, 0.75, 1]);
+    expect(fixture.parameters.get(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL)).toBe(false);
+  });
+
   it('restores a non-active texture unit binding', () => {
     const fixture = createStatefulGl();
     applyTestGlState(fixture, OUTER_STATE);
@@ -207,6 +267,9 @@ function applyTestGlState(fixture: StatefulGl, values: Readonly<TestGlState>): v
   gl.depthFunc(values.depthFunc);
   setCapability(gl, gl.CULL_FACE, values.cullFace);
   gl.cullFace(values.cullFaceMode);
+  gl.frontFace(values.frontFace);
+  setCapability(gl, gl.STENCIL_TEST, values.stencilTest);
+  gl.stencilMask(values.stencilWriteMask);
   setCapability(gl, gl.BLEND, values.blend);
   gl.blendFuncSeparate(values.blendSrcRgb, values.blendDstRgb, values.blendSrcAlpha, values.blendDstAlpha);
   gl.blendEquationSeparate(values.blendEquationRgb, values.blendEquationAlpha);
@@ -244,6 +307,27 @@ function createStatefulGl(): StatefulGl & ReturnType<typeof createGlState> {
     DEPTH_FUNC: 0x0b74,
     DEPTH_WRITEMASK: 0x0b72,
     FRAMEBUFFER_BINDING: 0x8ca6,
+    FRONT_FACE: 0x0b46,
+    BACK: 0x0405,
+    COLOR_CLEAR_VALUE: 0x0c22,
+    COLOR_WRITEMASK: 0x0c23,
+    UNPACK_PREMULTIPLY_ALPHA_WEBGL: 0x9241,
+    FRONT: 0x0404,
+    STENCIL_BACK_FAIL: 0x8801,
+    STENCIL_BACK_FUNC: 0x8800,
+    STENCIL_BACK_PASS_DEPTH_FAIL: 0x8802,
+    STENCIL_BACK_PASS_DEPTH_PASS: 0x8803,
+    STENCIL_BACK_REF: 0x8ca3,
+    STENCIL_BACK_VALUE_MASK: 0x8ca4,
+    STENCIL_BACK_WRITEMASK: 0x8ca5,
+    STENCIL_FAIL: 0x0b94,
+    STENCIL_FUNC: 0x0b92,
+    STENCIL_PASS_DEPTH_FAIL: 0x0b95,
+    STENCIL_PASS_DEPTH_PASS: 0x0b96,
+    STENCIL_REF: 0x0b97,
+    STENCIL_TEST: 0x0b90,
+    STENCIL_VALUE_MASK: 0x0b93,
+    STENCIL_WRITEMASK: 0x0b98,
     SCISSOR_BOX: 0x0c10,
     TEXTURE_BINDING_2D: 0x8069,
     VERTEX_ARRAY_BINDING: 0x85b5,
@@ -271,6 +355,65 @@ function createStatefulGl(): StatefulGl & ReturnType<typeof createGlState> {
   (gl.cullFace as ReturnType<typeof vi.fn>).mockImplementation((value: number) =>
     parameters.set(gl.CULL_FACE_MODE, value),
   );
+  (gl.frontFace as ReturnType<typeof vi.fn>).mockImplementation((value: number) =>
+    parameters.set(gl.FRONT_FACE, value),
+  );
+  (gl.colorMask as ReturnType<typeof vi.fn>).mockImplementation((r: boolean, g: boolean, b: boolean, a: boolean) =>
+    parameters.set(gl.COLOR_WRITEMASK, [r, g, b, a]),
+  );
+  (gl.clearColor as ReturnType<typeof vi.fn>).mockImplementation((r: number, g: number, b: number, a: number) =>
+    parameters.set(gl.COLOR_CLEAR_VALUE, [r, g, b, a]),
+  );
+  (gl.pixelStorei as ReturnType<typeof vi.fn>).mockImplementation((parameter: number, value: unknown) =>
+    parameters.set(parameter, value),
+  );
+  // Stencil is two-faced state: the unsuffixed setters write FRONT_AND_BACK while the Separate ones
+  // write only the named face. That rule was measured against a real WebGL2 context rather than assumed
+  // here — a fake cannot be the oracle for the API it fakes. `null` is the unsuffixed, both-faces form.
+  const writeStencilMask = (face: number | null, value: number): void => {
+    if (face !== gl.BACK) parameters.set(gl.STENCIL_WRITEMASK, value);
+    if (face !== gl.FRONT) parameters.set(gl.STENCIL_BACK_WRITEMASK, value);
+  };
+  const writeStencilFunc = (face: number | null, func: number, ref: number, mask: number): void => {
+    if (face !== gl.BACK) {
+      parameters.set(gl.STENCIL_FUNC, func);
+      parameters.set(gl.STENCIL_REF, ref);
+      parameters.set(gl.STENCIL_VALUE_MASK, mask);
+    }
+    if (face !== gl.FRONT) {
+      parameters.set(gl.STENCIL_BACK_FUNC, func);
+      parameters.set(gl.STENCIL_BACK_REF, ref);
+      parameters.set(gl.STENCIL_BACK_VALUE_MASK, mask);
+    }
+  };
+  const writeStencilOp = (face: number | null, fail: number, depthFail: number, depthPass: number): void => {
+    if (face !== gl.BACK) {
+      parameters.set(gl.STENCIL_FAIL, fail);
+      parameters.set(gl.STENCIL_PASS_DEPTH_FAIL, depthFail);
+      parameters.set(gl.STENCIL_PASS_DEPTH_PASS, depthPass);
+    }
+    if (face !== gl.FRONT) {
+      parameters.set(gl.STENCIL_BACK_FAIL, fail);
+      parameters.set(gl.STENCIL_BACK_PASS_DEPTH_FAIL, depthFail);
+      parameters.set(gl.STENCIL_BACK_PASS_DEPTH_PASS, depthPass);
+    }
+  };
+  (gl.stencilMask as ReturnType<typeof vi.fn>).mockImplementation((value: number) => writeStencilMask(null, value));
+  (gl.stencilMaskSeparate as ReturnType<typeof vi.fn>).mockImplementation((face: number, value: number) =>
+    writeStencilMask(face, value),
+  );
+  (gl.stencilFunc as ReturnType<typeof vi.fn>).mockImplementation((func: number, ref: number, mask: number) =>
+    writeStencilFunc(null, func, ref, mask),
+  );
+  (gl.stencilFuncSeparate as ReturnType<typeof vi.fn>).mockImplementation(
+    (face: number, func: number, ref: number, mask: number) => writeStencilFunc(face, func, ref, mask),
+  );
+  (gl.stencilOp as ReturnType<typeof vi.fn>).mockImplementation((fail: number, dFail: number, dPass: number) =>
+    writeStencilOp(null, fail, dFail, dPass),
+  );
+  (gl.stencilOpSeparate as ReturnType<typeof vi.fn>).mockImplementation(
+    (face: number, fail: number, dFail: number, dPass: number) => writeStencilOp(face, fail, dFail, dPass),
+  );
   (gl.blendFuncSeparate as ReturnType<typeof vi.fn>).mockImplementation(
     (srcRgb: number, dstRgb: number, srcAlpha: number, dstAlpha: number) => {
       parameters.set(gl.BLEND_SRC_RGB, srcRgb);
@@ -315,6 +458,14 @@ function expectTestGlState(fixture: StatefulGl, expected: Readonly<TestGlState>)
   expect(parameters.get(gl.DEPTH_FUNC)).toBe(expected.depthFunc);
   expect(gl.isEnabled(gl.CULL_FACE)).toBe(expected.cullFace);
   expect(parameters.get(gl.CULL_FACE_MODE)).toBe(expected.cullFaceMode);
+  // The 3D mesh path picks a front face per draw from the model determinant, so this is state Flight
+  // mutates and must hand back untouched — a host set to CW must not get CCW returned.
+  expect(parameters.get(gl.FRONT_FACE)).toBe(expected.frontFace);
+  // Flight's 2D clip system rasterizes stencil masks; its internal restore is scoped to Flight's own
+  // nesting and disables the test outright when Flight had no clip, so the host-facing preservation
+  // has to happen here. The outer fixture starts ENABLED so 'restored' is distinguishable from 'left off'.
+  expect(gl.isEnabled(gl.STENCIL_TEST)).toBe(expected.stencilTest);
+  expect(parameters.get(gl.STENCIL_WRITEMASK)).toBe(expected.stencilWriteMask);
   expect(gl.isEnabled(gl.BLEND)).toBe(expected.blend);
   expect(parameters.get(gl.BLEND_SRC_RGB)).toBe(expected.blendSrcRgb);
   expect(parameters.get(gl.BLEND_DST_RGB)).toBe(expected.blendDstRgb);
@@ -347,3 +498,22 @@ function setCapability(gl: WebGL2RenderingContext, capability: number, enabled:
     gl.disable(capability);
   }
 }
+
+// Both faces of every stencil parameter the bracket saves. Naming them here rather than asserting a
+// handful keeps the list checkable against the saved-state fields by eye.
+const TWO_SIDED_STENCIL_PARAMETERS = [
+  'STENCIL_FAIL',
+  'STENCIL_BACK_FAIL',
+  'STENCIL_PASS_DEPTH_FAIL',
+  'STENCIL_BACK_PASS_DEPTH_FAIL',
+  'STENCIL_PASS_DEPTH_PASS',
+  'STENCIL_BACK_PASS_DEPTH_PASS',
+  'STENCIL_FUNC',
+  'STENCIL_BACK_FUNC',
+  'STENCIL_REF',
+  'STENCIL_BACK_REF',
+  'STENCIL_VALUE_MASK',
+  'STENCIL_BACK_VALUE_MASK',
+  'STENCIL_WRITEMASK',
+  'STENCIL_BACK_WRITEMASK',
+] as const;

package/src/glShader.test.ts

@@ -1,16 +1,18 @@
 import { EntityRuntimeKey } from '@flighthq/types/contract';
 
+import { getGlRenderStateRuntime } from './glRenderState';
 import {
   compileDefaultGlProgram,
   compileGlBitmapProgram,
   createDefaultGlBitmapShader,
   createGlBitmapShader,
+  ensureDefaultGlBitmapShader,
   setGlAttributes,
   setGlBaseUniforms,
   setGlMatrixFromTransform,
   setGlMatrixFromValues,
 } from './glShader';
-import { makeGL, makeShaderLoc } from './glTestHelper';
+import { createGlState, makeGL, makeShaderLoc } from './glTestHelper';
 
 describe('compileDefaultGlProgram', () => {
   it('returns shader locations with all required fields', () => {
@@ -150,6 +152,30 @@ describe('createGlBitmapShader', () => {
   });
 });
 
+describe('ensureDefaultGlBitmapShader', () => {
+  it('compiles and caches the default shader on first call', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    runtime.defaultBitmapShader = null;
+    runtime.shaderLoc = null;
+    const shader = ensureDefaultGlBitmapShader(state);
+    expect(shader).toBeDefined();
+    expect(shader.program).toBeDefined();
+    expect(runtime.defaultBitmapShader).toBe(shader);
+    expect(runtime.shaderLoc).not.toBeNull();
+  });
+
+  it('returns the cached shader on subsequent calls', () => {
+    const { state } = createGlState();
+    const runtime = getGlRenderStateRuntime(state);
+    runtime.defaultBitmapShader = null;
+    runtime.shaderLoc = null;
+    const first = ensureDefaultGlBitmapShader(state);
+    const second = ensureDefaultGlBitmapShader(state);
+    expect(second).toBe(first);
+  });
+});
+
 describe('setGlAttributes', () => {
   it('enables the position vertex attrib array', () => {
     const gl = makeGL();
@@ -233,6 +259,34 @@ describe('setGlBaseUniforms', () => {
 });
 
 describe('setGlMatrixFromTransform', () => {
+  it('projects the quad corner order to a clockwise triangle, which is why 2D draws need culling off', () => {
+    // Measured in a real WebGL2 context, not argued: with CULL_FACE enabled and the CCW default, this
+    // quad renders 0 lit pixels where it otherwise renders 2304 — a single-sided 3D draw earlier in the
+    // frame therefore erases all 2D content. `renderGlScene2D` disables CULL_FACE because of THIS, and
+    // without an assertion the reason lives only in a comment: someone who later made the winding CCW
+    // would find the disable looking superfluous. The corner order below mirrors the quadVertexData
+    // fill in glDraw.ts and must be changed with it.
+    const gl = makeGL();
+    const m = new Float32Array(9);
+    const canvas = document.createElement('canvas');
+    canvas.width = 200;
+    canvas.height = 100;
+    setGlMatrixFromTransform(gl, makeShaderLoc(), m, { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 }, canvas);
+
+    const project = (x: number, y: number): [number, number] => [
+      m[0] * x + m[3] * y + m[6],
+      m[1] * x + m[4] * y + m[7],
+    ];
+    const [x0, y0, x1, y1] = [20, 30, 120, 80];
+    const [ax, ay] = project(x0, y0);
+    const [bx, by] = project(x1, y0);
+    const [cx, cy] = project(x1, y1);
+
+    // Signed area of the first indexed triangle (indices [0, 1, 2]); negative is clockwise.
+    const signedArea = (bx - ax) * (cy - ay) - (by - ay) * (cx - ax);
+    expect(signedArea).toBeLessThan(0);
+  });
+
   it('computes matrix scaled by canvas dimensions for identity transform', () => {
     const gl = makeGL();
     const loc = makeShaderLoc();

package/src/glTestHelper.test.ts

@@ -0,0 +1,51 @@
+import { makeGL } from './glTestHelper';
+
+describe('makeGL', () => {
+  it('keeps draw validation outside a test-installed mock implementation', () => {
+    const gl = makeGL();
+    const draw = vi.fn();
+    (gl.drawElements as ReturnType<typeof vi.fn>).mockImplementation(draw);
+
+    gl.drawElements(gl.TRIANGLES, 1, gl.UNSIGNED_SHORT, 1);
+
+    expect(draw).not.toHaveBeenCalled();
+    expect(gl.getError()).toBe(gl.INVALID_OPERATION);
+
+    gl.drawElements(gl.TRIANGLES, 1, gl.UNSIGNED_SHORT, 0);
+    expect(draw).toHaveBeenCalledOnce();
+  });
+
+  it('sets and consumes the first GL draw error without throwing', () => {
+    const gl = makeGL();
+
+    expect(() => gl.drawElements(gl.TRIANGLES, -1, gl.UNSIGNED_SHORT, 0)).not.toThrow();
+    gl.drawElements(0xffff, 1, gl.UNSIGNED_SHORT, 0);
+
+    expect(gl.drawElements).not.toHaveBeenCalled();
+    expect(gl.getError()).toBe(gl.INVALID_VALUE);
+    expect(gl.getError()).toBe(gl.NO_ERROR);
+  });
+
+  it('reports a type-misaligned index offset as INVALID_OPERATION', () => {
+    const gl = makeGL();
+
+    gl.drawElements(gl.TRIANGLES, 1, gl.UNSIGNED_SHORT, 1);
+
+    expect(gl.getError()).toBe(gl.INVALID_OPERATION);
+    expect(gl.getError()).toBe(gl.NO_ERROR);
+  });
+
+  it('validates non-indexed and instanced draw entry points', () => {
+    const gl = makeGL();
+
+    gl.drawArrays(0xffff, 0, 1);
+    expect(gl.getError()).toBe(gl.INVALID_ENUM);
+
+    gl.drawArraysInstanced(gl.TRIANGLES, 0, 1, -1);
+    expect(gl.getError()).toBe(gl.INVALID_VALUE);
+
+    gl.drawElementsInstanced(gl.TRIANGLES, 1, gl.FLOAT, 0, 1);
+    expect(gl.getError()).toBe(gl.INVALID_ENUM);
+    expect(gl.getError()).toBe(gl.NO_ERROR);
+  });
+});

package/src/glTextureResolver.test.ts

@@ -1,4 +1,5 @@
 import { createEntity } from '@flighthq/entity/contract';
+import { getRegistryTableKeys } from '@flighthq/registry/contract';
 import type { Image, RenderTexture, TextureLike, TextureSource } from '@flighthq/types/contract';
 import {
   BitmapTextureSourceKind,
@@ -80,11 +81,17 @@ function textureWithTarget(): TextureLike {
   return texture;
 }
 
+function registeredTextureSourceKinds(state: Parameters<typeof getGlRenderStateRuntime>[0]): string[] {
+  const kinds: string[] = [];
+  getRegistryTableKeys(kinds, getGlRenderStateRuntime(state).registries.textureResolvers);
+  return kinds;
+}
+
 describe('registerGlBitmapTextureResolver', () => {
   it('registers only the Bitmap source key', () => {
     const { state } = createGlState();
     registerGlBitmapTextureResolver(state);
-    expect([...getGlRenderStateRuntime(state).glTextureResolverRegistry!.keys()]).toEqual([BitmapTextureSourceKind]);
+    expect(registeredTextureSourceKinds(state)).toEqual([BitmapTextureSourceKind]);
   });
 });
 
@@ -92,9 +99,7 @@ describe('registerGlCompressedImageTextureResolver', () => {
   it('registers only the CompressedImage source key', () => {
     const { state } = createGlState();
     registerGlCompressedImageTextureResolver(state);
-    expect([...getGlRenderStateRuntime(state).glTextureResolverRegistry!.keys()]).toEqual([
-      CompressedImageTextureSourceKind,
-    ]);
+    expect(registeredTextureSourceKinds(state)).toEqual([CompressedImageTextureSourceKind]);
   });
 });
 
@@ -225,7 +230,7 @@ describe('registerGlTextureResolver', () => {
 
     registerGlTextureResolver(a, sourceKind, second);
     expect(resolveGlTexture(a, texture)).toEqual({ second: true });
-    expect(getGlRenderStateRuntime(a).glTextureResolverRegistry?.size).toBe(1);
+    expect(getGlRenderStateRuntime(a).registries.textureResolvers.entries.size).toBe(1);
 
     registerGlTextureResolver(a, sourceKind, null);
     expect(resolveGlTexture(a, texture)).toBeNull();
@@ -244,7 +249,7 @@ describe('registerStandardGlTextureResolvers', () => {
   it('registers bitmap, image, and render texture sources without compressed images', () => {
     const { state } = createGlState();
     registerStandardGlTextureResolvers(state);
-    expect([...getGlRenderStateRuntime(state).glTextureResolverRegistry!.keys()]).toEqual([
+    expect(registeredTextureSourceKinds(state)).toEqual([
       BitmapTextureSourceKind,
       ImageTextureSourceKind,
       RenderTargetTextureSourceKind,