Buffer

The Buffer namespace — 14 functions.

Buffer/completeReadback

Buffer.completeReadback(token, handle) -> boolean

Drain the completed readback bytes into the Buffer's CPU data, interpreting bytes as little-endian f32. The token is consumed (one-time access). Returns false if the token isn't ready, the handle is unknown, or the byte count doesn't match the buffer's current f32 capacity.

Buffer/copy

Buffer.copy(dstHandle, srcHandle)

Copy src buffer's data into dst. Strides must match — different per-record layouts would silently produce a malformed dst, so the copy refuses with false in that case.

Buffer/create

Buffer.create({ stride = N, count = M }) | Buffer.create(stride, count)

Allocate a pinned float buffer of stride×count f32s. Returns the buffer handle (a number).

Buffer/destroy

Buffer.destroy(handle)

Drop the buffer from the registry. Returns true if the handle was found, false if it was already absent.

Buffer/gpuName

Buffer.gpuName(handle) -> string | nil

Diagnostic accessor — returns the GPU registry name if the buffer has been promoted, nil otherwise. Useful for assertions and inspection.

Buffer/isReadbackReady

Buffer.isReadbackReady(token) -> boolean

Non-consuming poll for whether the GPU finished the readback for token. Pair with completeReadback once true.

Buffer/read

Buffer.read(handle, offset, len) -> { f1, f2, … } | nil

Read len f32s starting at offset. Returns the float array, or nil on out-of-bounds / unknown handle.

Buffer/size

Buffer.size(handle) -> (stride, count) | nil

Returns the buffer's stride and count as two values, or nil for unknown handles.

Buffer/syncFromGpu

Buffer.syncFromGpu(handle) -> string | nil

Start an async GPU→CPU read-back. Returns a token string to poll with isReadbackReady and drain with completeReadback. Returns nil if the buffer was never promoted via uploadAsStorage. The buffer is created with copy_src=true so readback always works once promoted.

Buffer/syncToGpu

Buffer.syncToGpu(handle)

Re-upload current CPU contents to the already-registered GPU buffer. Required before dispatching a compute shader that should see CPU-side mutations made since the last upload. Returns false if the buffer was never promoted via uploadAsStorage.

Buffer/unregisterStorage

Buffer.unregisterStorage(handle)

Release the GPU buffer associated with the handle and drop the name binding. The CPU side is unchanged. Buffer.destroy auto-calls this; standalone for cases where the buffer goes back to CPU-only.

Buffer/uploadAsStorage

Buffer.uploadAsStorage(handle, name?) -> string | nil

Promote the Buffer to a named entry in the compute.* GPU buffer registry. Copies current CPU contents up. Subsequent compute.dispatch calls can name the buffer in their bindings list. If the buffer was already promoted, the old GPU buffer is released first. Returns the registered name on success, nil on unknown handle.

Buffer/write

Buffer.write(handle, offset, { f1, f2, … })

Bulk-write float values into the buffer starting at offset (0-indexed, in f32 units, NOT records). Returns false on out-of-bounds or unknown handle; the buffer is unchanged on failure.

Buffer/zero

Buffer.zero(handle)

Reset every f32 in the buffer to 0.