@flighthq/render-gl 0.2.0 → 0.2.1-next.410.a23f189

package/src/glRenderPass.test.ts

@@ -0,0 +1,170 @@
+import { createMatrix } from '@flighthq/geometry';
+import type { GlRenderTarget } from '@flighthq/types';
+
+import { beginGlRenderPass, endGlRenderPass, setGlRenderTransform2D } from './glRenderPass';
+import { getGlRenderStateRuntime } from './glRenderState';
+import { createGlState } from './glTestHelper';
+
+function makeTarget(overrides?: Partial<GlRenderTarget>): GlRenderTarget {
+  const texture = { id: 'c0' } as unknown as WebGLTexture;
+  return {
+    width: 32,
+    height: 16,
+    format: 'rgba8',
+    colorSpace: 'srgb',
+    clearColors: [],
+    clearDepth: 1,
+    sampleCount: 1,
+    framebuffer: {} as WebGLFramebuffer,
+    resolveFramebuffer: null,
+    textures: [texture],
+    texture,
+    depthTexture: null,
+    colorRenderbuffers: [],
+    depthStencilRenderbuffer: { id: 'depth' } as unknown as WebGLRenderbuffer,
+    ...overrides,
+  };
+}
+
+describe('beginGlRenderPass', () => {
+  it('clears every color attachment and depth by default', () => {
+    const { state, gl } = createGlState();
+    const clearColor = vi.spyOn(gl, 'clearBufferfv');
+    const clearDepth = vi.spyOn(gl, 'clearBufferfi');
+
+    beginGlRenderPass(state, makeTarget());
+
+    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', () => {
+    const { state, gl } = createGlState();
+    const clearColor = vi.spyOn(gl, 'clearBufferfv');
+    const clearDepth = vi.spyOn(gl, 'clearBufferfi');
+
+    beginGlRenderPass(state, makeTarget(), { preserveColor: true });
+
+    expect(clearColor).not.toHaveBeenCalled();
+    expect(clearDepth).toHaveBeenCalled();
+  });
+
+  it('spares depth when preserveDepth is true, still clears color', () => {
+    const { state, gl } = createGlState();
+    const clearColor = vi.spyOn(gl, 'clearBufferfv');
+    const clearDepth = vi.spyOn(gl, 'clearBufferfi');
+
+    beginGlRenderPass(state, makeTarget(), { preserveDepth: true });
+
+    expect(clearColor).toHaveBeenCalled();
+    expect(clearDepth).not.toHaveBeenCalled();
+  });
+
+  it('preserves per attachment location when preserveColor is an array', () => {
+    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] });
+
+    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] });
+    const clearColor = vi.spyOn(gl, 'clearBufferfv');
+
+    beginGlRenderPass(state, makeTarget({ clearColors: [0xff0000ff] })); // opaque red
+
+    const rgba = clearColor.mock.calls[0][2] as Float32Array;
+    expect(rgba[0]).toBeCloseTo(1);
+    expect(rgba[1]).toBeCloseTo(0);
+    expect(rgba[3]).toBeCloseTo(1);
+  });
+
+  it('binds the target and sets the viewport to its dimensions', () => {
+    const { state } = createGlState();
+    const target = makeTarget({ width: 64, height: 48 });
+
+    beginGlRenderPass(state, target);
+
+    const runtime = getGlRenderStateRuntime(state);
+    expect(runtime.currentRenderTarget).toBe(target);
+    expect(runtime.renderTargetViewport).toEqual({ width: 64, height: 48 });
+  });
+
+  it('nests: the inner pass is current until it ends, then the outer is restored', () => {
+    const { state } = createGlState();
+    const outer = makeTarget({ width: 64, height: 48 });
+    const inner = makeTarget({ width: 32, height: 32 });
+    const runtime = getGlRenderStateRuntime(state);
+
+    beginGlRenderPass(state, outer);
+    beginGlRenderPass(state, inner);
+    expect(runtime.currentRenderTarget).toBe(inner);
+
+    endGlRenderPass(state);
+    expect(runtime.currentRenderTarget).toBe(outer);
+    expect(runtime.renderTargetViewport).toEqual({ width: 64, height: 48 });
+  });
+});
+
+describe('endGlRenderPass', () => {
+  it('restores the framebuffer binding that preceded the pass', () => {
+    const { state, gl } = createGlState();
+    const target = makeTarget();
+    const bindFramebuffer = vi.spyOn(gl, 'bindFramebuffer');
+
+    beginGlRenderPass(state, target);
+    endGlRenderPass(state);
+
+    // The pass began with the canvas default bound (null); ending restores it.
+    expect(bindFramebuffer.mock.calls.at(-1)?.[1]).toBe(null);
+  });
+
+  it('restores the render-target viewport to its pre-pass value (null = canvas)', () => {
+    const { state } = createGlState();
+    const target = makeTarget();
+
+    beginGlRenderPass(state, target);
+    endGlRenderPass(state);
+
+    expect(getGlRenderStateRuntime(state).renderTargetViewport).toBeNull();
+  });
+
+  it('is a no-op when there is no matching begin', () => {
+    const { state } = createGlState();
+    expect(() => endGlRenderPass(state)).not.toThrow();
+  });
+});
+
+describe('setGlRenderTransform2D', () => {
+  it('installs a copy of the transform as the 2D root device transform', () => {
+    const { state } = createGlState();
+    const transform = createMatrix();
+    transform.tx = 7;
+
+    setGlRenderTransform2D(state, transform);
+
+    expect(state.renderTransform2D?.tx).toBe(7);
+    // A copy, not the caller's object — so later caller mutations don't leak into render state.
+    expect(state.renderTransform2D).not.toBe(transform);
+  });
+
+  it('is undone by the enclosing pass: endGlRenderPass restores the pre-pass transform', () => {
+    const { state } = createGlState();
+    const original = state.renderTransform2D;
+    const target = makeTarget();
+    const cacheTransform = createMatrix();
+    cacheTransform.tx = 99;
+
+    beginGlRenderPass(state, target, { preserveColor: true });
+    setGlRenderTransform2D(state, cacheTransform);
+    expect(state.renderTransform2D?.tx).toBe(99);
+    endGlRenderPass(state);
+
+    expect(state.renderTransform2D).toBe(original);
+  });
+});

package/src/glRenderTarget.test.ts

@@ -2,13 +2,13 @@ import { createDisplayObject } from '@flighthq/displayobject';
 import { createMatrix } from '@flighthq/geometry';
 import { getOrCreateRenderProxy2D } from '@flighthq/render';
 
+import { beginGlRenderPass, endGlRenderPass } from './glRenderPass';
 import { getGlRenderStateRuntime } from './glRenderState';
 import {
-  beginGlRenderTarget,
   createGlRenderTarget,
+  declareGlRenderTargetColorSpace,
   destroyGlRenderTarget,
   drawGlRenderTargetResult,
-  endGlRenderTarget,
   resizeGlRenderTarget,
   resolveGlRenderTarget,
 } from './glRenderTarget';
@@ -39,57 +39,6 @@ function makeState() {
   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();
@@ -126,6 +75,67 @@ describe('createGlRenderTarget', () => {
     createGlRenderTarget(state, { width: 32, height: 32 });
     expect(runtime.currentTexture).toBeNull();
   });
+
+  it("defaults colorSpace to 'srgb' when the descriptor omits it", () => {
+    const { state } = makeState();
+    const target = createGlRenderTarget(state, { width: 32, height: 32 });
+    expect(target.colorSpace).toBe('srgb');
+  });
+
+  it('honors an explicit colorSpace', () => {
+    const { state } = makeState();
+    const target = createGlRenderTarget(state, { width: 32, height: 32, colorSpace: 'linear' });
+    expect(target.colorSpace).toBe('linear');
+  });
+
+  it('falls back a float format to rgba8 when EXT_color_buffer_float is unavailable', () => {
+    const { state, gl } = makeState();
+    // Simulate GL without float-render support (e.g. headless SwiftShader): a float target would be
+    // framebuffer-incomplete and render black, so the effective format degrades to the renderable rgba8.
+    (gl as unknown as { getExtension: (n: string) => unknown }).getExtension = (name: string) =>
+      name === 'EXT_color_buffer_float' ? null : {};
+    const target = createGlRenderTarget(state, { width: 32, height: 32, format: 'rgba16f' });
+    expect(target.format).toBe('rgba8');
+  });
+
+  it('keeps a float format when EXT_color_buffer_float is available', () => {
+    const { state, gl } = makeState();
+    (gl as unknown as { getExtension: (n: string) => unknown }).getExtension = () => ({});
+    const target = createGlRenderTarget(state, { width: 32, height: 32, format: 'rgba16f' });
+    expect(target.format).toBe('rgba16f');
+  });
+});
+
+describe('declareGlRenderTargetColorSpace', () => {
+  it('stamps the currently bound target and returns true', () => {
+    const { state } = makeState();
+    const target = createGlRenderTarget(state, { width: 64, height: 48 });
+    expect(target.colorSpace).toBe('srgb');
+    beginGlRenderPass(state, target);
+    expect(declareGlRenderTargetColorSpace(state, 'linear')).toBe(true);
+    expect(target.colorSpace).toBe('linear');
+    endGlRenderPass(state);
+  });
+
+  it('returns false when no target is bound (rendering to the canvas)', () => {
+    const { state } = makeState();
+    expect(declareGlRenderTargetColorSpace(state, 'linear')).toBe(false);
+  });
+
+  it('is restored to the outer target when a nested target ends', () => {
+    const { state } = makeState();
+    const outer = createGlRenderTarget(state, { width: 64, height: 48 });
+    const inner = createGlRenderTarget(state, { width: 32, height: 32 });
+    beginGlRenderPass(state, outer);
+    beginGlRenderPass(state, inner);
+    declareGlRenderTargetColorSpace(state, 'linear');
+    expect(inner.colorSpace).toBe('linear');
+    endGlRenderPass(state);
+    // Back on `outer`: a declare now stamps it, not the popped inner target.
+    declareGlRenderTargetColorSpace(state, 'linear');
+    expect(outer.colorSpace).toBe('linear');
+    endGlRenderPass(state);
+  });
 });
 
 describe('destroyGlRenderTarget', () => {
@@ -178,51 +188,6 @@ describe('drawGlRenderTargetResult', () => {
   });
 });
 
-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();

package/src/glRenderTargetPool.test.ts

@@ -27,6 +27,20 @@ describe('acquireGlRenderTarget', () => {
     expect(pool.free.length).toBe(0);
   });
 
+  it('re-stamps colorSpace on a reused target (not part of the physical reuse match)', () => {
+    const { state } = createGlState();
+    const pool = createGlRenderTargetPool();
+    const first = acquireGlRenderTarget(state, pool, { width: 64, height: 48, colorSpace: 'linear' });
+    expect(first.colorSpace).toBe('linear');
+    releaseGlRenderTarget(pool, first);
+
+    // Same dimensions/format/samples but a different color space: the pooled target is reused, so its
+    // stale 'linear' must be overwritten to avoid double-encoding sRGB content at present.
+    const reused = acquireGlRenderTarget(state, pool, { width: 64, height: 48, colorSpace: 'srgb' });
+    expect(reused).toBe(first);
+    expect(reused.colorSpace).toBe('srgb');
+  });
+
   it('allocates a new target when the free target has different dimensions', () => {
     const { state } = createGlState();
     const pool = createGlRenderTargetPool();

package/src/glSkinPaletteTexture.test.ts

@@ -0,0 +1,129 @@
+import type { GlSkinPaletteTexture } from '@flighthq/types';
+
+import {
+  createGlSkinPaletteTexture,
+  destroyGlSkinPaletteTexture,
+  uploadGlSkinPaletteTexture,
+} from './glSkinPaletteTexture';
+
+interface Call {
+  name: string;
+  args: unknown[];
+}
+
+function makeGl(): { gl: WebGL2RenderingContext; calls: Call[] } {
+  const calls: Call[] = [];
+  const record =
+    (name: string, result?: unknown) =>
+    (...args: unknown[]): unknown => {
+      calls.push({ name, args });
+      return result;
+    };
+  const gl = {
+    TEXTURE_2D: 0x0de1,
+    RGBA: 0x1908,
+    RGBA32F: 0x8814,
+    FLOAT: 0x1406,
+    NEAREST: 0x2600,
+    CLAMP_TO_EDGE: 0x812f,
+    TEXTURE_MIN_FILTER: 0x2801,
+    TEXTURE_MAG_FILTER: 0x2800,
+    TEXTURE_WRAP_S: 0x2802,
+    TEXTURE_WRAP_T: 0x2803,
+    createTexture: record('createTexture', { id: 'tex' }),
+    deleteTexture: record('deleteTexture'),
+    bindTexture: record('bindTexture'),
+    texImage2D: record('texImage2D'),
+    texSubImage2D: record('texSubImage2D'),
+    texParameteri: record('texParameteri'),
+  } as unknown as WebGL2RenderingContext;
+  return { gl, calls };
+}
+
+// Two joints' worth of identity-ish palette (32 floats). Values are irrelevant to the upload path.
+function makePalette(jointCount: number): Float32Array {
+  return new Float32Array(jointCount * 16);
+}
+
+describe('createGlSkinPaletteTexture', () => {
+  it('allocates a texture with zero joint capacity', () => {
+    const { gl, calls } = makeGl();
+    const palette = createGlSkinPaletteTexture(gl);
+    expect(palette.jointCapacity).toBe(0);
+    expect(calls.some((c) => c.name === 'createTexture')).toBe(true);
+  });
+});
+
+describe('destroyGlSkinPaletteTexture', () => {
+  it('deletes the palette texture', () => {
+    const { gl, calls } = makeGl();
+    const palette = createGlSkinPaletteTexture(gl);
+    destroyGlSkinPaletteTexture(gl, palette);
+    const del = calls.find((c) => c.name === 'deleteTexture');
+    expect(del?.args[0]).toBe(palette.texture);
+  });
+});
+
+describe('uploadGlSkinPaletteTexture', () => {
+  it('allocates RGBA32F storage width = jointCount*4 and sets NEAREST/CLAMP on first upload', () => {
+    const { gl, calls } = makeGl();
+    const palette = createGlSkinPaletteTexture(gl);
+    uploadGlSkinPaletteTexture(gl, palette, makePalette(3), 3);
+
+    const alloc = calls.find((c) => c.name === 'texImage2D');
+    expect(alloc).toBeDefined();
+    expect(alloc?.args[3]).toBe(12); // width = 3 joints * 4 texels
+    expect(alloc?.args[4]).toBe(1); // height
+    expect(alloc?.args[2]).toBe(gl.RGBA32F);
+    expect(palette.jointCapacity).toBe(3);
+    // NEAREST min+mag, CLAMP_TO_EDGE s+t — four texParameteri calls.
+    expect(calls.filter((c) => c.name === 'texParameteri').length).toBe(4);
+    expect(calls.some((c) => c.name === 'texParameteri' && c.args[2] === gl.NEAREST)).toBe(true);
+    expect(calls.some((c) => c.name === 'texParameteri' && c.args[2] === gl.CLAMP_TO_EDGE)).toBe(true);
+  });
+
+  it('binds the palette texture so the caller can set the sampler unit', () => {
+    const { gl, calls } = makeGl();
+    const palette = createGlSkinPaletteTexture(gl);
+    uploadGlSkinPaletteTexture(gl, palette, makePalette(1), 1);
+    const bind = calls.find((c) => c.name === 'bindTexture');
+    expect(bind?.args[0]).toBe(gl.TEXTURE_2D);
+    expect(bind?.args[1]).toBe(palette.texture);
+  });
+
+  it('writes in place with texSubImage2D when the palette fits the current capacity', () => {
+    const { gl, calls } = makeGl();
+    const palette = createGlSkinPaletteTexture(gl);
+    uploadGlSkinPaletteTexture(gl, palette, makePalette(4), 4);
+    calls.length = 0;
+
+    uploadGlSkinPaletteTexture(gl, palette, makePalette(2), 2);
+
+    expect(calls.some((c) => c.name === 'texImage2D')).toBe(false);
+    const sub = calls.find((c) => c.name === 'texSubImage2D');
+    expect(sub).toBeDefined();
+    expect(sub?.args[4]).toBe(8); // width = 2 joints * 4 (texSubImage2D arg order: target,level,x,y,w,h,…)
+    expect(palette.jointCapacity).toBe(4); // capacity unchanged; no reallocation
+    expect(calls.some((c) => c.name === 'texParameteri')).toBe(false);
+  });
+
+  it('grows storage (reallocates) when the palette exceeds the current capacity', () => {
+    const { gl, calls } = makeGl();
+    const palette = createGlSkinPaletteTexture(gl);
+    uploadGlSkinPaletteTexture(gl, palette, makePalette(2), 2);
+    calls.length = 0;
+
+    uploadGlSkinPaletteTexture(gl, palette, makePalette(5), 5);
+
+    const alloc = calls.find((c) => c.name === 'texImage2D');
+    expect(alloc?.args[3]).toBe(20); // width = 5 joints * 4
+    expect(palette.jointCapacity).toBe(5);
+  });
+
+  it('is alias-safe: reads jointCount before growing capacity', () => {
+    const { gl } = makeGl();
+    const palette: GlSkinPaletteTexture = createGlSkinPaletteTexture(gl);
+    uploadGlSkinPaletteTexture(gl, palette, makePalette(6), 6);
+    expect(palette.jointCapacity).toBe(6);
+  });
+});

package/src/glTextureUpload.test.ts

@@ -0,0 +1,49 @@
+import type { ImageResource } from '@flighthq/types';
+
+import { uploadGlTextureData, uploadGlTextureElement, uploadGlTextureImageResource } from './glTextureUpload';
+
+// The GL enums the primitives read; texImage2D is a spy so a test can assert which overload was driven.
+function makeGl(): WebGL2RenderingContext {
+  return {
+    RGBA: 0x1908,
+    UNSIGNED_BYTE: 0x1401,
+    TEXTURE_2D: 0x0de1,
+    texImage2D: vi.fn(),
+  } as unknown as WebGL2RenderingContext;
+}
+
+describe('uploadGlTextureData', () => {
+  it('drives the raw-pixel overload with width/height/border and the data buffer', () => {
+    const gl = makeGl();
+    const data = new Uint8ClampedArray(2 * 2 * 4);
+    uploadGlTextureData(gl, gl.TEXTURE_2D, 2, 2, data);
+    expect(gl.texImage2D).toHaveBeenCalledWith(gl.TEXTURE_2D, 0, gl.RGBA, 2, 2, 0, gl.RGBA, gl.UNSIGNED_BYTE, data);
+  });
+});
+
+describe('uploadGlTextureElement', () => {
+  it('drives the element overload with the TexImageSource', () => {
+    const gl = makeGl();
+    const source = {} as TexImageSource;
+    uploadGlTextureElement(gl, gl.TEXTURE_2D, source);
+    expect(gl.texImage2D).toHaveBeenCalledWith(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
+  });
+});
+
+describe('uploadGlTextureImageResource', () => {
+  it('takes the element path when the resource carries a source', () => {
+    const gl = makeGl();
+    const source = {} as TexImageSource;
+    const image = { source, data: null, width: 4, height: 4 } as ImageResource;
+    uploadGlTextureImageResource(gl, gl.TEXTURE_2D, image);
+    expect(gl.texImage2D).toHaveBeenCalledWith(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
+  });
+
+  it('takes the raw-pixel path when the resource is data-only', () => {
+    const gl = makeGl();
+    const data = new Uint8ClampedArray(4 * 4 * 4);
+    const image = { source: null, data, width: 4, height: 4 } as ImageResource;
+    uploadGlTextureImageResource(gl, gl.TEXTURE_2D, image);
+    expect(gl.texImage2D).toHaveBeenCalledWith(gl.TEXTURE_2D, 0, gl.RGBA, 4, 4, 0, gl.RGBA, gl.UNSIGNED_BYTE, data);
+  });
+});

package/src/glTextureVideoUpload.test.ts

@@ -0,0 +1,53 @@
+import type { VideoTexture } from '@flighthq/types';
+
+import { uploadGlTextureVideoFrame } from './glTextureVideoUpload';
+
+function makeGl(): WebGL2RenderingContext {
+  return {
+    RGBA: 0x1908,
+    UNSIGNED_BYTE: 0x1401,
+    TEXTURE_2D: 0x0de1,
+    texImage2D: vi.fn(),
+  } as unknown as WebGL2RenderingContext;
+}
+
+// A VideoTexture whose only relevant fields are frameId and the element carrier.
+function makeVideoTexture(frameId: number, readyState = 4, videoWidth = 320, videoHeight = 240): VideoTexture {
+  return {
+    frameId,
+    source: { element: { readyState, videoWidth, videoHeight } as unknown as HTMLVideoElement },
+  } as unknown as VideoTexture;
+}
+
+describe('uploadGlTextureVideoFrame', () => {
+  it('uploads the element and returns the new frame id when the frame advanced', () => {
+    const gl = makeGl();
+    const vt = makeVideoTexture(3);
+    const uploaded = uploadGlTextureVideoFrame(gl, vt, -1);
+    expect(uploaded).toBe(3);
+    expect(gl.texImage2D).toHaveBeenCalledWith(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, vt.source.element);
+  });
+
+  it('skips the upload and returns the same id when the frame has not advanced', () => {
+    const gl = makeGl();
+    const vt = makeVideoTexture(5);
+    const uploaded = uploadGlTextureVideoFrame(gl, vt, 5);
+    expect(uploaded).toBe(5);
+    expect(gl.texImage2D).not.toHaveBeenCalled();
+  });
+
+  it('skips and reports no upload when the element has no decoded frame yet', () => {
+    const gl = makeGl();
+    const vt = makeVideoTexture(1, 1, 0, 0);
+    const uploaded = uploadGlTextureVideoFrame(gl, vt, -1);
+    expect(uploaded).toBe(-1);
+    expect(gl.texImage2D).not.toHaveBeenCalled();
+  });
+
+  it('skips when the element is null', () => {
+    const gl = makeGl();
+    const vt = { frameId: 2, source: { element: null } } as unknown as VideoTexture;
+    expect(uploadGlTextureVideoFrame(gl, vt, -1)).toBe(-1);
+    expect(gl.texImage2D).not.toHaveBeenCalled();
+  });
+});