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.

property usage: Bitmask indicating how the buffer can be used in a wgpu pipeline.

property draw_range: The range to data (origin, size) expressed in items.

send_data(offset, data)

Send a chunk of data to the GPU.

This provides a way to upload data to buffers that don’t have local data (i.e. buffer.data is None). It is intended for use-cases where data-copies must be avoid for performance. Can only be used when the buffer has no local data, and requires usage=wgpu.BufferUsage.COPY_DST.

The offset is expressed as an integer number of items. Note that in contrast to the update_x methods, multiple calls are not combined; each call to send_data() results in one upload operation.

Example:

buf = gfx.Buffer(
    nitems=64,
    nbytes=64*4*3,
    format="3xf4",
    usage=wgpu.BufferUsage.COPY_DST,
    force_contiguous=True,
)

set_data(data)

Reset the data to a new array.

This avoids a data-copy compared to doing buffer.data[:] = new_data. The new data must fit the buffer’s shape and format.

update_full(): Mark the whole data for upload.

update_indices(indices): Mark specific item indices for upload.

update_range(offset=0, size=None)

Mark a certain range of the data for upload to the GPU.

The offset and size are expressed in integer number of items.

Examples

Colormap Channels

Colormap Mesh

Morph Targets

Volume and Mesh Slicing 1

Full-Screen Post Processing 1

Mesh Colormaps

Validate send_data