@flighthq/scene3d-gl 0.2.1-next.840.857425c

package/src/glMeshUpload.test.ts

@@ -0,0 +1,311 @@
+import {
+  createBoxMeshGeometry,
+  createMeshGeometry,
+  setMeshGeometrySkinBindPose,
+  updateMeshMorph,
+} from '@flighthq/mesh';
+import { createMesh } from '@flighthq/scene3d';
+import type { Mesh, MeshMorph, MeshSkinBindPose, VertexAttributeLayout, GlMeshUpload } from '@flighthq/types';
+
+import { destroyGlMeshUpload, ensureGlMeshUpload } from './glMeshUpload';
+import { getGlScene3DRuntime } from './glScene3DRuntime';
+import { makeGlScene3DState } from './glScene3DTestHelper';
+
+describe('destroyGlMeshUpload', () => {
+  it('deletes the VAO and the vertex + index buffers of an indexed upload', () => {
+    const { state, gl } = makeGlScene3DState();
+    const upload = ensureGlMeshUpload(state, createBoxMeshGeometry());
+    destroyGlMeshUpload(state, upload);
+    expect(gl.calls.filter((c) => c.name === 'deleteVertexArray').length).toBe(1);
+    expect(gl.calls.filter((c) => c.name === 'deleteBuffer').length).toBe(2);
+  });
+
+  it('skips the index buffer when the upload is non-indexed', () => {
+    const { state, gl } = makeGlScene3DState();
+    const upload: GlMeshUpload = {
+      indexBuffer: null,
+      indexCount: 0,
+      indexType: gl.UNSIGNED_SHORT,
+      primitiveMode: gl.TRIANGLES,
+      vao: {} as WebGLVertexArrayObject,
+      version: 0,
+      vertexBuffer: {} as WebGLBuffer,
+    };
+    destroyGlMeshUpload(state, upload);
+    expect(gl.calls.filter((c) => c.name === 'deleteVertexArray').length).toBe(1);
+    expect(gl.calls.filter((c) => c.name === 'deleteBuffer').length).toBe(1);
+  });
+});
+
+describe('ensureGlMeshUpload', () => {
+  it('uploads vertex + index buffers into a VAO and reports the indexed draw shape', () => {
+    const { state, gl } = makeGlScene3DState();
+    const geometry = createBoxMeshGeometry();
+    const upload = ensureGlMeshUpload(state, geometry);
+
+    expect(upload.vao).not.toBeNull();
+    expect(upload.vertexBuffer).not.toBeNull();
+    expect(upload.indexBuffer).not.toBeNull();
+    expect(upload.indexCount).toBe(geometry.indices!.length);
+    const expectedType = geometry.indices instanceof Uint32Array ? gl.UNSIGNED_INT : gl.UNSIGNED_SHORT;
+    expect(upload.indexType).toBe(expectedType);
+    expect(upload.version).toBe(geometry.version);
+    expect(upload.primitiveMode).toBe(gl.TRIANGLES);
+    expect(gl.calls.some((c) => c.name === 'bufferData')).toBe(true);
+  });
+
+  it('reports the vertex count for a non-indexed upload', () => {
+    const { state, gl } = makeGlScene3DState();
+    const layout: VertexAttributeLayout = {
+      attributes: [{ byteOffset: 0, format: 'float32x3', semantic: 'position' }],
+      stride: 12,
+    };
+    const geometry = createMeshGeometry({ layout, vertices: new Float32Array(9) });
+    const upload = ensureGlMeshUpload(state, geometry);
+
+    expect(upload.indexBuffer).toBeNull();
+    expect(upload.indexCount).toBe(3);
+    expect(upload.primitiveMode).toBe(gl.TRIANGLES);
+  });
+
+  it('refreshes the primitive mode on a cached upload without re-uploading buffers', () => {
+    const { state, gl } = makeGlScene3DState();
+    const geometry = createBoxMeshGeometry();
+    const upload = ensureGlMeshUpload(state, geometry);
+    const bufferDataCount = gl.calls.filter((call) => call.name === 'bufferData').length;
+
+    geometry.topology = 'triangle-strip';
+    const reused = ensureGlMeshUpload(state, geometry);
+
+    expect(reused).toBe(upload);
+    expect(reused.primitiveMode).toBe(gl.TRIANGLE_STRIP);
+    expect(gl.calls.filter((call) => call.name === 'bufferData').length).toBe(bufferDataCount);
+  });
+
+  it('deletes an obsolete index buffer when geometry becomes non-indexed', () => {
+    const { state, gl } = makeGlScene3DState();
+    const geometry = createBoxMeshGeometry();
+    const upload = ensureGlMeshUpload(state, geometry);
+    expect(upload.indexBuffer).not.toBeNull();
+
+    geometry.indices = null;
+    geometry.version++;
+    ensureGlMeshUpload(state, geometry);
+
+    expect(upload.indexBuffer).toBeNull();
+    expect(gl.calls.filter((call) => call.name === 'deleteBuffer').length).toBe(1);
+  });
+
+  it('caches by geometry and reuses the upload when the version is unchanged', () => {
+    const { state, gl } = makeGlScene3DState();
+    const geometry = createBoxMeshGeometry();
+    const first = ensureGlMeshUpload(state, geometry);
+    const bufferDataCount = gl.calls.filter((c) => c.name === 'bufferData').length;
+    const second = ensureGlMeshUpload(state, geometry);
+    expect(second).toBe(first);
+    // No re-upload: bufferData not called again, only the VAO re-bound.
+    expect(gl.calls.filter((c) => c.name === 'bufferData').length).toBe(bufferDataCount);
+    expect(getGlScene3DRuntime(state).uploadCache.get(geometry)).toBe(first);
+  });
+
+  it('re-uploads when the geometry version is bumped, reusing the GL objects', () => {
+    const { state, gl } = makeGlScene3DState();
+    const geometry = createBoxMeshGeometry();
+    const first = ensureGlMeshUpload(state, geometry);
+    geometry.version++;
+    const bufferDataCount = gl.calls.filter((c) => c.name === 'bufferData').length;
+    const second = ensureGlMeshUpload(state, geometry);
+    expect(second).toBe(first);
+    expect(second.vao).toBe(first.vao);
+    expect(gl.calls.filter((c) => c.name === 'bufferData').length).toBeGreaterThan(bufferDataCount);
+    expect(second.version).toBe(geometry.version);
+  });
+
+  it('converts packed integer storage into the float inputs declared by mesh shaders', () => {
+    const { state, gl } = makeGlScene3DState();
+    const layout: VertexAttributeLayout = {
+      attributes: [
+        { byteOffset: 0, format: 'float32x3', semantic: 'position' },
+        { byteOffset: 12, format: 'uint8x4', semantic: 'joints0' },
+        { byteOffset: 16, format: 'unorm8x4', semantic: 'weights0' },
+      ],
+      stride: 20,
+    };
+    ensureGlMeshUpload(state, createMeshGeometry({ layout, vertices: new Float32Array(5) }));
+
+    const jointCall = gl.calls.find((call) => call.name === 'vertexAttribPointer' && call.args[0] === 6);
+    const weightCall = gl.calls.find((call) => call.name === 'vertexAttribPointer' && call.args[0] === 7);
+    expect(jointCall?.args.slice(1)).toEqual([4, gl.UNSIGNED_BYTE, false, 20, 12]);
+    expect(weightCall?.args.slice(1)).toEqual([4, gl.UNSIGNED_BYTE, true, 20, 16]);
+    expect(gl.calls.some((call) => call.name === 'vertexAttribIPointer')).toBe(false);
+  });
+
+  // The double-skinning fix: a GPU-skinned draw must upload the STATIC bind pose, not the CPU-posed
+  // geometry.vertices updateMeshSkin writes each frame — else the shader would skin an already-skinned
+  // vertex (M²). Captures the box's original positions as the bind pose, then displaces every vertex to
+  // simulate a CPU pose and asserts the uploaded buffer carries the bind position, not the displaced one.
+  it('uploads the skin bind pose (not the CPU-posed vertices) for a GPU-skinned draw', () => {
+    const { state, gl } = makeGlScene3DState();
+    const geometry = createBoxMeshGeometry(2, 2, 2);
+    const floatsPerVertex = geometry.layout.stride / 4;
+    const vertexCount = geometry.vertices.length / floatsPerVertex;
+    const positions = new Float32Array(vertexCount * 3);
+    const normals = new Float32Array(vertexCount * 3);
+    for (let v = 0; v < vertexCount; v++) {
+      const b = v * floatsPerVertex;
+      positions[v * 3] = geometry.vertices[b]!;
+      positions[v * 3 + 1] = geometry.vertices[b + 1]!;
+      positions[v * 3 + 2] = geometry.vertices[b + 2]!;
+      normals[v * 3] = geometry.vertices[b + 3]!;
+      normals[v * 3 + 1] = geometry.vertices[b + 4]!;
+      normals[v * 3 + 2] = geometry.vertices[b + 5]!;
+    }
+    const bindPose: MeshSkinBindPose = {
+      joints: new Float32Array(0),
+      normals,
+      positions,
+      skinnedNormals: new Float32Array(0),
+      skinnedPositions: new Float32Array(0),
+      weights: new Float32Array(0),
+    };
+    setMeshGeometrySkinBindPose(geometry, bindPose);
+    // Simulate updateMeshSkin having posed the vertices: shift every position by +1000.
+    for (let b = 0; b < geometry.vertices.length; b += floatsPerVertex) geometry.vertices[b] += 1000;
+    geometry.version++;
+
+    ensureGlMeshUpload(state, geometry, true);
+    const uploaded = gl.calls
+      .filter((c) => c.name === 'bufferData')
+      .map((c) => c.args[1])
+      .find((data): data is Float32Array => data instanceof Float32Array)!;
+    // Vertex 0's uploaded position.x is the bind value, not the +1000 CPU-posed value.
+    expect(uploaded[0]).toBeCloseTo(positions[0]!);
+    expect(uploaded[0]).not.toBeCloseTo(positions[0]! + 1000);
+  });
+
+  it('reuses the bind-pose upload across version bumps for a GPU-skinned draw (no per-frame re-skin)', () => {
+    const { state, gl } = makeGlScene3DState();
+    const geometry = createBoxMeshGeometry(2, 2, 2);
+    const floatsPerVertex = geometry.layout.stride / 4;
+    const vertexCount = geometry.vertices.length / floatsPerVertex;
+    const positions = new Float32Array(vertexCount * 3);
+    for (let v = 0; v < vertexCount; v++) {
+      const b = v * floatsPerVertex;
+      positions[v * 3] = geometry.vertices[b]!;
+      positions[v * 3 + 1] = geometry.vertices[b + 1]!;
+      positions[v * 3 + 2] = geometry.vertices[b + 2]!;
+    }
+    setMeshGeometrySkinBindPose(geometry, {
+      joints: new Float32Array(0),
+      normals: new Float32Array(vertexCount * 3),
+      positions,
+      skinnedNormals: new Float32Array(0),
+      skinnedPositions: new Float32Array(0),
+      weights: new Float32Array(0),
+    });
+    ensureGlMeshUpload(state, geometry, true);
+    const afterFirst = gl.calls.filter((c) => c.name === 'bufferData').length;
+    geometry.version++; // a per-frame updateMeshSkin bump
+    ensureGlMeshUpload(state, geometry, true);
+    // The static bind buffer is not re-uploaded on the version bump.
+    expect(gl.calls.filter((c) => c.name === 'bufferData').length).toBe(afterFirst);
+  });
+
+  // Morph + skin compose on GPU: when a geometry is both morphed and GPU-skinned, the per-frame morphed
+  // vertices (not the frozen skin bind pose) are what the shader skins, and they re-upload each frame.
+  it('uploads the morphed vertices (not the frozen skin bind pose) for a morphed + GPU-skinned draw', () => {
+    const { state, gl } = makeGlScene3DState();
+    const geometry = createMeshGeometry({
+      layout: { attributes: [{ byteOffset: 0, format: 'float32x3', semantic: 'position' }], stride: 12 },
+      vertices: new Float32Array([1, 0, 0]),
+    });
+    // A captured skin bind pose at the rest position x = 1 — what the freeze would pin the buffer to.
+    setMeshGeometrySkinBindPose(geometry, {
+      joints: new Float32Array(0),
+      normals: new Float32Array(3),
+      positions: new Float32Array([1, 0, 0]),
+      skinnedNormals: new Float32Array(0),
+      skinnedPositions: new Float32Array(0),
+      weights: new Float32Array(0),
+    });
+
+    // prepareScene3DMorph blends the morph into geometry.vertices (x → 5) and captures the morph bind pose.
+    const mesh = { geometry, materials: [], morph: undefined } as unknown as Mesh;
+    mesh.morph = {
+      targets: [{ normalDeltas: null, positionDeltas: new Float32Array([4, 0, 0]), tangentDeltas: null }],
+      weights: new Float32Array([1]),
+    };
+    updateMeshMorph(mesh);
+
+    ensureGlMeshUpload(state, geometry, true);
+    const firstUpload = lastFloat32BufferData(gl.calls);
+    // The morphed value (5), NOT the frozen skin bind (1): the morph is not discarded.
+    expect(firstUpload[0]).toBeCloseTo(5);
+
+    const uploadsAfterFirst = gl.calls.filter((c) => c.name === 'bufferData').length;
+
+    // A moving morph weight re-uploads the freshly-morphed bind (x → 9), unlike the skin-only freeze.
+    mesh.morph!.weights[0] = 2;
+    updateMeshMorph(mesh);
+    ensureGlMeshUpload(state, geometry, true);
+    expect(gl.calls.filter((c) => c.name === 'bufferData').length).toBeGreaterThan(uploadsAfterFirst);
+    expect(lastFloat32BufferData(gl.calls)[0]).toBeCloseTo(9);
+  });
+
+  // The GL vertex morph path is CPU-blend-then-upload: updateMeshMorph blends base + Σ wᵢ·targetᵢ into
+  // geometry.vertices and bumps the version, and ensureGlMeshUpload (the non-skinned path) re-uploads the
+  // deformed vertices — no HAS_MORPH shader permutation. (Folded from the former glMeshMorph.test.ts,
+  // whose source lives here in glMeshUpload.ts.)
+  it('uploads the morph-blended vertices for a morphed mesh (CPU-blend-then-upload GL path)', () => {
+    const { state, gl } = makeGlScene3DState();
+    const layout: VertexAttributeLayout = {
+      attributes: [{ byteOffset: 0, format: 'float32x3', semantic: 'position' }],
+      stride: 12,
+    };
+    const geometry = createMeshGeometry({ layout, vertices: new Float32Array([0, 0, 0, 1, 0, 0]) });
+    const morph: MeshMorph = {
+      targets: [{ normalDeltas: null, positionDeltas: new Float32Array([0, 5, 0, 0, 5, 0]), tangentDeltas: null }],
+      weights: new Float32Array([1]),
+    };
+    const mesh = createMesh(geometry, []);
+    mesh.morph = morph;
+
+    ensureGlMeshUpload(state, geometry, false); // first upload before morph blends
+    updateMeshMorph(mesh); // weight 1 raises both vertices by 5 in y
+    ensureGlMeshUpload(state, geometry, false);
+
+    expect(Array.from(lastFloat32BufferData(gl.calls))).toEqual([0, 5, 0, 1, 5, 0]);
+  });
+
+  it('re-uploads as the morph weights change frame to frame', () => {
+    const { state, gl } = makeGlScene3DState();
+    const layout: VertexAttributeLayout = {
+      attributes: [{ byteOffset: 0, format: 'float32x3', semantic: 'position' }],
+      stride: 12,
+    };
+    const geometry = createMeshGeometry({ layout, vertices: new Float32Array([0, 0, 0]) });
+    const morph: MeshMorph = {
+      targets: [{ normalDeltas: null, positionDeltas: new Float32Array([2, 0, 0]), tangentDeltas: null }],
+      weights: new Float32Array([1]),
+    };
+    const mesh = createMesh(geometry, []);
+    mesh.morph = morph;
+
+    updateMeshMorph(mesh);
+    ensureGlMeshUpload(state, geometry, false);
+    expect(Array.from(lastFloat32BufferData(gl.calls))).toEqual([2, 0, 0]);
+
+    morph.weights[0] = 0.5;
+    updateMeshMorph(mesh);
+    ensureGlMeshUpload(state, geometry, false);
+    expect(Array.from(lastFloat32BufferData(gl.calls))).toEqual([1, 0, 0]);
+  });
+});
+
+function lastFloat32BufferData(calls: readonly { name: string; args: readonly unknown[] }[]): Float32Array {
+  const data = calls
+    .filter((c) => c.name === 'bufferData')
+    .map((c) => c.args[1])
+    .filter((d): d is Float32Array => d instanceof Float32Array);
+  return data[data.length - 1]!;
+}

package/src/glParticleEmitter3D.test.ts

@@ -0,0 +1,280 @@
+import { createCamera3D } from '@flighthq/camera';
+import { createMatrix4, setVector3 } from '@flighthq/geometry';
+import { addNodeChild, invalidateNodeLocalTransform } from '@flighthq/node';
+import { createParticleEmitter3D, reserveParticleEmitter3D } from '@flighthq/particleemitter';
+import { createNode3D, Node3DKind } from '@flighthq/scene3d';
+import type { ParticleEmitter3D, Scene3DLightsLike } from '@flighthq/types';
+
+import { destroyGlParticleEmitter3DShader, drawGlScene3DParticleEmitter3Ds } from './glParticleEmitter3D';
+import { makeGlScene3DState } from './glScene3DTestHelper';
+
+function makeCamera() {
+  const cam = createCamera3D({
+    far: 100,
+    near: 0.1,
+    projection: { aspect: 1, fovY: Math.PI / 3, kind: 'perspective' },
+  });
+  cam.view = createMatrix4();
+  return cam;
+}
+
+function makeLights(): Scene3DLightsLike {
+  return { ambient: null, directional: null };
+}
+
+function makeEmitterWithParticles(count: number): ParticleEmitter3D {
+  const emitter = createParticleEmitter3D();
+  reserveParticleEmitter3D(emitter, count);
+  const data = emitter.data;
+  data.particleCount = count;
+  for (let i = 0; i < count; i++) {
+    const tt = i * 4;
+    data.transforms[tt] = i;
+    data.transforms[tt + 1] = i * 2;
+    data.transforms[tt + 2] = 0;
+    data.transforms[tt + 3] = 1;
+    data.positionsZ[i] = i * 3;
+    data.alphas[i] = 1;
+    const ct = i * 3;
+    data.colors[ct] = 1;
+    data.colors[ct + 1] = 1;
+    data.colors[ct + 2] = 1;
+    data.ids[i] = 0;
+  }
+  return emitter;
+}
+
+// A single-particle emitter carrying a texture atlas whose sole region is regionWidth×regionHeight
+// pixels within a 128×128 image. Exercises the atlas draw path — texture upload/bind and quad-size
+// normalization — that the plain makeEmitterWithParticles (atlas === null) never reaches.
+function makeAtlasEmitter(regionWidth: number, regionHeight: number): ParticleEmitter3D {
+  const emitter = makeEmitterWithParticles(1);
+  const img = document.createElement('img');
+  emitter.data.atlas = {
+    image: { source: img, width: 128, height: 128 },
+    regions: [{ id: 0, x: 0, y: 0, width: regionWidth, height: regionHeight }],
+  } as unknown as NonNullable<ParticleEmitter3D['data']['atlas']>;
+  return emitter;
+}
+
+describe('destroyGlParticleEmitter3DShader', () => {
+  it('is a no-op when no shader was created', () => {
+    const { state } = makeGlScene3DState();
+    expect(() => destroyGlParticleEmitter3DShader(state)).not.toThrow();
+  });
+
+  it('deletes GPU resources after a draw', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    const emitter = makeEmitterWithParticles(1);
+    addNodeChild(scene, emitter);
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    destroyGlParticleEmitter3DShader(state);
+    expect(gl.calls.some((c) => c.name === 'deleteProgram')).toBe(true);
+    expect(gl.calls.filter((c) => c.name === 'deleteBuffer').length).toBeGreaterThanOrEqual(3);
+  });
+});
+
+describe('drawGlScene3DParticleEmitter3Ds', () => {
+  it('is a no-op when scene has no particle emitter 3D nodes', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    expect(gl.calls.some((c) => c.name === 'drawElementsInstanced')).toBe(false);
+  });
+
+  it('skips emitters with zero particles', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    const emitter = createParticleEmitter3D();
+    addNodeChild(scene, emitter);
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    expect(gl.calls.some((c) => c.name === 'drawElementsInstanced')).toBe(false);
+  });
+
+  it('issues an instanced draw for particles', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    const emitter = makeEmitterWithParticles(5);
+    addNodeChild(scene, emitter);
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    const draw = gl.calls.find((c) => c.name === 'drawElementsInstanced');
+    expect(draw).toBeDefined();
+    expect(draw!.args[4]).toBe(5);
+  });
+
+  it('applies the emitter node world transform for local-space particles', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    const emitter = makeEmitterWithParticles(1);
+    emitter.data.transforms[0] = 1;
+    emitter.data.transforms[1] = 2;
+    emitter.data.positionsZ[0] = 3;
+    setVector3(emitter.position, 10, 20, 30);
+    invalidateNodeLocalTransform(emitter);
+    addNodeChild(scene, emitter);
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    const instanceData = gl.calls.find((c) => c.name === 'bufferSubData')!.args[2] as Float32Array;
+    // Local particles ride the emitter node: local (1,2,3) + node translation (10,20,30).
+    expect(instanceData[0]).toBeCloseTo(11);
+    expect(instanceData[1]).toBeCloseTo(22);
+    expect(instanceData[2]).toBeCloseTo(33);
+  });
+
+  it('skips the node world transform for world-space particles already baked into world coordinates', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    const emitter = makeEmitterWithParticles(1);
+    emitter.data.transforms[0] = 1;
+    emitter.data.transforms[1] = 2;
+    emitter.data.positionsZ[0] = 3;
+    setVector3(emitter.position, 10, 20, 30);
+    invalidateNodeLocalTransform(emitter);
+    emitter.data.worldSpace = true;
+    addNodeChild(scene, emitter);
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    const instanceData = gl.calls.find((c) => c.name === 'bufferSubData')!.args[2] as Float32Array;
+    // World-space particles already hold world coordinates, so the node translation must NOT be
+    // re-applied: the instance position stays at the baked (1,2,3).
+    expect(instanceData[0]).toBeCloseTo(1);
+    expect(instanceData[1]).toBeCloseTo(2);
+    expect(instanceData[2]).toBeCloseTo(3);
+  });
+
+  it('compiles the shader program on first call', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeEmitterWithParticles(1));
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    expect(gl.calls.some((c) => c.name === 'createProgram')).toBe(true);
+  });
+
+  it('reuses the shader program on subsequent calls', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeEmitterWithParticles(1));
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    const programCount = gl.calls.filter((c) => c.name === 'createProgram').length;
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    expect(gl.calls.filter((c) => c.name === 'createProgram').length).toBe(programCount);
+  });
+
+  it('enables depth test and alpha blending', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeEmitterWithParticles(1));
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    expect(gl.calls.some((c) => c.name === 'enable' && c.args[0] === gl.DEPTH_TEST)).toBe(true);
+    expect(gl.calls.some((c) => c.name === 'enable' && c.args[0] === gl.BLEND)).toBe(true);
+    expect(gl.calls.some((c) => c.name === 'depthMask' && c.args[0] === false)).toBe(true);
+  });
+
+  it('applies the emitter blend mode: additive for add, premultiplied over-blend for normal', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    const additive = makeEmitterWithParticles(1);
+    additive.blendMode = 'add';
+    const normal = makeEmitterWithParticles(1);
+    addNodeChild(scene, additive);
+    addNodeChild(scene, normal);
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    const blendFuncs = gl.calls.filter((c) => c.name === 'blendFunc');
+    // add: straight ONE/ONE additive sum.
+    expect(blendFuncs.some((c) => c.args[0] === gl.ONE && c.args[1] === gl.ONE)).toBe(true);
+    // normal: premultiplied over-blend (ONE, ONE_MINUS_SRC_ALPHA), NOT SRC_ALPHA — the fragment
+    // shader emits premultiplied color, so SRC_ALPHA would double-apply alpha and darken.
+    expect(blendFuncs.some((c) => c.args[0] === gl.ONE && c.args[1] === gl.ONE_MINUS_SRC_ALPHA)).toBe(true);
+    expect(blendFuncs.some((c) => c.args[0] === gl.SRC_ALPHA)).toBe(false);
+  });
+
+  it('uploads and binds the atlas image (never a null texture) for textured particles', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeAtlasEmitter(64, 32));
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    // The atlas image is uploaded to a GL texture on first use.
+    expect(gl.calls.some((c) => c.name === 'texImage2D')).toBe(true);
+    // Every texture bind targets a real texture object. Binding null here — as the bug did — leaves
+    // an incomplete sampler that reads (0,0,0,1), turning each particle into a solid black quad.
+    const textureBinds = gl.calls.filter((c) => c.name === 'bindTexture');
+    expect(textureBinds.length).toBeGreaterThan(0);
+    expect(textureBinds.every((c) => c.args[1] !== null)).toBe(true);
+    // u_hasTexture is signaled on so the fragment shader samples the atlas.
+    expect(
+      gl.calls.some(
+        (c) => c.name === 'uniform1i' && (c.args[0] as { name: string }).name === 'u_hasTexture' && c.args[1] === 1,
+      ),
+    ).toBe(true);
+  });
+
+  it('normalizes the particle quad to an aspect-ratio unit square, not the region pixel size', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    // A 64×32 region: the larger axis normalizes to 1, the shorter to its aspect ratio (0.5). The
+    // raw pixel dims would make a 64-world-unit quad — screen-covering, with crippling overdraw.
+    addNodeChild(scene, makeAtlasEmitter(64, 32));
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    const upload = gl.calls.find((c) => c.name === 'bufferSubData');
+    expect(upload).toBeDefined();
+    const instanceData = upload!.args[2] as Float32Array;
+    // a_size occupies instance floats [13] (width) and [14] (height) of the first particle.
+    expect(instanceData[13]).toBeCloseTo(1);
+    expect(instanceData[14]).toBeCloseTo(0.5);
+  });
+
+  it('does not upload a texture and signals u_hasTexture off for atlas-less emitters', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeEmitterWithParticles(1));
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    expect(gl.calls.some((c) => c.name === 'texImage2D')).toBe(false);
+    expect(
+      gl.calls.some(
+        (c) => c.name === 'uniform1i' && (c.args[0] as { name: string }).name === 'u_hasTexture' && c.args[1] === 0,
+      ),
+    ).toBe(true);
+  });
+
+  it('restores depth write and disables blend after draw', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeEmitterWithParticles(1));
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    const depthMaskCalls = gl.calls.filter((c) => c.name === 'depthMask');
+    expect(depthMaskCalls[depthMaskCalls.length - 1].args[0]).toBe(true);
+    const disableCalls = gl.calls.filter((c) => c.name === 'disable');
+    expect(disableCalls.some((c) => c.args[0] === gl.BLEND)).toBe(true);
+  });
+
+  it('uploads view-projection and camera vectors as uniforms', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeEmitterWithParticles(1));
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    expect(gl.calls.some((c) => c.name === 'uniformMatrix4fv')).toBe(true);
+    const uniform3fCalls = gl.calls.filter((c) => c.name === 'uniform3f');
+    expect(uniform3fCalls.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('draws multiple emitters in one call', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    addNodeChild(scene, makeEmitterWithParticles(3));
+    addNodeChild(scene, makeEmitterWithParticles(7));
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    const draws = gl.calls.filter((c) => c.name === 'drawElementsInstanced');
+    expect(draws.length).toBe(2);
+    expect(draws[0].args[4]).toBe(3);
+    expect(draws[1].args[4]).toBe(7);
+  });
+
+  it('skips disabled emitters', () => {
+    const { state, gl } = makeGlScene3DState();
+    const scene = createNode3D(Node3DKind);
+    const emitter = makeEmitterWithParticles(5);
+    emitter.enabled = false;
+    addNodeChild(scene, emitter);
+    drawGlScene3DParticleEmitter3Ds(state, scene, makeCamera(), makeLights());
+    expect(gl.calls.some((c) => c.name === 'drawElementsInstanced')).toBe(false);
+  });
+});