@bigmistqke/view.gl 0.1.19 → 0.2.0

package/src/index.ts

@@ -9,10 +9,14 @@ import type {
   BufferView,
   GL,
   UniformView as InferUniformView,
+  GLUsage,
+  InterleavedAttributeLayout,
   InterleavedAttributeMethods,
   InterleavedAttributeSchema,
   InterleavedAttributeView,
   UniformSchema,
+  VertexArrayMethods,
+  VertexArrayParticipant,
   View,
   ViewOptions,
   ViewSchema,
@@ -81,9 +85,96 @@ export function view<TSchema extends ViewSchema>(
       ? undefined
       : interleavedAttributeView(gl, program, schema.interleavedAttributes, options),
     buffers: !schema.buffers ? undefined : bufferView(gl, schema.buffers),
+    vao(participants: VertexArrayParticipant[]) {
+      return vaoView(gl, participants, options)
+    },
   } as View<TSchema>
 }
 
+/**********************************************************************************/
+/*                                                                                */
+/*                                    Vertex Array                                */
+/*                                                                                */
+/**********************************************************************************/
+
+/**
+ * Bind the default vertex array, returning a disposer that puts the previous
+ * one back. The pointer calls name no destination, so anything applied without
+ * a vertex array of its own has to say which one it means — and a vertex array
+ * keeps what it is given, so writing into a caller's array by accident would
+ * outlive the call that did it.
+ */
+function bindDefaultVertexArray(gl: GL): () => void {
+  const feature = getVertexArrayObject(gl)
+  if (!feature) {
+    return () => {}
+  }
+  const previous = gl.getParameter(VERTEX_ARRAY_BINDING) as WebGLVertexArrayObject | null
+  feature.bindVertexArray(null)
+  return () => feature.bindVertexArray(previous)
+}
+
+/**
+ * A vertex array over the participants one draw needs.
+ *
+ * Where the context has vertex arrays, each participant writes itself in once,
+ * here, and `bind()` is a single `bindVertexArray`. Where it does not — WebGL1
+ * without `OES_vertex_array_object` — there is nowhere to keep the state, so
+ * `bind()` re-applies every participant and the disposer puts back what they
+ * displaced. Same contract, and the emulation is why the name still fits.
+ */
+export function vaoView(
+  gl: GL,
+  participants: VertexArrayParticipant[],
+  { signal }: ViewOptions = {},
+): VertexArrayMethods {
+  const feature = getVertexArrayObject(gl)
+
+  const methods: VertexArrayMethods = !feature
+    ? {
+        bind() {
+          const restores = participants.map(participant => participant.applyToVertexArray())
+          participants.forEach(participant => participant.applyToContext?.())
+          return once(() => restores.forEach(restore => restore()))
+        },
+        unbind() {},
+        dispose() {},
+      }
+    : (() => {
+        const vertexArray = assertedNotNullish(feature.createVertexArray())
+        const previous = gl.getParameter(VERTEX_ARRAY_BINDING) as WebGLVertexArrayObject | null
+        feature.bindVertexArray(vertexArray)
+        // Discarding the restorers is the point: the state lives in this array
+        // now, and the array is thrown away whole.
+        for (const participant of participants) {
+          participant.applyToVertexArray()
+        }
+        feature.bindVertexArray(previous)
+
+        return {
+          bind() {
+            const previousVertexArray = gl.getParameter(
+              VERTEX_ARRAY_BINDING,
+            ) as WebGLVertexArrayObject | null
+            feature.bindVertexArray(vertexArray)
+            // Context state the array cannot hold — see applyToContext.
+            participants.forEach(participant => participant.applyToContext?.())
+            return once(() => feature.bindVertexArray(previousVertexArray))
+          },
+          unbind() {
+            feature.bindVertexArray(null)
+          },
+          dispose() {
+            feature.deleteVertexArray(vertexArray)
+          },
+        }
+      })()
+
+  signal?.addEventListener('abort', () => methods.dispose())
+
+  return methods
+}
+
 /**********************************************************************************/
 /*                                                                                */
 /*                                    Uniform View                                */
@@ -287,15 +378,28 @@ export function attributeView<T extends AttributeSchema>(
       const glType = FORMAT_TO_GL_TYPE[resolvedFormat]
       const isIntKind = kind.startsWith('i') || kind.startsWith('u')
 
+      function applyToVertexArray() {
+        // Snapshot before the change, restore in the disposer
+        const previousDivisor = readDivisor(gl, location)
+        // vertexAttribPointer captures whatever is bound to ARRAY_BUFFER when
+        // it runs, so this binding is the setup for the pointer, not a lasting
+        // part of the vertex array's state.
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer)
+        handleAttribute(gl, location, size, 0, 0, glType, isIntKind, normalized, instanced)
+        return once(() => {
+          getInstancedArrays(gl)?.vertexAttribDivisor(location, previousDivisor)
+        })
+      }
+
       return {
         buffer,
+        applyToVertexArray,
         bind() {
-          // Snapshot before the change, restore in the disposer
-          const previousDivisor = readDivisor(gl, location)
-          gl.bindBuffer(gl.ARRAY_BUFFER, buffer)
-          handleAttribute(gl, location, size, 0, 0, glType, isIntKind, normalized, instanced)
+          const restoreVertexArray = bindDefaultVertexArray(gl)
+          const restore = applyToVertexArray()
           return once(() => {
-            getInstancedArrays(gl)?.vertexAttribDivisor(location, previousDivisor)
+            restore()
+            restoreVertexArray()
           })
         },
         dispose() {
@@ -323,6 +427,73 @@ export function attributeView<T extends AttributeSchema>(
 /*                                                                                */
 /**********************************************************************************/
 
+/**
+ * The other place an attribute's value can come from: not a buffer, but the
+ * context's current generic vertex attribute values, which an attribute reads
+ * for every vertex when its array is disabled.
+ *
+ * A constant is a uniform in all but name — one value for the whole draw, set
+ * by a function chosen from the kind — so it gets the setters a uniform gets,
+ * off the same layout the buffer source uses.
+ *
+ * `vertexAttrib*` tops out at four floats and has no matrix form, so a layout
+ * key that is fine in a buffer can be impossible as a constant. That is a hard
+ * limit of the API rather than a choice, and it is worth saying so out loud at
+ * the point someone reaches for it.
+ */
+function constantSource(gl: GL, layout: InterleavedAttributeLayout[], locations: number[]) {
+  const setters = layout.map((entry, index) => {
+    const size = kindToSize(entry.kind)
+    const name = toID(entry.key)
+    if (isMatKind(entry.kind) || size > 4) {
+      throw new Error(
+        `'${name}' is a ${entry.kind}, which cannot be a constant attribute: vertexAttrib* takes at most 4 floats and has no matrix form. Use the buffer source for it.`,
+      )
+    }
+    // The values are context state, not vertex-array state, so they are held
+    // here and written again on every bind — see applyToContext.
+    let values: number[] = []
+    const fn = gl[`vertexAttrib${size as 1 | 2 | 3 | 4}f`].bind(gl)
+    return {
+      name,
+      location: locations[index]!,
+      write: () => {
+        if (values.length) {
+          ;(fn as (location: number, ...args: number[]) => void)(locations[index]!, ...values)
+        }
+      },
+      methods: {
+        set(...args: number[]) {
+          values = args
+        },
+      },
+    }
+  })
+
+  return Object.assign(Object.fromEntries(setters.map(setter => [setter.name, setter.methods])), {
+    applyToVertexArray() {
+      const restores = setters.map(({ location }) => {
+        const wasEnabled = gl.getVertexAttrib(location, gl.VERTEX_ATTRIB_ARRAY_ENABLED) as boolean
+        gl.disableVertexAttribArray(location)
+        return () => (wasEnabled ? gl.enableVertexAttribArray(location) : undefined)
+      })
+      return once(() => restores.forEach(restore => restore()))
+    },
+    applyToContext() {
+      setters.forEach(setter => setter.write())
+    },
+    bind() {
+      const restoreVertexArray = bindDefaultVertexArray(gl)
+      const restore = this.applyToVertexArray()
+      this.applyToContext()
+      return once(() => {
+        restore()
+        restoreVertexArray()
+      })
+    },
+  })
+}
+
 export function interleavedAttributeView<T extends InterleavedAttributeSchema>(
   gl: GL,
   program: WebGLProgram,
@@ -330,7 +501,7 @@ export function interleavedAttributeView<T extends InterleavedAttributeSchema>(
   { signal }: ViewOptions = {},
 ): InterleavedAttributeView<T> {
   // Initialize interleaved attributes
-  const interleavedAttributes = mapObject(schema, ({ layout, instanced }) => {
+  const interleavedAttributes = mapObject(schema, ({ layout }) => {
     // Increment number to keep track of offset
     let index = 0
 
@@ -355,7 +526,7 @@ export function interleavedAttributeView<T extends InterleavedAttributeSchema>(
       const normalized = layout.normalized ?? false
       index += size * FORMAT_BYTE_SIZE[resolvedFormat]
 
-      return () =>
+      return (divisor: 0 | 1) =>
         handleAttribute(
           gl,
           location,
@@ -365,7 +536,7 @@ export function interleavedAttributeView<T extends InterleavedAttributeSchema>(
           glType,
           isIntKind,
           normalized,
-          instanced,
+          divisor === 1,
         )
     })
 
@@ -375,90 +546,62 @@ export function interleavedAttributeView<T extends InterleavedAttributeSchema>(
     // Create a buffer
     const buffer = assertedNotNullish(gl.createBuffer())
 
-    // Create VAO to cache attribute state
-    let vao: { unbind(): void; bind(): void; dispose(): void } | undefined = undefined
-
-    // Get VAO-feature: extension if webgl1, gl if webgl2
-    const feature = getVertexArrayObject(gl)
-    if (feature) {
-      const vertexArray = feature.createVertexArray()
-      feature.bindVertexArray(vertexArray)
+    // This layout used to create a vertex array of its own, here, which is why
+    // the other participants in a draw had to be bound after it to be included
+    // — the array they landed in was whichever one happened to be current.
+    // Arrays are `vao()`'s job now; a layout is a layout and a buffer.
+    function applyToVertexArray(divisor: 0 | 1) {
+      const previousDivisors = locations.map(
+        location => [location, readDivisor(gl, location)] as const,
+      )
       gl.bindBuffer(gl.ARRAY_BUFFER, buffer)
       for (const handle of handles) {
-        handle()
-      }
-      feature.bindVertexArray(null)
-      vao = {
-        unbind() {
-          feature.bindVertexArray(null)
-        },
-        bind() {
-          feature.bindVertexArray(vertexArray)
-        },
-        dispose() {
-          feature.deleteVertexArray(vertexArray)
-        },
+        handle(divisor)
       }
+      return once(() => {
+        const instancedArrays = getInstancedArrays(gl)
+        previousDivisors.forEach(([location, previous]) => {
+          instancedArrays?.vertexAttribDivisor(location, previous)
+        })
+      })
     }
 
-    // A selected vertex array stays selected for every later draw, which would
-    // then write its own attributes into this one
-    const unbind = () => {
-      if (vao) {
-        vao.unbind()
+    let constant: ReturnType<typeof constantSource> | undefined
+
+    /** One layout, one buffer, but a divisor per draw rather than per schema. */
+    function bufferSource(divisor: 0 | 1) {
+      const apply = () => applyToVertexArray(divisor)
+      return {
+        applyToVertexArray: apply,
+        bind() {
+          const restoreVertexArray = bindDefaultVertexArray(gl)
+          const restore = apply()
+          return once(() => {
+            restore()
+            restoreVertexArray()
+          })
+        },
       }
     }
 
     return {
-      bind() {
-        // Snapshot before the change, restore in the disposer
-        const previousVertexArray = feature
-          ? (gl.getParameter(VERTEX_ARRAY_BINDING) as WebGLVertexArrayObject | null)
-          : null
-        const previousDivisors = vao
-          ? []
-          : locations.map(location => [location, readDivisor(gl, location)] as const)
-
-        gl.bindBuffer(gl.ARRAY_BUFFER, buffer)
-        if (vao) {
-          vao.bind()
-        } else {
-          // Fallback: manual attribute setup
-          for (const handle of handles) {
-            handle()
-          }
-        }
-
-        return once(() => {
-          if (feature) {
-            feature.bindVertexArray(previousVertexArray)
-          }
-          // Without a vertex array the manual setup wrote divisors straight to
-          // the locations, so they are ours to put back
-          if (!vao) {
-            const instancedArrays = getInstancedArrays(gl)
-            previousDivisors.forEach(([location, divisor]) => {
-              instancedArrays?.vertexAttribDivisor(location, divisor)
-            })
-          }
-        })
+      buffer: Object.assign(bufferSource(0), {
+        /** The same buffer, stepped once per instance instead of once per vertex. */
+        perInstance: bufferSource(1),
+        set(value: Float32Array, usage: GLUsage = 'STATIC_DRAW') {
+          // Uploading is storage, not binding: ARRAY_BUFFER is not vertex-array
+          // state, so this touches no array, whichever one is bound.
+          gl.bindBuffer(gl.ARRAY_BUFFER, buffer)
+          gl.bufferData(gl.ARRAY_BUFFER, value, gl[usage])
+        },
+      }),
+      // Lazy: a layout key can be perfectly good in a buffer and impossible as
+      // a constant, and finding that out should wait until someone asks for one.
+      get constant() {
+        return (constant ??= constantSource(gl, layout, locations))
       },
-      unbind,
       dispose() {
         gl.deleteBuffer(buffer)
-        if (vao) {
-          vao.dispose()
-        }
-      },
-      set(value, usage = 'STATIC_DRAW') {
-        if (vao) {
-          vao.bind()
-        }
-        gl.bindBuffer(gl.ARRAY_BUFFER, buffer)
-        gl.bufferData(gl.ARRAY_BUFFER, value, gl[usage])
-        if (vao) {
-          vao.unbind()
-        }
       },
     } satisfies InterleavedAttributeMethods
   })
@@ -485,16 +628,29 @@ export function bufferView<T extends BufferSchema>(
   const buffers = mapObject(schema, ({ target = 'ARRAY_BUFFER', usage = 'STATIC_DRAW' }) => {
     const buffer = assertedNotNullish(gl.createBuffer())
 
+    function applyToVertexArray() {
+      // Snapshot before the change, restore in the disposer. Restoring the
+      // previous buffer rather than null matters for ELEMENT_ARRAY_BUFFER,
+      // whose binding is recorded in the bound vertex array: clearing it
+      // would strip the index buffer from an array the caller may not own.
+      const previousBuffer = gl.getParameter(gl[`${target}_BINDING`]) as WebGLBuffer | null
+      gl.bindBuffer(gl[target], buffer)
+      return once(() => {
+        gl.bindBuffer(gl[target], previousBuffer)
+      })
+    }
+
     return {
+      applyToVertexArray,
       bind() {
-        // Snapshot before the change, restore in the disposer. Restoring the
-        // previous buffer rather than null matters for ELEMENT_ARRAY_BUFFER,
-        // whose binding is recorded in the bound vertex array: clearing it
-        // would strip the index buffer from an array the caller may not own.
-        const previousBuffer = gl.getParameter(gl[`${target}_BINDING`]) as WebGLBuffer | null
-        gl.bindBuffer(gl[target], buffer)
+        // ELEMENT_ARRAY_BUFFER's binding belongs to the bound vertex array, so
+        // like the attributes this has to say which array it means. ARRAY_BUFFER
+        // is context state and unaffected either way.
+        const restoreVertexArray = bindDefaultVertexArray(gl)
+        const restore = applyToVertexArray()
         return once(() => {
-          gl.bindBuffer(gl[target], previousBuffer)
+          restore()
+          restoreVertexArray()
         })
       },
       dispose() {

package/src/types.ts

@@ -322,9 +322,47 @@ 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
-  /** Binds the attribute, returning a disposer that restores the divisor */
+  /**
+   * 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
@@ -354,13 +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[],
 > {
+  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
 }
 
@@ -381,7 +461,7 @@ export interface BufferDefinition {
 
 export type BufferSchema = Record<string | symbol, BufferDefinition>
 
-export interface BufferMethods {
+export interface BufferMethods extends VertexArrayParticipant {
   set(data: Float32Array | Uint16Array | Uint32Array): void
   /** Binds the buffer, returning a disposer that restores the previous binding */
   bind(): () => void
@@ -563,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
 }
 
 /**********************************************************************************/