GPUBuffer

class wgpu.GPUBuffer

Bases: GPUObjectBase

Represents a block of memory that can be used in GPU operations.

Data is stored in linear layout, meaning that each byte of the allocation can be addressed by its offset from the start of the buffer, subject to alignment restrictions depending on the operation.

Create a buffer using GPUDevice.create_buffer().

One can sync data in a buffer by mapping it and then getting and setting data. Alternatively, one can tell the GPU (via the command encoder) to copy data between buffers and textures.

destroy()

An application that no longer requires a buffer can choose to destroy it. Note that this is automatically called when the Python object is cleaned up by the garbadge collector.

map(mode, offset=0, size=None)

Maps the given range of the GPUBuffer.

When this call returns, the buffer content is ready to be accessed with read_mapped or write_mapped. Don’t forget to unmap() when done.

Parameters:

  • mode (enum) – The mapping mode, either wgpu.MapMode.READ or wgpu.MapMode.WRITE, can also be a string.

  • offset (str) – the buffer offset in bytes. Default 0.

  • size (int) – the size to read. Default until the end.

async map_async(mode, offset=0, size=None)

Alternative version of map().

map_read(offset=None, size=None, iter=None)

Deprecated.

property map_state

The mapping state of the buffer, see BufferMapState.

map_write(data)

Deprecated.

read_mapped(buffer_offset=None, size=None, *, copy=True)

Read mapped buffer data.

This method must only be called when the buffer is in a mapped state. This is the Python alternative to WebGPU’s getMappedRange. Returns a memoryview that is a copy of the mapped data (it won’t become invalid when the buffer is ummapped).

Parameters:

  • buffer_offset (int) – the buffer offset in bytes. Must be at least as large as the offset specified in map(). The default is the offset of the mapped range.

  • size (int) – the size to read. The resuling range must fit into the range specified in map(). The default is as large as the mapped range allows.

  • copy (boool) – whether a copy of the data is given. Default True. If False, the returned memoryview represents the mapped data directly, and is released when the buffer is unmapped. WARNING: views of the returned data (e.g. memoryview objects or numpy arrays) can still be used after the base memory is released, which can result in corrupted data and segfaults. Therefore, when setting copy to False, make very sure the memory is not accessed after the buffer is unmapped.

Also see GPUBuffer.write_mapped(), GPUQueue.read_buffer() and GPUQueue.write_buffer().

property size

The length of the GPUBuffer allocation in bytes.

unmap()

Unmaps the buffer.

Unmaps the mapped range of the GPUBuffer and makes it’s contents available for use by the GPU again.

property usage

The allowed usages (int bitmap) for this GPUBuffer, specifying e.g. whether the buffer may be used as a vertex buffer, uniform buffer, target or source for copying data, etc.

write_mapped(data, buffer_offset=None, size=None)

Read mapped buffer data.

This method must only be called when the buffer is in a mapped state. This is the Python alternative to WebGPU’s getMappedRange. Since the data can also be a view into a larger array, this method allows updating the buffer with minimal data copying.

Parameters:

  • data (buffer-like) – The data to write to the buffer, in the form of e.g. a bytes object, memoryview, or numpy array.

  • buffer_offset (int) – the buffer offset in bytes. Must be at least as large as the offset specified in map(). The default is the offset of the mapped range.

  • size (int) – the size to read. The default is the size of the data, so this argument can typically be ignored. The resuling range must fit into the range specified in map().

Also see GPUBuffer.read_mapped, `GPUQueue.read_buffer() and GPUQueue.write_buffer().