@bigmistqke/view.gl 0.1.19 → 0.3.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,
@@ -24,9 +28,13 @@ import {
   assertedNotNullish,
   kindToSize,
   forEachObject,
+  once,
 } from './utils'
 import { createUpsertMap, mapObject } from './utils'
 export * from './types'
+// Documented under Utils but reachable from nowhere until now: utils is not a
+// build entry, and named rather than star so the internal helpers stay internal.
+export { createFramebuffer, createTexture } from './utils'
 
 /**********************************************************************************/
 /*                                                                                */
@@ -70,20 +78,132 @@ export function view<TSchema extends ViewSchema>(
   gl: GL,
   program: WebGLProgram,
   schema: TSchema,
-  options?: ViewOptions,
+  { signal }: ViewOptions = {},
 ): View<TSchema> {
+  // The sub-views are built without the signal and the view wires disposal
+  // once, so that `dispose()` and aborting do the same thing rather than each
+  // doing half of it.
+  const attributes = !schema.attributes ? undefined : attributeView(gl, program, schema.attributes)
+  const interleavedAttributes = !schema.interleavedAttributes
+    ? undefined
+    : interleavedAttributeView(gl, program, schema.interleavedAttributes)
+
+  // Vertex arrays are made on demand rather than declared, so they are the one
+  // thing the view cannot dispose from the schema alone. Held until disposed —
+  // by the view or by the caller — and dropped either way, so a view that hands
+  // out an array per frame does not accumulate them.
+  const vertexArrays = new Set<VertexArrayMethods>()
+
+  const dispose = once(() => {
+    if (attributes) forEachObject(attributes, value => value.dispose())
+    if (interleavedAttributes) forEachObject(interleavedAttributes, value => value.dispose())
+    vertexArrays.forEach(vertexArray => vertexArray.dispose())
+    vertexArrays.clear()
+  })
+
+  signal?.addEventListener('abort', dispose)
+
   return {
     uniforms: !schema.uniforms ? undefined : uniformView(gl, program, schema.uniforms),
-    attributes: !schema.attributes
-      ? undefined
-      : attributeView(gl, program, schema.attributes, options),
-    interleavedAttributes: !schema.interleavedAttributes
-      ? undefined
-      : interleavedAttributeView(gl, program, schema.interleavedAttributes, options),
-    buffers: !schema.buffers ? undefined : bufferView(gl, schema.buffers),
+    attributes,
+    interleavedAttributes,
+    vao(participants: VertexArrayParticipant[]) {
+      const vertexArray = vaoView(gl, participants)
+      vertexArrays.add(vertexArray)
+      return {
+        ...vertexArray,
+        dispose: once(() => {
+          vertexArrays.delete(vertexArray)
+          vertexArray.dispose()
+        }),
+      }
+    },
+    dispose,
   } 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: once(() => feature.deleteVertexArray(vertexArray)),
+        }
+      })()
+
+  signal?.addEventListener('abort', () => methods.dispose())
+
+  return methods
+}
+
 /**********************************************************************************/
 /*                                                                                */
 /*                                    Uniform View                                */
@@ -246,17 +366,6 @@ function readDivisor(gl: GL, location: number): number {
     : 0
 }
 
-// Wraps a restore so it runs once: a disposer is per bind() and undoing twice
-// would put back state a later bind() is relying on
-function once(restore: () => void): () => void {
-  let done = false
-  return () => {
-    if (done) return
-    done = true
-    restore()
-  }
-}
-
 export function attributeView<T extends AttributeSchema>(
   gl: GL,
   program: WebGLProgram,
@@ -266,17 +375,17 @@ export function attributeView<T extends AttributeSchema>(
   const attributes = mapObject(
     schema,
     (
-      {
-        kind,
-        format,
-        normalized = false,
-        instanced,
-        buffer = assertedNotNullish(gl.createBuffer()),
-      },
+      { kind, format, normalized = false, instanced, buffer: providedBuffer },
       key,
     ): AttributeMethods => {
       const name = toID(key)
 
+      // Whoever made the buffer deletes it. A schema can name a buffer that
+      // belongs to another view — the quad `compile.toQuad` shares across every
+      // program on a context, an attribute two programs step over — and
+      // deleting one of those would take it out from under its owner.
+      const buffer = providedBuffer ?? assertedNotNullish(gl.createBuffer())
+
       const location = gl.getAttribLocation(program, name)
       if (location < 0) {
         throw new Error(`Attribute '${name}' not found`)
@@ -287,20 +396,35 @@ 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() {
-          gl.deleteBuffer(buffer)
-        },
+        dispose: once(() => {
+          if (!providedBuffer) {
+            gl.deleteBuffer(buffer)
+          }
+        }),
         set(data, usage = 'STATIC_DRAW') {
           gl.bindBuffer(gl.ARRAY_BUFFER, buffer)
           gl.bufferData(gl.ARRAY_BUFFER, data, gl[usage])
@@ -323,6 +447,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 +521,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 +546,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 +556,7 @@ export function interleavedAttributeView<T extends InterleavedAttributeSchema>(
           glType,
           isIntKind,
           normalized,
-          instanced,
+          divisor === 1,
         )
     })
 
@@ -375,91 +566,61 @@ 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)
-            })
-          }
-        })
-      },
-      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()
-        }
+      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))
       },
+      dispose: once(() => gl.deleteBuffer(buffer)),
     } satisfies InterleavedAttributeMethods
   })
 
@@ -485,21 +646,32 @@ 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() {
-        gl.deleteBuffer(buffer)
-      },
+      dispose: once(() => gl.deleteBuffer(buffer)),
       set(data: Float32Array) {
         gl.bindBuffer(gl[target], buffer)
         gl.bufferData(gl[target], data, gl[usage])

package/src/tag.ts

@@ -18,7 +18,7 @@ import type {
   ViewSchema,
   ViewSchemaPartial,
 } from './types'
-import { createUpsertMap } from './utils'
+import { createUpsertMap, once } from './utils'
 
 export function glsl<TSlot extends GLSLSlot, const TSlots extends TSlot[]>(
   template: TemplateStringsArray,
@@ -99,6 +99,11 @@ export function interleave<
 export interface CompileOptions<TSchema extends ViewSchemaPartial> {
   schema?: TSchema
   webgl2?: boolean
+  /**
+   * Disposes what `compile` made: the program, and the buffers the view created
+   * for itself. Buffers named by the schema belong to whoever made them.
+   */
+  signal?: AbortSignal
 }
 
 export function compile<
@@ -145,10 +150,21 @@ export function compile<
   try {
     const program = createProgram(gl, _vertex.template, _fragment.template)
 
+    // The same rule the views follow: `compile` made this program, so `compile`
+    // is what deletes it. A program handed in from outside would not be ours to
+    // delete, and there is no way to hand one in.
+    const resolvedView = view(gl, program, schema)
+    const dispose = once(() => {
+      resolvedView.dispose()
+      gl.deleteProgram(program)
+    })
+    options?.signal?.addEventListener('abort', dispose)
+
     return {
       program,
       schema,
-      view: view(gl, program, schema),
+      view: resolvedView,
+      dispose,
       vertex: _vertex.template,
       fragment: _fragment.template,
     } as unknown as Prettify<CompileResult<TVertex, TFragment, TSchema>>