@bigmistqke/view.gl 0.1.19 → 0.3.0

package/src/types.ts

@@ -322,11 +322,58 @@ 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 }
+  /**
+   * Delete the buffer, if this attribute is the one that made it.
+   *
+   * A buffer named by the schema came from somewhere else and is deleted by
+   * whoever made it — a shared buffer is the point of passing one in, and one
+   * view cannot know whether the others are done. So this is safe to call
+   * twice and safe to call on a borrowed buffer, and it is not a way to free
+   * one: dispose the view that created it.
+   */
   dispose(): void
 }
 
@@ -354,13 +401,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 +470,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
@@ -422,6 +511,12 @@ export interface TextureDefinition {
 export interface Framebuffer {
   texture: WebGLTexture
   framebuffer: WebGLFramebuffer
+  /**
+   * Delete the framebuffer, and the texture only if `createFramebuffer` made
+   * it. A texture handed in belongs to whoever made it. Idempotent, and exactly
+   * what aborting the signal does.
+   */
+  dispose(): void
 }
 
 /**********************************************************************************/
@@ -537,11 +632,16 @@ export interface ViewOptions {
   signal?: AbortSignal
 }
 
+/**
+ * What a program has names for. Buffers are absent on purpose: a buffer has no
+ * name in the source, so it cannot be resolved against a program the way a
+ * uniform or an attribute is, and its lifetime is rarely a program's. Build one
+ * with `bufferView` and pass it to `vao()` alongside the attributes.
+ */
 export interface ViewSchema {
   uniforms?: UniformSchema
   attributes?: AttributeSchema
   interleavedAttributes?: InterleavedAttributeSchema
-  buffers?: BufferSchema
 }
 
 type PartialSchema<T> =
@@ -551,7 +651,6 @@ export interface ViewSchemaPartial {
   uniforms?: PartialSchema<UniformSchema>
   attributes?: PartialSchema<AttributeSchema>
   interleavedAttributes?: PartialSchema<InterleavedAttributeSchema>
-  buffers?: PartialSchema<BufferSchema>
 }
 
 export type View<T extends ViewSchema = ViewSchema> = {
@@ -561,8 +660,24 @@ export type View<T extends ViewSchema = ViewSchema> = {
   interleavedAttributes: T['interleavedAttributes'] extends InterleavedAttributeSchema
     ? Prettify<InterleavedAttributeView<T['interleavedAttributes']>>
     : {}
-  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
+  /**
+   * Delete everything the view made: the buffers behind its attributes and
+   * layouts, and any vertex array still held from `vao()`. Buffers named by the
+   * schema are left alone — those belong to whoever made them. Idempotent, and
+   * exactly what aborting the signal does.
+   */
+  dispose(): void
 }
 
 /**********************************************************************************/
@@ -791,5 +906,10 @@ export type CompileResult<
         view: Prettify<View<TSchema>>
         vertex: string
         fragment: string
+        /**
+         * Delete the program and everything its view made. Idempotent, and
+         * exactly what aborting the signal does.
+         */
+        dispose(): void
       }
     : never

package/src/utils.ts

@@ -6,6 +6,7 @@ import type {
   KIND_TO_UNIFORM_FN_NAME_MAP,
   TextureDefinition,
   UniformKind,
+  ViewOptions,
 } from './types'
 
 export function assertedNotNullish<T>(value: T, message?: string): NonNullable<T> {
@@ -13,6 +14,24 @@ export function assertedNotNullish<T>(value: T, message?: string): NonNullable<T
   return value
 }
 
+/**
+ * Wraps a teardown so it runs once.
+ *
+ * Two reasons, and both bite. A disposer is per `bind()`, and undoing twice
+ * would put back state a later `bind()` is relying on. And a `dispose()` that
+ * deletes twice invalidates a handle someone else may still be holding — the
+ * object survives while it is bound, so the fault surfaces later, somewhere
+ * else. Idempotent is the only safe shape for either.
+ */
+export function once(teardown: () => void): () => void {
+  let done = false
+  return () => {
+    if (done) return
+    done = true
+    teardown()
+  }
+}
+
 /**********************************************************************************/
 /*                                                                                */
 /*                              Kind To Uniform Name                              */
@@ -114,8 +133,9 @@ export function createTexture(
     height,
   }: TextureDefinition,
   data?: ArrayBufferView | null,
+  { signal }: ViewOptions = {},
 ): WebGLTexture {
-  const texture = gl.createTexture()
+  const texture = assertedNotNullish(gl.createTexture(), 'Failed to create texture')
 
   function getTextureConstant(name: string) {
     if (!(name in gl)) {
@@ -137,13 +157,17 @@ export function createTexture(
     data ?? null,
   )
 
-  console.log(minFilter)
   // Set texture parameters
   gl.texParameteri(gl[target], gl.TEXTURE_MIN_FILTER, gl[minFilter])
   gl.texParameteri(gl[target], gl.TEXTURE_MAG_FILTER, gl[magFilter])
   gl.texParameteri(gl[target], gl.TEXTURE_WRAP_S, gl[wrapS])
   gl.texParameteri(gl[target], gl.TEXTURE_WRAP_T, gl[wrapT])
 
+  signal?.addEventListener(
+    'abort',
+    once(() => gl.deleteTexture(texture)),
+  )
+
   return texture
 }
 
@@ -162,7 +186,7 @@ const FRAMEBUFFER_ATTACHMENT_MAP = {
 
 class FramebufferError extends Error {
   constructor(gl: GL, status: number) {
-    let errorMessage = `Framebuffer '${name}' not complete. Status: `
+    let errorMessage = 'Framebuffer not complete. Status: '
     switch (status) {
       case gl.FRAMEBUFFER_INCOMPLETE_ATTACHMENT:
         errorMessage += 'FRAMEBUFFER_INCOMPLETE_ATTACHMENT'
@@ -185,16 +209,15 @@ class FramebufferError extends Error {
 
 export function createFramebuffer(
   gl: GL,
-  { attachment, texture, ...options }: FramebufferDefinition,
+  { attachment, texture: providedTexture, ...definition }: FramebufferDefinition,
+  { signal }: ViewOptions = {},
 ) {
-  // Create texture for the framebuffer
-  texture ??= createTexture(gl, options)
+  // Create texture for the framebuffer, unless one was handed in. Which one it
+  // is decides who deletes it below — the same rule the attribute buffers follow.
+  const texture = providedTexture ?? createTexture(gl, definition)
 
   // Create framebuffer
-  const framebuffer = assertedNotNullish(
-    gl.createFramebuffer(),
-    `Failed to create framebuffer: ${name}`,
-  )
+  const framebuffer = assertedNotNullish(gl.createFramebuffer(), 'Failed to create framebuffer')
 
   gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer)
 
@@ -213,9 +236,21 @@ export function createFramebuffer(
     throw new FramebufferError(gl, status)
   }
 
+  const dispose = once(() => {
+    gl.deleteFramebuffer(framebuffer)
+    // A texture handed in belongs to whoever made it — it commonly outlives the
+    // framebuffer, ping-ponged between two of them.
+    if (!providedTexture) {
+      gl.deleteTexture(texture)
+    }
+  })
+
+  signal?.addEventListener('abort', dispose)
+
   return {
     texture,
     framebuffer,
+    dispose,
   }
 }