@bigmistqke/view.gl 0.6.0 → 0.7.0

package/README.md

@@ -396,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.6.0",
+  "version": "0.7.0",
   "description": "👀 Utilities for managing WebGL resources.",
   "exports": {
     ".": {

package/src/index.ts

@@ -702,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

@@ -490,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

@@ -1256,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' },