@bigmistqke/view.gl 0.1.18 → 0.2.0

package/src/types.ts

@@ -285,14 +285,7 @@ export type AttributeKind =
   | 'uvec3'
   | 'uvec4'
 
-export type AttributeFormat =
-  | 'float32'
-  | 'int32'
-  | 'uint32'
-  | 'int16'
-  | 'uint16'
-  | 'int8'
-  | 'uint8'
+export type AttributeFormat = 'float32' | 'int32' | 'uint32' | 'int16' | 'uint16' | 'int8' | 'uint8'
 
 export interface AttributeDefinition {
   kind: AttributeKind
@@ -313,7 +306,9 @@ type DefaultFormat<K extends AttributeKind> = K extends IntKind
     ? 'uint32'
     : 'float32'
 
-type ResolvedFormat<T extends AttributeDefinition> = T extends { format: infer F extends AttributeFormat }
+type ResolvedFormat<T extends AttributeDefinition> = T extends {
+  format: infer F extends AttributeFormat
+}
   ? F
   : DefaultFormat<T['kind']>
 
@@ -327,10 +322,49 @@ type FormatToArray = {
   uint8: Uint8Array
 }
 
-export interface AttributeMethods<T extends AttributeDefinition = AttributeDefinition> {
+/**
+ * What a participant contributes to a vertex array.
+ *
+ * `enableVertexAttribArray`, `vertexAttribPointer`, `vertexAttribDivisor` and
+ * the `ELEMENT_ARRAY_BUFFER` binding all write into whichever vertex array is
+ * bound when they run — they name no destination of their own. That is what
+ * makes them a participant in something rather than a property of themselves,
+ * and why `vao()` exists: it binds the array first, then asks each participant
+ * to write itself in.
+ *
+ * The returned function undoes the write. It is only used where there is no
+ * vertex array to hold the state — a WebGL1 context without
+ * `OES_vertex_array_object` — since a real vertex array is thrown away whole.
+ */
+export interface VertexArrayParticipant {
+  applyToVertexArray(): () => void
+  /**
+   * State the CONTEXT holds rather than the vertex array, re-applied on every
+   * bind because no array can keep it.
+   *
+   * There is exactly one such thing: the current generic vertex attribute
+   * values, which an attribute reads when its array is disabled. The enable
+   * flag saying to read them is vertex-array state; the values themselves are
+   * not. So a constant source splits across the two hooks — and the tempting
+   * optimisation of skipping this when nothing changed would let one draw's
+   * constants leak into the next.
+   */
+  applyToContext?(): void
+}
+
+export interface AttributeMethods<T extends AttributeDefinition = AttributeDefinition>
+  extends VertexArrayParticipant {
   buffer: WebGLBuffer
-  bind(): void
-  set(data: FormatToArray[ResolvedFormat<T>], usage?: GLUsage): { bind(): void }
+  /**
+   * Apply this attribute to the DEFAULT vertex array, returning a disposer.
+   *
+   * Explicitly the default one: these calls have no destination of their own,
+   * so without binding first this would edit whichever array happened to be
+   * bound — and a vertex array keeps what it is given, so the damage would
+   * outlive the call. Use `vao()` to build an array of your own.
+   */
+  bind(): () => void
+  set(data: FormatToArray[ResolvedFormat<T>], usage?: GLUsage): { bind(): () => void }
   dispose(): void
 }
 
@@ -358,12 +392,55 @@ export interface InterleavedAttributeDefinition {
 
 export type InterleavedAttributeSchema = Record<string | symbol, InterleavedAttributeDefinition>
 
+/**
+ * A source is where one draw's values for a layout come from. Both kinds are
+ * participants, so either can go into a `vao()`.
+ */
+export interface Source extends VertexArrayParticipant {
+  /**
+   * Apply this source to the DEFAULT vertex array, returning a disposer. See
+   * `AttributeMethods.bind` — and prefer `vao()`, which is the only way to get
+   * a source and its fellow participants into an array of their own.
+   */
+  bind(): () => void
+}
+
+export interface BufferSource extends Source {
+  /**
+   * The same buffer, stepped once per instance rather than once per vertex.
+   *
+   * A divisor is a property of the draw, not of the data — the same markers
+   * are an instanced fleet in one draw and a single mesh in the next — so it
+   * is chosen here rather than declared in the schema.
+   */
+  perInstance: Source
+  set(data: Float32Array, usage?: GLUsage): void
+}
+
+export interface ConstantAttributeMethods {
+  set(...values: number[]): void
+}
+
+/**
+ * Per-key setters over the same layout the buffer source uses — a constant
+ * attribute is a uniform in all but name, so it is written like one.
+ */
+export type ConstantSource<T extends InterleavedAttributeLayout[]> = Source & {
+  [K in T[number] as K['key'] extends string ? K['key'] : never]: ConstantAttributeMethods
+}
+
 export interface InterleavedAttributeMethods<
   T extends InterleavedAttributeLayout[] = InterleavedAttributeLayout[],
 > {
-  bind(): void
+  buffer: BufferSource
+  constant: ConstantSource<T>
+  dispose(): void
+}
+
+export interface VertexArrayMethods {
+  /** Binds the vertex array, returning a disposer that restores the previous one */
+  bind(): () => void
   unbind(): void
-  set(data: Float32Array, usage?: GLUsage): void
   dispose(): void
 }
 
@@ -384,9 +461,10 @@ export interface BufferDefinition {
 
 export type BufferSchema = Record<string | symbol, BufferDefinition>
 
-export interface BufferMethods {
+export interface BufferMethods extends VertexArrayParticipant {
   set(data: Float32Array | Uint16Array | Uint32Array): void
-  bind(): void
+  /** Binds the buffer, returning a disposer that restores the previous binding */
+  bind(): () => void
   dispose(): void
 }
 
@@ -565,6 +643,16 @@ export type View<T extends ViewSchema = ViewSchema> = {
     : {}
   buffers: T['buffers'] extends BufferSchema ? Prettify<BufferView<T['buffers']>> : {}
   uniforms: T['uniforms'] extends UniformSchema ? Prettify<UniformView<T['uniforms']>> : {}
+  /**
+   * Build a vertex array from the participants one draw needs — its attributes,
+   * its interleaved layouts, its element buffer.
+   *
+   * This is the one member the schema cannot declare, because its input is the
+   * schema's own output. It is also the only place a vertex array is created:
+   * the participants no longer make one each, so which array they end up in is
+   * something you say rather than something you inherit from call order.
+   */
+  vao(participants: VertexArrayParticipant[]): VertexArrayMethods
 }
 
 /**********************************************************************************/

package/test/index.test.ts

@@ -4,6 +4,7 @@ import {
   bufferView,
   interleavedAttributeView,
   uniformView,
+  vaoView,
   view,
 } from '../src/index'
 import type {
@@ -83,10 +84,11 @@ describe('view', () => {
 
     expect(result.interleavedAttributes).toBeDefined()
     expect(result.interleavedAttributes!.data).toBeDefined()
-    expect(result.interleavedAttributes!.data.bind).toBeInstanceOf(Function)
-    expect(result.interleavedAttributes!.data.unbind).toBeInstanceOf(Function)
+    expect(result.interleavedAttributes!.data.buffer.bind).toBeInstanceOf(Function)
+    expect(result.interleavedAttributes!.data.buffer.perInstance.bind).toBeInstanceOf(Function)
+    expect(result.interleavedAttributes!.data.constant.bind).toBeInstanceOf(Function)
     expect(result.interleavedAttributes!.data.dispose).toBeInstanceOf(Function)
-    expect(result.interleavedAttributes!.data.set).toBeInstanceOf(Function)
+    expect(result.interleavedAttributes!.data.buffer.set).toBeInstanceOf(Function)
   })
 
   it('should create a view with buffers', () => {
@@ -166,7 +168,7 @@ describe('view', () => {
     expect(result.attributes![a_position_symbol].bind).toBeInstanceOf(Function)
     
     expect(result.interleavedAttributes![data_symbol]).toBeDefined()
-    expect(result.interleavedAttributes![data_symbol].bind).toBeInstanceOf(Function)
+    expect(result.interleavedAttributes![data_symbol].buffer.bind).toBeInstanceOf(Function)
     
     expect(result.buffers![vertices_symbol]).toBeDefined()
     expect(result.buffers![vertices_symbol].bind).toBeInstanceOf(Function)
@@ -409,6 +411,64 @@ describe('attributeView', () => {
     expect(gl.vertexAttribDivisor).toHaveBeenCalledWith(expect.any(Number), 1)
   })
 
+  it('should return a disposer from bind that clears the instancing divisor', () => {
+    const schema = {
+      a_instancePosition: { kind: 'vec3', instanced: true },
+    } satisfies AttributeSchema
+
+    const attributes = attributeView(gl, program, schema)
+
+    // The divisor is global to the location rather than to the program, so
+    // leaving it at 1 makes the next non-instanced attribute bound there read
+    // a single value for every vertex.
+    const unbind = attributes.a_instancePosition.bind()
+    expect(gl.vertexAttribDivisor).toHaveBeenCalledWith(expect.any(Number), 1)
+
+    unbind()
+    expect(gl.vertexAttribDivisor).toHaveBeenLastCalledWith(expect.any(Number), 0)
+  })
+
+  it('should state a zero divisor for non-instanced attributes rather than inherit one', () => {
+    const schema = {
+      a_position: { kind: 'vec2' },
+    } satisfies AttributeSchema
+
+    const attributes = attributeView(gl, program, schema)
+
+    // A location left at 1 by an earlier instanced attribute would otherwise
+    // feed a single value to every vertex here.
+    attributes.a_position.bind()
+    expect(gl.vertexAttribDivisor).toHaveBeenCalledWith(expect.any(Number), 0)
+  })
+
+  it('should restore the previous divisor rather than assume it was zero', () => {
+    const schema = {
+      a_instancePosition: { kind: 'vec3', instanced: true },
+    } satisfies AttributeSchema
+
+    const attributes = attributeView(gl, program, schema)
+    ;(gl.getVertexAttrib as any).mockReturnValue(2)
+
+    const unbind = attributes.a_instancePosition.bind()
+    unbind()
+    expect(gl.vertexAttribDivisor).toHaveBeenLastCalledWith(expect.any(Number), 2)
+  })
+
+  it('should return a disposer that only restores once', () => {
+    const schema = {
+      a_instancePosition: { kind: 'vec3', instanced: true },
+    } satisfies AttributeSchema
+
+    const attributes = attributeView(gl, program, schema)
+
+    const unbind = attributes.a_instancePosition.bind()
+    unbind()
+    const callsAfterFirst = (gl.vertexAttribDivisor as any).mock.calls.length
+    // Undoing twice would put back state a later bind() is relying on.
+    unbind()
+    expect((gl.vertexAttribDivisor as any).mock.calls).toHaveLength(callsAfterFirst)
+  })
+
   it('should use custom buffer if provided', () => {
     const customBuffer = gl.createBuffer()!
     const schema = {
@@ -720,10 +780,38 @@ describe('interleavedAttributeView', () => {
     const interleavedAttributes = interleavedAttributeView(gl, program, schema)
 
     expect(interleavedAttributes.vertexData).toBeDefined()
-    expect(interleavedAttributes.vertexData.bind).toBeInstanceOf(Function)
-    expect(interleavedAttributes.vertexData.unbind).toBeInstanceOf(Function)
+    expect(interleavedAttributes.vertexData.buffer.bind).toBeInstanceOf(Function)
+    expect(interleavedAttributes.vertexData.buffer.perInstance.bind).toBeInstanceOf(Function)
     expect(interleavedAttributes.vertexData.dispose).toBeInstanceOf(Function)
-    expect(interleavedAttributes.vertexData.set).toBeInstanceOf(Function)
+    expect(interleavedAttributes.vertexData.buffer.set).toBeInstanceOf(Function)
+  })
+
+  it('should return a disposer from bind that restores the default vertex array', () => {
+    const schema = {
+      vertexData: {
+        layout: [
+          { key: 'a_position', kind: 'vec3' },
+          { key: 'a_color', kind: 'vec4' },
+        ],
+        instanced: true,
+      },
+    } satisfies InterleavedAttributeSchema
+
+    const interleavedAttributes = interleavedAttributeView(gl, program, schema)
+
+    // A bound vertex array stays selected for everything drawn afterwards, so
+    // the next draw would write its own attributes into THIS array and corrupt
+    // the layer that owns it. The disposer hands the default back.
+    // Restoring the previous array rather than null keeps nested binds working.
+    const previous = { id: 'previously-bound-vao' }
+    ;(gl.getParameter as any).mockReturnValue(previous)
+
+    const unbind = interleavedAttributes.vertexData.buffer.bind()
+    expect(unbind).toBeInstanceOf(Function)
+
+    ;(gl.bindVertexArray as any).mockClear()
+    unbind()
+    expect(gl.bindVertexArray).toHaveBeenCalledWith(previous)
   })
 
   it('should calculate correct stride and offsets', () => {
@@ -740,7 +828,7 @@ describe('interleavedAttributeView', () => {
 
     const interleavedAttributes = interleavedAttributeView(gl, program, schema)
 
-    interleavedAttributes.vertexData.bind()
+    interleavedAttributes.vertexData.buffer.bind()
 
     // Check vertexAttribPointer calls
     const calls = (gl.vertexAttribPointer as any).mock.calls
@@ -764,23 +852,28 @@ describe('interleavedAttributeView', () => {
     expect(calls[2][5]).toBe(24) // offset
   })
 
-  it('should handle instanced interleaved attributes', () => {
+  it('steps per instance or per vertex from the same buffer', () => {
+    // A divisor is a property of the draw, not of the data, so it is chosen
+    // here rather than declared in the schema.
     const schema = {
       instanceData: {
         layout: [
           { key: 'a_instancePos', kind: 'vec3' },
           { key: 'a_instanceScale', kind: 'float' },
         ],
-        instanced: true,
       },
     } satisfies InterleavedAttributeSchema
 
     const interleavedAttributes = interleavedAttributeView(gl, program, schema)
 
-    interleavedAttributes.instanceData.bind()
-
+    interleavedAttributes.instanceData.buffer.perInstance.bind()
     expect(gl.vertexAttribDivisor).toHaveBeenCalledTimes(2)
     expect(gl.vertexAttribDivisor).toHaveBeenCalledWith(expect.any(Number), 1)
+
+    vi.mocked(gl.vertexAttribDivisor).mockClear()
+
+    interleavedAttributes.instanceData.buffer.bind()
+    expect(gl.vertexAttribDivisor).toHaveBeenCalledWith(expect.any(Number), 0)
   })
 
   it('should handle integer attributes in layout', () => {
@@ -797,7 +890,7 @@ describe('interleavedAttributeView', () => {
 
     const interleavedAttributes = interleavedAttributeView(gl, program, schema)
 
-    interleavedAttributes.data.bind()
+    interleavedAttributes.data.buffer.bind()
 
     const floatCalls = (gl.vertexAttribPointer as any).mock.calls
     const intCalls = (gl.vertexAttribIPointer as any).mock.calls
@@ -822,7 +915,7 @@ describe('interleavedAttributeView', () => {
     } satisfies InterleavedAttributeSchema
 
     const interleavedAttributes = interleavedAttributeView(gl, program, schema)
-    interleavedAttributes.data.bind()
+    interleavedAttributes.data.buffer.bind()
 
     const calls = (gl.vertexAttribPointer as any).mock.calls
     const stride = 16 // 8 + 4 + 4
@@ -875,25 +968,13 @@ describe('interleavedAttributeView', () => {
       1, // color
     ])
 
-    interleavedAttributes.vertexData.set(data)
+    interleavedAttributes.vertexData.buffer.set(data)
     expect(gl.bufferData).toHaveBeenCalledWith(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW)
   })
 
-  it('should use VAO when available', () => {
-    const vertexArray = { id: 1 }
-    const vaoExt = {
-      createVertexArrayOES: vi.fn(() => vertexArray),
-      bindVertexArrayOES: vi.fn(),
-      deleteVertexArrayOES: vi.fn(),
-    }
-
-    // Override the getExtension method for this test
-    const originalGetExtension = gl.getExtension
-    gl.getExtension = vi.fn((name: string) => {
-      if (name === 'OES_vertex_array_object') return vaoExt as any
-      return originalGetExtension.call(gl, name)
-    }) as any
-
+  it('does not create a vertex array of its own', () => {
+    // A layout used to make one here, which is why the other participants in a
+    // draw had to be bound after it to be included. Arrays are vao()'s job.
     const schema = {
       vertexData: {
         layout: [{ key: 'a_position', kind: 'vec2' }],
@@ -901,26 +982,9 @@ describe('interleavedAttributeView', () => {
       },
     } satisfies InterleavedAttributeSchema
 
-    const interleavedAttributes = interleavedAttributeView(gl as any, program, schema)
+    interleavedAttributeView(gl as any, program, schema)
 
-    expect(vaoExt.createVertexArrayOES).toHaveBeenCalled()
-    expect(vaoExt.bindVertexArrayOES).toHaveBeenCalledWith(vertexArray)
-    expect(vaoExt.bindVertexArrayOES).toHaveBeenCalledWith(null) // unbind after setup
-
-    // Test bind
-    interleavedAttributes.vertexData.bind()
-    expect(vaoExt.bindVertexArrayOES).toHaveBeenCalledWith(vertexArray)
-
-    // Test unbind
-    interleavedAttributes.vertexData.unbind()
-    expect(vaoExt.bindVertexArrayOES).toHaveBeenCalledWith(null)
-
-    // Test dispose
-    interleavedAttributes.vertexData.dispose()
-    expect(vaoExt.deleteVertexArrayOES).toHaveBeenCalledWith(vertexArray)
-
-    // Restore original method
-    gl.getExtension = originalGetExtension
+    expect(gl.createVertexArray).not.toHaveBeenCalled()
   })
 
   it('should dispose buffers', () => {
@@ -999,13 +1063,13 @@ describe('interleavedAttributeView', () => {
     const interleavedAttributes = interleavedAttributeView(gl, program, schema)
 
     expect(interleavedAttributes[data_symbol]).toBeDefined()
-    expect(interleavedAttributes[data_symbol].bind).toBeInstanceOf(Function)
-    expect(interleavedAttributes[data_symbol].unbind).toBeInstanceOf(Function)
+    expect(interleavedAttributes[data_symbol].buffer.bind).toBeInstanceOf(Function)
+    expect(interleavedAttributes[data_symbol].buffer.perInstance.bind).toBeInstanceOf(Function)
     expect(interleavedAttributes[data_symbol].dispose).toBeInstanceOf(Function)
-    expect(interleavedAttributes[data_symbol].set).toBeInstanceOf(Function)
+    expect(interleavedAttributes[data_symbol].buffer.set).toBeInstanceOf(Function)
 
     // Test binding
-    interleavedAttributes[data_symbol].bind()
+    interleavedAttributes[data_symbol].buffer.bind()
     
     // Should bind buffer and set up attributes
     expect(gl.bindBuffer).toHaveBeenCalled()
@@ -1033,7 +1097,7 @@ describe('interleavedAttributeView', () => {
     expect(interleavedAttributes[vertexData]).toBeDefined()
     
     // Test that it correctly calculates stride
-    interleavedAttributes[vertexData].bind()
+    interleavedAttributes[vertexData].buffer.bind()
     
     const calls = (gl.vertexAttribPointer as any).mock.calls
     // All calls should have the same stride (3+3+2)*4 = 32 bytes
@@ -1080,6 +1144,26 @@ describe('bufferView', () => {
     expect(gl.bindBuffer).toHaveBeenCalledWith(gl.ELEMENT_ARRAY_BUFFER, expect.any(Object))
   })
 
+  it('should return a disposer from bind that releases the target', () => {
+    const schema = {
+      indices: { target: 'ELEMENT_ARRAY_BUFFER' },
+    } satisfies BufferSchema
+
+    const buffers = bufferView(gl, schema)
+
+    // An ELEMENT_ARRAY_BUFFER binding is recorded in whichever vertex array is
+    // bound, so restoring the previous buffer rather than null keeps the
+    // disposer from stripping the index buffer off an array we do not own.
+    const previous = { id: 'previously-bound' }
+    ;(gl.getParameter as any).mockReturnValue(previous)
+
+    const unbind = buffers.indices.bind()
+    expect(unbind).toBeInstanceOf(Function)
+
+    unbind()
+    expect(gl.bindBuffer).toHaveBeenLastCalledWith(gl.ELEMENT_ARRAY_BUFFER, previous)
+  })
+
   it('should set buffer data with specified usage', () => {
     const schema = {
       vertices: { target: 'ARRAY_BUFFER', usage: 'STATIC_DRAW' },
@@ -1166,3 +1250,198 @@ describe('bufferView', () => {
     expect(gl.bufferData).toHaveBeenCalledWith(gl.ARRAY_BUFFER, data, gl.DYNAMIC_DRAW)
   })
 })
+
+describe('vaoView', () => {
+  let gl: WebGL2RenderingContext
+  let program: WebGLProgram
+  beforeEach(() => {
+    const mock = createMockCanvas()
+    gl = mock.gl
+    program = gl.createProgram()!
+  })
+
+  function participants() {
+    const attributes = attributeView(gl as any, program, {
+      a_corner: { kind: 'vec2' },
+    } satisfies AttributeSchema)
+    const interleaved = interleavedAttributeView(gl as any, program, {
+      a_instance: {
+        layout: [{ key: 'a_position', kind: 'vec2' }],
+      },
+    } satisfies InterleavedAttributeSchema)
+    const buffers = bufferView(gl as any, {
+      b_index: { target: 'ELEMENT_ARRAY_BUFFER' },
+    } satisfies BufferSchema)
+    return { attributes, interleaved, buffers }
+  }
+
+  it('writes every participant into one array, at construction', () => {
+    const { attributes, interleaved, buffers } = participants()
+    const vertexArray = { id: 'vao' } as unknown as WebGLVertexArrayObject
+    gl.createVertexArray = vi.fn(() => vertexArray) as any
+
+    const calls: string[] = []
+    gl.bindVertexArray = vi.fn(v => calls.push(v === vertexArray ? 'bind' : 'unbind')) as any
+    gl.vertexAttribPointer = vi.fn(() => calls.push('pointer')) as any
+    gl.bindBuffer = vi.fn((target: number) =>
+      calls.push(target === gl.ELEMENT_ARRAY_BUFFER ? 'indices' : 'array'),
+    ) as any
+
+    vaoView(gl as any, [
+      attributes.a_corner,
+      interleaved.a_instance.buffer.perInstance,
+      buffers.b_index,
+    ])
+
+    // Every participant's state is written while the new array is bound —
+    // that is the whole contract, and what call order used to decide.
+    const bound = calls.indexOf('bind')
+    const unbound = calls.lastIndexOf('unbind')
+    expect(bound).toBeGreaterThanOrEqual(0)
+    expect(calls.indexOf('pointer')).toBeGreaterThan(bound)
+    expect(calls.indexOf('indices')).toBeGreaterThan(bound)
+    expect(unbound).toBeGreaterThan(calls.lastIndexOf('indices'))
+  })
+
+  it('binds and restores, and disposes the array', () => {
+    const { attributes } = participants()
+    const vertexArray = { id: 'vao' } as unknown as WebGLVertexArrayObject
+    const foreign = { id: 'foreign' } as unknown as WebGLVertexArrayObject
+    // Swapped before the first getVertexArrayObject call: on a context without
+    // native vertex arrays the extension wrapper binds these once, up front.
+    gl.createVertexArray = vi.fn(() => vertexArray) as any
+    const bindVertexArray = vi.fn()
+    gl.bindVertexArray = bindVertexArray as any
+    gl.getParameter = vi.fn(() => foreign) as any
+
+    const vao = vaoView(gl as any, [attributes.a_corner])
+    bindVertexArray.mockClear()
+
+    const restore = vao.bind()
+    expect(bindVertexArray).toHaveBeenLastCalledWith(vertexArray)
+    restore()
+    expect(bindVertexArray).toHaveBeenLastCalledWith(foreign)
+
+    vao.dispose()
+    expect(gl.deleteVertexArray).toHaveBeenCalledWith(vertexArray)
+  })
+
+  it('re-applies each participant per bind when the context has no vertex arrays', () => {
+    // WebGL1 without OES_vertex_array_object: nowhere to keep the state, so
+    // the array is emulated by doing the work again on every bind.
+    const mock = createMockGL()
+    const gl1 = mock as any
+    gl1.createVertexArray = undefined
+    gl1.getExtension = vi.fn(() => null)
+    const program1 = gl1.createProgram()
+
+    const attributes = attributeView(gl1, program1, {
+      a_corner: { kind: 'vec2' },
+    } satisfies AttributeSchema)
+
+    const vao = vaoView(gl1, [attributes.a_corner])
+    expect(gl1.vertexAttribPointer).not.toHaveBeenCalled()
+
+    vao.bind()
+    expect(gl1.vertexAttribPointer).toHaveBeenCalledTimes(1)
+    vao.bind()
+    expect(gl1.vertexAttribPointer).toHaveBeenCalledTimes(2)
+  })
+})
+
+describe('binding a participant on its own', () => {
+  let gl: WebGL2RenderingContext
+  let program: WebGLProgram
+  beforeEach(() => {
+    const mock = createMockCanvas()
+    gl = mock.gl
+    program = gl.createProgram()!
+  })
+
+  it('targets the default vertex array, not whichever one is current', () => {
+    // The pointer calls name no destination. Without binding first, this would
+    // edit a caller's array — and an array keeps what it is given, so the
+    // damage would outlive the call.
+    const foreign = { id: 'foreign' } as unknown as WebGLVertexArrayObject
+    gl.getParameter = vi.fn(() => foreign) as any
+    const bindVertexArray = vi.fn()
+    gl.bindVertexArray = bindVertexArray as any
+
+    const attributes = attributeView(gl as any, program, {
+      a_corner: { kind: 'vec2' },
+    } satisfies AttributeSchema)
+
+    const restore = attributes.a_corner.bind()
+    expect(bindVertexArray).toHaveBeenCalledWith(null)
+    restore()
+    expect(bindVertexArray).toHaveBeenLastCalledWith(foreign)
+  })
+})
+
+describe('the constant source', () => {
+  let gl: WebGL2RenderingContext
+  let program: WebGLProgram
+  beforeEach(() => {
+    const mock = createMockCanvas()
+    gl = mock.gl
+    program = gl.createProgram()!
+  })
+
+  const schema = {
+    a_instance: {
+      layout: [
+        { key: 'a_pos', kind: 'vec2' },
+        { key: 'a_size', kind: 'float' },
+      ],
+    },
+  } satisfies InterleavedAttributeSchema
+
+  it('gives the layout per-key setters, like a uniform', () => {
+    const { a_instance } = interleavedAttributeView(gl as any, program, schema)
+
+    expect(a_instance.constant.a_pos.set).toBeInstanceOf(Function)
+    expect(a_instance.constant.a_size.set).toBeInstanceOf(Function)
+  })
+
+  it('disables the arrays, so the attributes read the constants', () => {
+    const { a_instance } = interleavedAttributeView(gl as any, program, schema)
+
+    a_instance.constant.applyToVertexArray()
+
+    expect(gl.disableVertexAttribArray).toHaveBeenCalledTimes(2)
+  })
+
+  it('writes the values on every bind, not once into the array', () => {
+    // The enable flag is vertex-array state; the values are context state, and
+    // no array can keep them. Applying them once at construction would leave a
+    // later draw showing whatever the previous one set.
+    const { a_instance } = interleavedAttributeView(gl as any, program, schema)
+    a_instance.constant.a_pos.set(1, 2)
+    a_instance.constant.a_size.set(4)
+
+    const vao = vaoView(gl as any, [a_instance.constant])
+    expect(gl.vertexAttrib2f).not.toHaveBeenCalled()
+
+    vao.bind()
+    expect(gl.vertexAttrib2f).toHaveBeenCalledWith(expect.any(Number), 1, 2)
+    expect(gl.vertexAttrib1f).toHaveBeenCalledWith(expect.any(Number), 4)
+
+    a_instance.constant.a_pos.set(7, 8)
+    vao.bind()
+    expect(gl.vertexAttrib2f).toHaveBeenLastCalledWith(expect.any(Number), 7, 8)
+  })
+
+  it('refuses a kind vertexAttrib* cannot express, when asked for one', () => {
+    // A hard limit of the API, not a choice: vertexAttrib* takes at most four
+    // floats and has no matrix form. The buffer source handles it fine, so the
+    // complaint waits until someone reaches for a constant.
+    const matrix = {
+      a_instance: { layout: [{ key: 'a_model', kind: 'mat4' }] },
+    } satisfies InterleavedAttributeSchema
+
+    const { a_instance } = interleavedAttributeView(gl as any, program, matrix)
+
+    expect(() => a_instance.buffer.bind()).not.toThrow()
+    expect(() => a_instance.constant).toThrow(/cannot be a constant attribute/)
+  })
+})