@bigmistqke/view.gl 0.5.0 → 0.7.0

package/README.md

@@ -268,6 +268,14 @@ gl.drawArraysInstanced(gl.TRIANGLES, 0, 3, 100)
 unbind()
 ```
 
+A large buffer can be sized first and filled in parts, counting in elements of
+the attribute's format:
+
+```typescript
+attributes.position.allocate(totalElements)   // sizes the buffer, contents undefined
+attributes.position.write(chunk, offset)      // overwrites a range with bufferSubData
+```
+
 ##### 📋 AttributeSchema
 
 A mapping of attribute names to their configuration.
@@ -388,6 +396,14 @@ const unbind = buffers.indices.bind()
 // bound vertex array object.
 ```
 
+A large buffer can be sized first and filled in parts. A buffer has no element
+type of its own, so these count in bytes:
+
+```typescript
+buffers.data.allocate(byteLength)        // sizes the buffer, contents undefined
+buffers.data.write(chunk, byteOffset)    // overwrites a range with bufferSubData
+```
+
 ##### 📋 BufferSchema
 A mapping of buffer names to their configuration. Each buffer has a target type and optional usage pattern.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigmistqke/view.gl",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "👀 Utilities for managing WebGL resources.",
   "exports": {
     ".": {

package/src/index.ts

@@ -438,6 +438,16 @@ export function attributeView<T extends AttributeSchema>(
           gl.bufferData(gl.ARRAY_BUFFER, data, gl[usage])
           return this
         },
+        allocate(length, usage = 'STATIC_DRAW') {
+          gl.bindBuffer(gl.ARRAY_BUFFER, buffer)
+          gl.bufferData(gl.ARRAY_BUFFER, length * FORMAT_BYTE_SIZE[resolvedFormat], gl[usage])
+          return this
+        },
+        write(data, offset) {
+          gl.bindBuffer(gl.ARRAY_BUFFER, buffer)
+          gl.bufferSubData(gl.ARRAY_BUFFER, offset * FORMAT_BYTE_SIZE[resolvedFormat], data)
+          return this
+        },
       }
     },
   )
@@ -692,6 +702,14 @@ export function bufferView<T extends BufferSchema>(
         gl.bindBuffer(gl[target], buffer)
         gl.bufferData(gl[target], data, gl[usage])
       },
+      allocate(byteLength: number) {
+        gl.bindBuffer(gl[target], buffer)
+        gl.bufferData(gl[target], byteLength, gl[usage])
+      },
+      write(data: Float32Array | Uint16Array | Uint32Array, byteOffset: number) {
+        gl.bindBuffer(gl[target], buffer)
+        gl.bufferSubData(gl[target], byteOffset, data)
+      },
     }
   })
 

package/src/types.ts

@@ -365,6 +365,17 @@ export interface AttributeMethods<T extends AttributeDefinition = AttributeDefin
    */
   bind(): () => void
   set(data: FormatToArray[ResolvedFormat<T>], usage?: GLUsage): { bind(): () => void }
+  /**
+   * Sizes the buffer to `length` elements of the attribute's format, contents
+   * undefined, discarding what it held.
+   */
+  allocate(length: number, usage?: GLUsage): { bind(): () => void }
+  /**
+   * Overwrites the elements from `offset` on with `data`, leaving the rest as
+   * it is. Counts in elements of the attribute's format; the range must fit
+   * inside the buffer's current size.
+   */
+  write(data: FormatToArray[ResolvedFormat<T>], offset: number): { bind(): () => void }
   /**
    * Delete the buffer, if this attribute is the one that made it.
    *
@@ -479,6 +490,16 @@ export type BufferSchema = Record<string | symbol, BufferDefinition>
 
 export interface BufferMethods extends VertexArrayParticipant {
   set(data: Float32Array | Uint16Array | Uint32Array): void
+  /**
+   * Sizes the buffer to `byteLength` bytes, contents undefined, discarding what
+   * it held. In bytes: the buffer has no element type of its own.
+   */
+  allocate(byteLength: number): void
+  /**
+   * Overwrites the bytes from `byteOffset` on with `data`, leaving the rest as
+   * it is. The range must fit inside the buffer's current size.
+   */
+  write(data: Float32Array | Uint16Array | Uint32Array, byteOffset: number): void
   /** Binds the buffer, returning a disposer that restores the previous binding */
   bind(): () => void
   dispose(): void

package/test/index.test.ts

@@ -435,6 +435,31 @@ describe('attributeView', () => {
     program = gl.createProgram()!
   })
 
+  it('sizes the buffer without data, then fills it in parts, counting in its format', () => {
+    const schema = {
+      a_position: { kind: 'vec2' },
+      a_uv: { kind: 'vec2', format: 'int16' },
+    } satisfies AttributeSchema
+
+    const { a_position, a_uv } = attributeView(gl, program, schema)
+
+    a_position.allocate(12, 'DYNAMIC_DRAW')
+    expect(gl.bindBuffer).toHaveBeenLastCalledWith(gl.ARRAY_BUFFER, a_position.buffer)
+    expect(gl.bufferData).toHaveBeenLastCalledWith(gl.ARRAY_BUFFER, 48, gl.DYNAMIC_DRAW)
+
+    const floats = new Float32Array([1, 2])
+    a_position.write(floats, 6)
+    expect(gl.bufferSubData).toHaveBeenLastCalledWith(gl.ARRAY_BUFFER, 24, floats)
+
+    a_uv.allocate(12)
+    expect(gl.bindBuffer).toHaveBeenLastCalledWith(gl.ARRAY_BUFFER, a_uv.buffer)
+    expect(gl.bufferData).toHaveBeenLastCalledWith(gl.ARRAY_BUFFER, 24, gl.STATIC_DRAW)
+
+    const shorts = new Int16Array([1, 2])
+    a_uv.write(shorts, 6)
+    expect(gl.bufferSubData).toHaveBeenLastCalledWith(gl.ARRAY_BUFFER, 12, shorts)
+  })
+
   it('should create attribute methods for basic types', () => {
     const schema = {
       a_position: { kind: 'vec2' },
@@ -1231,6 +1256,21 @@ describe('bufferView', () => {
     expect(gl.createBuffer).toHaveBeenCalledTimes(2)
   })
 
+  it('sizes the buffer without data, then fills it in parts, counting in bytes', () => {
+    const { indices } = bufferView(gl, {
+      indices: { target: 'ELEMENT_ARRAY_BUFFER', usage: 'DYNAMIC_DRAW' },
+    })
+    const target = vi.mocked(gl.createBuffer).mock.results.at(-1)!.value
+
+    indices.allocate(64)
+    expect(gl.bindBuffer).toHaveBeenLastCalledWith(gl.ELEMENT_ARRAY_BUFFER, target)
+    expect(gl.bufferData).toHaveBeenLastCalledWith(gl.ELEMENT_ARRAY_BUFFER, 64, gl.DYNAMIC_DRAW)
+
+    const part = new Uint16Array([0, 1, 2])
+    indices.write(part, 12)
+    expect(gl.bufferSubData).toHaveBeenLastCalledWith(gl.ELEMENT_ARRAY_BUFFER, 12, part)
+  })
+
   it('should create buffers with specified target', () => {
     const schema = {
       vertices: { target: 'ARRAY_BUFFER' },