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()

Destroy the buffer.

Explicitly destroys the buffer, freeing its memory and putting the object in an unusable state. In general its easier (and safer) to just let the garbage collector do its thing.

map(*args, **kwargs)

Backwards compatible method for map_sync()

async map_async(mode: MapMode, offset: int = 0, size: int | None = 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.

Alignment: the offset must be a multiple of 8, the size must be a multiple of 4.

property map_state

The mapping state of the buffer, see BufferMapState.

map_sync(mode: MapMode, offset: int = 0, size: int | None = None)

Sync version of map_async().

Provided by wgpu-py, but not compatible with WebGPU.

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 (in bytes). The resulting range must fit into the range specified in map(). The default is as large as the mapped range allows.

  • copy (bool) – 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.

Alignment: the buffer offset must be a multiple of 8, the size must be a multiple of 4.

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 its 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)

Write 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. Must be an object that supports the buffer protocol, e.g. bytes, memoryview, numpy array, etc. Does not have to be contiguous, since the data is copied anyway.

  • 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.

Alignment: the buffer offset must be a multiple of 8.

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