@flighthq/displayobject-gl 0.1.0

package/src/glClipRectangle.test.ts

@@ -0,0 +1,47 @@
+import { createMatrix, createRectangle } from '@flighthq/geometry';
+import { getGlRenderStateRuntime } from '@flighthq/render-gl';
+
+import { popGlClipRectangle, pushGlClipRectangle } from './glClipRectangle';
+import { createGlState } from './glTestHelper';
+
+describe('popGlClipRectangle', () => {
+  it('restores the previous scissor rectangle', () => {
+    const { state, gl } = createGlState();
+    pushGlClipRectangle(state, createRectangle(0, 0, 100, 50), createMatrix());
+    pushGlClipRectangle(state, createRectangle(10, 10, 10, 10), createMatrix());
+
+    popGlClipRectangle(state);
+
+    expect(gl.scissor).toHaveBeenLastCalledWith(0, 50, 100, 50);
+  });
+
+  it('disables scissor testing when the stack becomes empty', () => {
+    const { state, gl } = createGlState();
+    pushGlClipRectangle(state, createRectangle(0, 0, 100, 50), createMatrix());
+
+    popGlClipRectangle(state);
+
+    expect(gl.disable).toHaveBeenLastCalledWith(gl.SCISSOR_TEST);
+    expect(getGlRenderStateRuntime(state).currentScissorRect).toBeNull();
+  });
+});
+
+describe('pushGlClipRectangle', () => {
+  it('enables scissor testing with a transformed rectangle', () => {
+    const { state, gl } = createGlState();
+
+    pushGlClipRectangle(state, createRectangle(10, 20, 30, 40), createMatrix(1, 0, 0, 1, 5, 6));
+
+    expect(gl.enable).toHaveBeenLastCalledWith(gl.SCISSOR_TEST);
+    expect(gl.scissor).toHaveBeenLastCalledWith(15, 34, 30, 40);
+  });
+
+  it('intersects nested scissor rectangles', () => {
+    const { state, gl } = createGlState();
+
+    pushGlClipRectangle(state, createRectangle(0, 0, 100, 100), createMatrix());
+    pushGlClipRectangle(state, createRectangle(50, 25, 100, 50), createMatrix());
+
+    expect(gl.scissor).toHaveBeenLastCalledWith(50, 25, 50, 50);
+  });
+});

package/src/glColorTransformMaterial.test.ts

@@ -0,0 +1,45 @@
+import { getGlMaterialRenderer } from '@flighthq/render-gl';
+import { ColorTransformMaterialKind } from '@flighthq/types';
+
+import { colorTransformGlMaterialRenderer, registerGlColorTransformMaterial } from './glColorTransformMaterial';
+import { createGlState } from './glTestHelper';
+
+function makeColorTransform(redMultiplier: number) {
+  return {
+    redMultiplier,
+    greenMultiplier: 1,
+    blueMultiplier: 1,
+    alphaMultiplier: 1,
+    redOffset: 0,
+    greenOffset: 0,
+    blueOffset: 0,
+    alphaOffset: 0,
+  };
+}
+
+describe('colorTransformGlMaterialRenderer', () => {
+  it('declares 8 per-instance floats', () => {
+    expect(colorTransformGlMaterialRenderer.instanceFloatCount).toBe(8);
+  });
+
+  it('packs the supplied material data color transform', () => {
+    const out = new Float32Array(8);
+    colorTransformGlMaterialRenderer.packInstance!(null as any, makeColorTransform(0.5) as any, out, 0);
+    expect(out[0]).toBe(0.5);
+    expect(out[3]).toBe(1);
+  });
+
+  it('packs identity when material data is null', () => {
+    const out = new Float32Array(8);
+    colorTransformGlMaterialRenderer.packInstance!(null as any, null, out, 0);
+    expect(Array.from(out)).toEqual([1, 1, 1, 1, 0, 0, 0, 0]);
+  });
+});
+
+describe('registerGlColorTransformMaterial', () => {
+  it('registers the per-instance color transform material renderer', () => {
+    const { state } = createGlState();
+    registerGlColorTransformMaterial(state);
+    expect(getGlMaterialRenderer(state, ColorTransformMaterialKind)).toBe(colorTransformGlMaterialRenderer);
+  });
+});

package/src/glDefaultMaterial.test.ts

@@ -0,0 +1,19 @@
+import { getGlMaterialRenderer } from '@flighthq/render-gl';
+import { DefaultMaterialKind } from '@flighthq/types';
+
+import { defaultGlMaterialRenderer, registerDefaultGlMaterial } from './glDefaultMaterial';
+import { createGlState } from './glTestHelper';
+
+describe('defaultGlMaterialRenderer', () => {
+  it('declares no per-instance float data', () => {
+    expect(defaultGlMaterialRenderer.instanceFloatCount).toBe(0);
+  });
+});
+
+describe('registerDefaultGlMaterial', () => {
+  it('registers the default renderer under DefaultMaterialKind', () => {
+    const { state } = createGlState();
+    registerDefaultGlMaterial(state);
+    expect(getGlMaterialRenderer(state, DefaultMaterialKind)).toBe(defaultGlMaterialRenderer);
+  });
+});

package/src/glDisplayObject.test.ts

@@ -0,0 +1,85 @@
+import { createDisplayObject } from '@flighthq/displayobject';
+import { addNodeChild } from '@flighthq/node';
+import { getOrCreateRenderProxy2D, prepareDisplayObjectRender, registerRenderer } from '@flighthq/render';
+import { createGlRenderState } from '@flighthq/render-gl';
+import type { GlRenderState } from '@flighthq/types';
+import { DisplayObjectKind } from '@flighthq/types';
+
+import { defaultGlDisplayObjectRenderer, drawGlDisplayObject, renderGlDisplayObject } from './glDisplayObject';
+
+function makeState(): GlRenderState {
+  const canvas = document.createElement('canvas');
+  canvas.width = 200;
+  canvas.height = 100;
+  return createGlRenderState(canvas);
+}
+
+function makeRenderer() {
+  return {
+    createData: () => null,
+    submit: vi.fn(),
+  } as any;
+}
+
+describe('defaultGlDisplayObjectRenderer', () => {
+  it('has draw, and createData functions', () => {
+    expect(defaultGlDisplayObjectRenderer.createData({} as any, {} as any)).toBeNull();
+    expect(defaultGlDisplayObjectRenderer.submit).toBe(drawGlDisplayObject);
+  });
+});
+
+describe('drawGlDisplayObject', () => {
+  it('does not draw plain display object geometry', () => {
+    const state = makeState();
+    expect(() => drawGlDisplayObject(state, {} as any)).not.toThrow();
+  });
+});
+
+describe('renderGlDisplayObject', () => {
+  it('does not throw for an empty display object', () => {
+    const state = makeState();
+    const obj = createDisplayObject();
+    prepareDisplayObjectRender(state, obj);
+    expect(() => renderGlDisplayObject(state, obj)).not.toThrow();
+  });
+
+  it('calls renderer.submit for a visible object with a renderer', () => {
+    const state = makeState();
+    const renderer = makeRenderer();
+    registerRenderer(state, DisplayObjectKind, renderer);
+    const obj = createDisplayObject();
+    const data = getOrCreateRenderProxy2D(state, obj);
+    prepareDisplayObjectRender(state, obj);
+
+    renderGlDisplayObject(state, obj);
+
+    expect(renderer.submit).toHaveBeenCalledWith(state, data);
+  });
+
+  it('skips objects with zero alpha', () => {
+    const state = makeState();
+    const renderer = makeRenderer();
+    registerRenderer(state, DisplayObjectKind, renderer);
+    const obj = createDisplayObject();
+    obj.alpha = 0;
+    prepareDisplayObjectRender(state, obj);
+
+    renderGlDisplayObject(state, obj);
+
+    expect(renderer.submit).not.toHaveBeenCalled();
+  });
+
+  it('traverses children and draws visible ones', () => {
+    const state = makeState();
+    const renderer = makeRenderer();
+    registerRenderer(state, DisplayObjectKind, renderer);
+    const parent = createDisplayObject();
+    const child = createDisplayObject();
+    addNodeChild(parent, child);
+    prepareDisplayObjectRender(state, parent);
+
+    renderGlDisplayObject(state, parent);
+
+    expect(renderer.submit).toHaveBeenCalledTimes(2);
+  });
+});

package/src/glDisplayObjectRegistration.test.ts

@@ -0,0 +1,130 @@
+import { getRenderStateRuntime } from '@flighthq/render';
+import { createGlRenderState } from '@flighthq/render-gl';
+import type { GlRenderState } from '@flighthq/types';
+import {
+  BitmapKind,
+  DisplayObjectKind,
+  ParticleEmitterKind,
+  QuadBatchKind,
+  RenderCacheKind,
+  RichTextKind,
+  Scale9ShapeKind,
+  ShapeKind,
+  SpriteKind,
+  TextLabelKind,
+  TilemapKind,
+  VideoKind,
+} from '@flighthq/types';
+
+import { defaultGlBitmapRenderer } from './glBitmap';
+import { defaultGlRenderCacheRenderer } from './glCache';
+import { defaultGlDisplayObjectRenderer } from './glDisplayObject';
+import { registerGlDisplayObjectRenderers } from './glDisplayObjectRegistration';
+import { defaultGlParticleEmitterRenderer } from './glParticleEmitter';
+import { defaultGlQuadBatchRenderer } from './glQuadBatch';
+import { defaultGlRichTextRenderer } from './glRichText';
+import { defaultGlScale9ShapeRenderer } from './glScale9Shape';
+import { defaultGlShapeRenderer } from './glShape';
+import { defaultGlSpriteRenderer } from './glSpriteRenderer';
+import { defaultGlTextLabelRenderer } from './glTextLabel';
+import { defaultGlTilemapRenderer } from './glTilemap';
+import { defaultGlVideoRenderer } from './glVideo';
+
+function makeState(): GlRenderState {
+  const canvas = document.createElement('canvas');
+  canvas.width = 100;
+  canvas.height = 100;
+  return createGlRenderState(canvas);
+}
+
+describe('registerGlDisplayObjectRenderers', () => {
+  it('registers all twelve display-object renderer kinds in one call', () => {
+    const state = makeState();
+    registerGlDisplayObjectRenderers(state);
+    const { rendererMap } = getRenderStateRuntime(state);
+    expect(rendererMap.get(BitmapKind)).toBe(defaultGlBitmapRenderer);
+    expect(rendererMap.get(DisplayObjectKind)).toBe(defaultGlDisplayObjectRenderer);
+    expect(rendererMap.get(ParticleEmitterKind)).toBe(defaultGlParticleEmitterRenderer);
+    expect(rendererMap.get(QuadBatchKind)).toBe(defaultGlQuadBatchRenderer);
+    expect(rendererMap.get(RenderCacheKind)).toBe(defaultGlRenderCacheRenderer);
+    expect(rendererMap.get(RichTextKind)).toBe(defaultGlRichTextRenderer);
+    expect(rendererMap.get(Scale9ShapeKind)).toBe(defaultGlScale9ShapeRenderer);
+    expect(rendererMap.get(ShapeKind)).toBe(defaultGlShapeRenderer);
+    expect(rendererMap.get(SpriteKind)).toBe(defaultGlSpriteRenderer);
+    expect(rendererMap.get(TextLabelKind)).toBe(defaultGlTextLabelRenderer);
+    expect(rendererMap.get(TilemapKind)).toBe(defaultGlTilemapRenderer);
+    expect(rendererMap.get(VideoKind)).toBe(defaultGlVideoRenderer);
+  });
+
+  it('registers BitmapKind with the default bitmap renderer', () => {
+    const state = makeState();
+    registerGlDisplayObjectRenderers(state);
+    expect(getRenderStateRuntime(state).rendererMap.get(BitmapKind)).toBe(defaultGlBitmapRenderer);
+  });
+
+  it('registers DisplayObjectKind with the default display object renderer', () => {
+    const state = makeState();
+    registerGlDisplayObjectRenderers(state);
+    expect(getRenderStateRuntime(state).rendererMap.get(DisplayObjectKind)).toBe(defaultGlDisplayObjectRenderer);
+  });
+
+  it('registers ParticleEmitterKind with the default particle emitter renderer', () => {
+    const state = makeState();
+    registerGlDisplayObjectRenderers(state);
+    expect(getRenderStateRuntime(state).rendererMap.get(ParticleEmitterKind)).toBe(defaultGlParticleEmitterRenderer);
+  });
+
+  it('registers QuadBatchKind with the default quad batch renderer', () => {
+    const state = makeState();
+    registerGlDisplayObjectRenderers(state);
+    expect(getRenderStateRuntime(state).rendererMap.get(QuadBatchKind)).toBe(defaultGlQuadBatchRenderer);
+  });
+
+  it('registers RenderCacheKind with the default render cache renderer', () => {
+    const state = makeState();
+    registerGlDisplayObjectRenderers(state);
+    expect(getRenderStateRuntime(state).rendererMap.get(RenderCacheKind)).toBe(defaultGlRenderCacheRenderer);
+  });
+
+  it('registers RichTextKind with the default rich text renderer', () => {
+    const state = makeState();
+    registerGlDisplayObjectRenderers(state);
+    expect(getRenderStateRuntime(state).rendererMap.get(RichTextKind)).toBe(defaultGlRichTextRenderer);
+  });
+
+  it('registers Scale9ShapeKind with the default scale9 shape renderer', () => {
+    const state = makeState();
+    registerGlDisplayObjectRenderers(state);
+    expect(getRenderStateRuntime(state).rendererMap.get(Scale9ShapeKind)).toBe(defaultGlScale9ShapeRenderer);
+  });
+
+  it('registers ShapeKind with the default shape renderer', () => {
+    const state = makeState();
+    registerGlDisplayObjectRenderers(state);
+    expect(getRenderStateRuntime(state).rendererMap.get(ShapeKind)).toBe(defaultGlShapeRenderer);
+  });
+
+  it('registers SpriteKind with the default sprite renderer', () => {
+    const state = makeState();
+    registerGlDisplayObjectRenderers(state);
+    expect(getRenderStateRuntime(state).rendererMap.get(SpriteKind)).toBe(defaultGlSpriteRenderer);
+  });
+
+  it('registers TextLabelKind with the default text label renderer', () => {
+    const state = makeState();
+    registerGlDisplayObjectRenderers(state);
+    expect(getRenderStateRuntime(state).rendererMap.get(TextLabelKind)).toBe(defaultGlTextLabelRenderer);
+  });
+
+  it('registers TilemapKind with the default tilemap renderer', () => {
+    const state = makeState();
+    registerGlDisplayObjectRenderers(state);
+    expect(getRenderStateRuntime(state).rendererMap.get(TilemapKind)).toBe(defaultGlTilemapRenderer);
+  });
+
+  it('registers VideoKind with the default video renderer', () => {
+    const state = makeState();
+    registerGlDisplayObjectRenderers(state);
+    expect(getRenderStateRuntime(state).rendererMap.get(VideoKind)).toBe(defaultGlVideoRenderer);
+  });
+});

package/src/glMaterials.test.ts

@@ -0,0 +1,91 @@
+import { getGlRenderStateRuntime } from '@flighthq/render-gl';
+import { ColorTransformMaterialKind, UniformColorTransformMaterialKind } from '@flighthq/types';
+
+import { getGlRenderProxyColorTransform, registerGlColorTransformShader } from './glMaterials';
+import { createGlState } from './glTestHelper';
+
+describe('getGlRenderProxyColorTransform', () => {
+  it('returns null when the node has no material', () => {
+    expect(getGlRenderProxyColorTransform({ material: null } as never)).toBeNull();
+  });
+
+  it('returns the value carried on a uniform color transform material', () => {
+    const colorTransform = { redMultiplier: 0.5 };
+    const node = { material: { kind: UniformColorTransformMaterialKind, colorTransform } } as never;
+    expect(getGlRenderProxyColorTransform(node)).toBe(colorTransform);
+  });
+
+  it('returns the per-node material data for a color transform material', () => {
+    const colorTransform = { redMultiplier: 0.5 };
+    const node = { material: { kind: ColorTransformMaterialKind }, materialData: colorTransform } as never;
+    expect(getGlRenderProxyColorTransform(node)).toBe(colorTransform);
+  });
+});
+
+describe('registerGlColorTransformShader', () => {
+  it('registers a color transform shader on the render state', () => {
+    const { state } = createGlState();
+
+    registerGlColorTransformShader(state);
+
+    expect(getGlRenderStateRuntime(state).colorTransformBitmapShader).toBeDefined();
+  });
+
+  it('does not make the color transform shader the state default shader', () => {
+    const { state } = createGlState();
+
+    registerGlColorTransformShader(state);
+
+    const runtime = getGlRenderStateRuntime(state);
+    expect(runtime.defaultBitmapShader).not.toBe(runtime.colorTransformBitmapShader);
+  });
+
+  it('includes color transform uniform locations', () => {
+    const { state } = createGlState();
+
+    registerGlColorTransformShader(state);
+
+    const runtime = getGlRenderStateRuntime(state);
+    expect(runtime.colorTransformBitmapShader?.locations.locColorMultiplier).toBeDefined();
+    expect(runtime.colorTransformBitmapShader?.locations.locColorOffset).toBeDefined();
+    expect(runtime.colorTransformBitmapShader?.locations.locHasColorTransform).toBeDefined();
+  });
+
+  it('binds color transform uniforms from the node material data', () => {
+    const { state, gl } = createGlState();
+    const renderProxy = {
+      alpha: 0.75,
+      material: { kind: ColorTransformMaterialKind },
+      materialData: {
+        redMultiplier: 0.5,
+        greenMultiplier: 0.25,
+        blueMultiplier: 1.5,
+        alphaMultiplier: 0.8,
+        redOffset: 10,
+        greenOffset: 20,
+        blueOffset: 30,
+        alphaOffset: 40,
+      },
+      transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 },
+    };
+
+    registerGlColorTransformShader(state);
+    const runtime = getGlRenderStateRuntime(state);
+    runtime.colorTransformBitmapShader!.bind(gl, state, renderProxy as never);
+
+    const loc = runtime.colorTransformBitmapShader!.locations;
+    expect(gl.uniform1i).toHaveBeenCalledWith(loc.locHasColorTransform, 1);
+    expect(gl.uniform4f).toHaveBeenCalledWith(loc.locColorMultiplier, 0.5, 0.25, 1.5, 0.8);
+    expect(gl.uniform4f).toHaveBeenCalledWith(loc.locColorOffset, 10 / 255, 20 / 255, 30 / 255, 40 / 255);
+  });
+
+  it('does not replace an existing color transform shader', () => {
+    const { state } = createGlState();
+
+    registerGlColorTransformShader(state);
+    const first = getGlRenderStateRuntime(state).colorTransformBitmapShader;
+    registerGlColorTransformShader(state);
+
+    expect(getGlRenderStateRuntime(state).colorTransformBitmapShader).toBe(first);
+  });
+});

package/src/glParticleEmitter.test.ts

@@ -0,0 +1,98 @@
+import type { RenderProxy2D } from '@flighthq/types';
+
+import { defaultGlParticleEmitterRenderer, drawGlParticleEmitter } from './glParticleEmitter';
+import { createGlState } from './glTestHelper';
+
+function makeAtlas() {
+  const img = document.createElement('img');
+  return {
+    image: { source: img, width: 64, height: 64 },
+    regions: [{ id: 0, x: 0, y: 0, width: 32, height: 32 }],
+  };
+}
+
+function makeParticleEmitterNode(data: Record<string, unknown> = {}): RenderProxy2D {
+  return {
+    source: {
+      data: {
+        atlas: makeAtlas(),
+        particleCount: 1,
+        ids: new Uint16Array([0]),
+        transforms: new Float32Array([0, 0, 0, 1]),
+        alphas: new Float32Array([1]),
+        colors: new Float32Array([1, 1, 1]),
+        ...data,
+      },
+    },
+    blendMode: 0,
+    alpha: 1,
+    transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 },
+  } as unknown as RenderProxy2D;
+}
+
+describe('defaultGlParticleEmitterRenderer', () => {
+  it('has a createData function', () => {
+    expect(typeof defaultGlParticleEmitterRenderer.createData).toBe('function');
+  });
+
+  it('has a submit function', () => {
+    expect(typeof defaultGlParticleEmitterRenderer.submit).toBe('function');
+  });
+});
+
+describe('drawGlParticleEmitter', () => {
+  it('returns early without drawing when atlas is null', () => {
+    const { state, gl } = createGlState();
+    drawGlParticleEmitter(state, makeParticleEmitterNode({ atlas: null }));
+    expect(gl.drawElements).not.toHaveBeenCalled();
+  });
+
+  it('returns early without drawing when atlas.image is null', () => {
+    const { state, gl } = createGlState();
+    drawGlParticleEmitter(state, makeParticleEmitterNode({ atlas: { image: null, regions: [] } }));
+    expect(gl.drawElements).not.toHaveBeenCalled();
+  });
+
+  it('returns early without drawing when atlas.image.source is null', () => {
+    const { state, gl } = createGlState();
+    drawGlParticleEmitter(state, makeParticleEmitterNode({ atlas: { image: { source: null }, regions: [] } }));
+    expect(gl.drawElements).not.toHaveBeenCalled();
+  });
+
+  it('returns early without drawing when particleCount is 0', () => {
+    const { state, gl } = createGlState();
+    drawGlParticleEmitter(state, makeParticleEmitterNode({ particleCount: 0 }));
+    expect(gl.drawElementsInstanced).not.toHaveBeenCalled();
+  });
+
+  it('draws all live particles in a single instanced draw call', () => {
+    const { state, gl } = createGlState();
+    drawGlParticleEmitter(
+      state,
+      makeParticleEmitterNode({
+        particleCount: 3,
+        ids: new Uint16Array([0, 0, 0]),
+        transforms: new Float32Array([0, 0, 0, 1, 10, 10, 0, 1, 20, 20, 0, 1]),
+        alphas: new Float32Array([1, 0.5, 0.25]),
+        colors: new Float32Array([1, 1, 1, 1, 1, 1, 1, 1, 1]),
+      }),
+    );
+    expect(gl.drawElementsInstanced).toHaveBeenCalledTimes(1);
+    expect(gl.drawElementsInstanced).toHaveBeenCalledWith(expect.anything(), 6, expect.anything(), 0, 3);
+  });
+
+  it('skips out-of-range region ids and draws only valid particles', () => {
+    const { state, gl } = createGlState();
+    drawGlParticleEmitter(
+      state,
+      makeParticleEmitterNode({
+        particleCount: 3,
+        ids: new Uint16Array([0, 99, 0]),
+        transforms: new Float32Array([0, 0, 0, 1, 10, 10, 0, 1, 20, 20, 0, 1]),
+        alphas: new Float32Array([1, 1, 1]),
+        colors: new Float32Array([1, 1, 1, 1, 1, 1, 1, 1, 1]),
+      }),
+    );
+    expect(gl.drawElementsInstanced).toHaveBeenCalledWith(expect.anything(), 6, expect.anything(), 0, 2);
+  });
+});

package/src/glQuadBatch.test.ts

@@ -0,0 +1,132 @@
+import type { RenderProxy2D } from '@flighthq/types';
+
+import { registerDefaultGlMaterial } from './glDefaultMaterial';
+import { defaultGlQuadBatchRenderer } from './glQuadBatch';
+import { flushGlSpriteBatch } from './glSpriteBatch';
+import { createGlState } from './glTestHelper';
+
+function makeAtlas() {
+  const img = document.createElement('img');
+  return {
+    image: { source: img, width: 64, height: 64 },
+    regions: [{ x: 0, y: 0, width: 32, height: 32 }],
+  };
+}
+
+function makeQuadBatchNode(data: Record<string, unknown> = {}): RenderProxy2D {
+  return {
+    source: {
+      data: {
+        atlas: makeAtlas(),
+        instanceCount: 1,
+        ids: new Int32Array([0]),
+        transforms: new Float32Array([0, 0]),
+        transformType: 'vector2',
+        ...data,
+      },
+    },
+    blendMode: 0,
+    alpha: 1,
+    material: null,
+    materialData: null,
+    renderer: null,
+    traverseChildren: false,
+    transform2D: { a: 1, b: 0, c: 0, d: 1, tx: 0, ty: 0 },
+  } as unknown as RenderProxy2D;
+}
+
+describe('defaultGlQuadBatchRenderer', () => {
+  it('has a createData function', () => {
+    expect(typeof defaultGlQuadBatchRenderer.createData).toBe('function');
+  });
+
+  it('has a submit function', () => {
+    expect(typeof defaultGlQuadBatchRenderer.submit).toBe('function');
+  });
+});
+
+describe('defaultGlQuadBatchRenderer.submit', () => {
+  it('returns early without drawing when atlas is null', () => {
+    const { state, gl } = createGlState();
+    registerDefaultGlMaterial(state);
+    defaultGlQuadBatchRenderer.submit(state, makeQuadBatchNode({ atlas: null }));
+    flushGlSpriteBatch(state as any);
+    expect(gl.drawElementsInstanced).not.toHaveBeenCalled();
+  });
+
+  it('returns early without drawing when atlas.image is null', () => {
+    const { state, gl } = createGlState();
+    registerDefaultGlMaterial(state);
+    defaultGlQuadBatchRenderer.submit(state, makeQuadBatchNode({ atlas: { image: null, regions: [] } }));
+    flushGlSpriteBatch(state as any);
+    expect(gl.drawElementsInstanced).not.toHaveBeenCalled();
+  });
+
+  it('returns early without drawing when atlas.image.source is null', () => {
+    const { state, gl } = createGlState();
+    registerDefaultGlMaterial(state);
+    defaultGlQuadBatchRenderer.submit(state, makeQuadBatchNode({ atlas: { image: { source: null }, regions: [] } }));
+    flushGlSpriteBatch(state as any);
+    expect(gl.drawElementsInstanced).not.toHaveBeenCalled();
+  });
+
+  it('returns early without drawing when instanceCount is 0', () => {
+    const { state, gl } = createGlState();
+    registerDefaultGlMaterial(state);
+    defaultGlQuadBatchRenderer.submit(state, makeQuadBatchNode({ instanceCount: 0 }));
+    flushGlSpriteBatch(state as any);
+    expect(gl.drawElementsInstanced).not.toHaveBeenCalled();
+  });
+
+  it('draws all valid instances in a single instanced call with vector2 transform type', () => {
+    const { state, gl } = createGlState();
+    registerDefaultGlMaterial(state);
+    defaultGlQuadBatchRenderer.submit(
+      state,
+      makeQuadBatchNode({
+        instanceCount: 2,
+        ids: new Int32Array([0, 0]),
+        transforms: new Float32Array([0, 0, 10, 20]),
+        transformType: 'vector2',
+      }),
+    );
+    flushGlSpriteBatch(state as any);
+    expect(gl.drawElementsInstanced).toHaveBeenCalledTimes(1);
+    expect(gl.drawElementsInstanced).toHaveBeenCalledWith(expect.anything(), 6, expect.anything(), 0, 2);
+  });
+
+  it('excludes out-of-range ids from the instanced draw count', () => {
+    const { state, gl } = createGlState();
+    registerDefaultGlMaterial(state);
+    defaultGlQuadBatchRenderer.submit(
+      state,
+      makeQuadBatchNode({
+        instanceCount: 3,
+        ids: new Int32Array([0, 99, 0]),
+        transforms: new Float32Array([0, 0, 0, 0, 0, 0]),
+        transformType: 'vector2',
+      }),
+    );
+    flushGlSpriteBatch(state as any);
+    expect(gl.drawElementsInstanced).toHaveBeenCalledTimes(1);
+    expect(gl.drawElementsInstanced).toHaveBeenCalledWith(expect.anything(), 6, expect.anything(), 0, 2);
+  });
+
+  it('draws all valid instances in a single instanced call with full matrix transform type', () => {
+    const { state, gl } = createGlState();
+    registerDefaultGlMaterial(state);
+    const transforms = new Float32Array([1, 0, 0, 1, 0, 0]);
+    defaultGlQuadBatchRenderer.submit(
+      state,
+      makeQuadBatchNode({
+        instanceCount: 1,
+        ids: new Int32Array([0]),
+        transforms,
+        transformType: 'matrix',
+      }),
+    );
+    flushGlSpriteBatch(state as any);
+    expect(gl.drawElementsInstanced).toHaveBeenCalledTimes(1);
+    expect(gl.drawElementsInstanced).toHaveBeenCalledWith(expect.anything(), 6, expect.anything(), 0, 1);
+  });
+});