pygfx.resources.Buffer

class pygfx.resources.Buffer(data=None, *, nbytes=None, nitems=None, format=None, chunk_size=None, force_contiguous=False, usage=0)

Bases: Resource

The Buffer represents a contiguous piece of GPU memory.

A buffer can be used as index buffer or storage buffer. They are also used for uniform buffers (internally in the pygfx materials). You can provide (and update data for it), or use it as a placeholder for a buffer with no representation on the CPU.

Parameters:

data (array | None) – The initial data of the buffer. It must support the buffer-protocol, (e.g. a bytes or numpy array). If None, nbytes and nitems must be provided. The data will be accessible at buffer.data, no copies are made.
nbytes (int | None) – The size of the buffer in bytes. If both data and nbytes are given, the data.nbytes is checked against nbytes.
nitems (int | None) – The number of elements in the buffer. If both data and nitems are given, the data is interpreted as having that many items (reshaped internally).
format (None | str | ElementFormat | wgpu.VertexFormat | wgpu.IndexFormat) – A format string describing the buffer layout. This can follow pygfx’ ElementFormat e.g. “3xf4”, or wgpu’s VertexFormat. Optional: if None, it is automatically determined from the data.
chunk_size (None | int) – The chunk size to use for uploading data to the GPU, expressed in items counts. When None (default) an optimal chunk size is determined automatically.
force_contiguous (bool) – When set to true, the buffer goes into a stricter mode, forcing set data to be c_contiguous. This ensures optimal upload performance for cases when the data changes often.
usage (int | wgpu.BufferUsage) – The wgpu usage flag for this buffer. Optional: typically pygfx can derive how the buffer is used and apply the appropriate flag. In cases where it doesn’t this param provides an override. This is a bitmask flag (values are OR’d).
tips (Performance)
c_contiguous (* If the given data is not) – at upload-time, which reduces performance when the data is changed often.
copied (the chunks will need to be) – at upload-time, which reduces performance when the data is changed often.
contiguous (* Setting force_contiguous ensures that the set data is) – is recommended to use this when the bufer data is dynamic.
it – is recommended to use this when the bufer data is dynamic.

property data

The data for this buffer.

Can be None if the data only exists on the GPU. This object is the same that was given to instantiate this object or with set_data().

property view

A numpy array view on the data of this buffer.

Can be None if the data only exists on the GPU. This is a view on the same memory as .data. The first dimension matches nitems.

property nbytes: The number of bytes in the buffer.

property nitems: The number of items in the buffer.

property itemsize: The number of bytes for a single item.

property format

The buffer format.

Usually a pygfx format specifier (e.g. ‘u2’ for scalar uint16, or ‘3xf4’ for 3xfloat32), but can also be a value from wgpu.VertexFormat, or None e.g. for uniform buffers.