Buffer

Holds a block of GPU memory. The length of a buffer cannot be changed after creation.

Types

BufferProps

Property	Type	Description
usage?	number	Bit mask of Usage flags
byteLength?	number	Length of buffer (cannot be changed after creation).
data?	ArrayBuffer | ArrayBufferView	Data to be copied into buffer. byteLength will be deduced if not supplied.
byteOffset?	number	Offset for data
indexType?	'uint16' | 'uint32'	If props.usage & Buffer.INDEX

Usage

Usage expresses two things: The type of buffer and what operations can be performed on it.

Note that the allowed combinations are very limited, especially in WebGPU.

Usage Flag	Value	Description
Buffer.INDEX	0x0010	An index buffer (array of 16 or 32 bit unsigned integers
Buffer.VERTEX	0x0020	A vertex buffer (a binary column)
Buffer.UNIFORM	0x0040	A uniform buffer
Buffer.STORAGE	0x0080	A storage buffer
Buffer.INDIRECT	0x0100
Buffer.QUERY_RESOLVE	0x0200
Buffer.MAP_READ	0x01	Whether the buffer can be mapped for read
Buffer.MAP_WRITE	0x02	Whether the buffer can be mapped for write
Buffer.COPY_SRC	0x0004	Supports commandEncoder.copyBufferTo...
Buffer.COPY_DST	0x0008	Supports commandEncoder.copy...ToBuffer

BufferMapCallback

Called when a GPU buffer data has been mapped to the CPU.

type BufferMapCallback<T> = (arrayBuffer: ArrayBuffer, lifetime: 'mapped' | 'copied') => T;

• arrayBuffer an array buffer containing the data range of the buffer.
• lifetime - indicates whether the arrayBuffer parameter is only available in the callback (WebGPU) or whether it is permanent and can be used after the callback returns (WebGL2).

Members

• device: Device - holds a reference to the Device that created this Buffer.
• handle: unknown - holds the underlying WebGL or WebGPU shader object
• props: BufferProps - holds a copy of the BufferProps used to create this Buffer.

Methods

constructor(props: BufferProps)

Buffer is an abstract class and cannot be instantiated directly. Create with device.createBuffer(...).

destroy(): void

Free up any GPU resources associated with this buffer immediately (instead of waiting for garbage collection).

write(): void

buffer.write(data: ArrayBufferLike | ArrayBufferView, byteOffset?: number): void;

Writes data to the GPU buffer.

• data - binary data to be written to the GPU Buffer.
• byteOffset - the first byte to read from the GPU buffer.
• byteLength - the number of bytes to read from the GPU buffer

Remarks

• Data writes are asynchronous on the GPU but will be completed before any reads.

readAsync(): Promise<ArrayBuffer>

Reads the contents of a GPU Buffer into CPU memory.

buffer.readAsync(byteOffset?: number, byteLength?: number): Promise<Uint8Array>;

Remarks:

• On WebGPU, this copies the mapped buffer data into a permanent array buffer. If you do not need a copy of the memory, considering using mapAndReadAsync instead.

mapAndReadAsync(): Promise<void>

Maps buffer data to CPU memory. Mapped memory is only accessible in the callback.

  buffer.mapAndReadAsync<T>(onData: BufferMapCallback<T>, byteOffset?: number, byteLength?: number): Promise<T>;

• onData - called when the GPU buffer data has been mapped onto the CPU.
• byteOffset - the first byte to read from the GPU buffer.
• byteLength - the number of bytes to read from the GPU buffer

Note:

• On WebGPU, if you do not plan to hold on to the ArrayBuffer read from the buffer, you can provide a callback that accesses the mapped buffer data before it is unmapped.

readSyncWebGL(): ArrayBuffer

• byteOffset - the first byte to read from the GPU buffer.
• byteLength - the number of bytes to read from the GPU buffer

Synchronous reads, while convenient, have significant performance penalty as they force a GPU sync. Synchronous reads are not available on WebGPU.