pygfx.resources.Texture

class pygfx.resources.Texture(data=None, *, dim, size=None, format=None, colorspace='srgb', generate_mipmaps=False, chunk_size=None, force_contiguous=False, usage=0)

Bases: Resource

The Texture represents structured 1D, 2D or 3D data on the GPU.

A texture can be used to represent e.g. image data or colormaps. They can also serve as a render target (for the renderer). Supports texture stacks, cube textures, and mipmapping.

Parameters:

data (array | None) – The initial data of the texture. It must support the buffer-protocol, (e.g. a bytes or numpy array). If None, size and forma must be provided. The data will be accessible at texture.data, no copies are made. The dtype must be compatible with wgpu texture formats.
dim (int) – The dimensionality of the array (1, 2 or 3).
size (tuple | None) – The extent (width, height, depth) of the array. If None, it is derived from dim and the shape of the data. The texture can also represent a stack of images by setting dim=2 and depth > 1, or a cube image by setting dim=2 and depth==6.
format (None | str | ElementFormat | wgpu.TextureFormat) – A format string describing the pixel/voxel format. This can follow pygfx’ ElementFormat e.g. “1xf4” for intensity, “3xu1” for rgb, etc. Can also be wgpu’s TextureFormat. Optional: if None, it is automatically determined from the data.
colorspace (str) – If this data is used as color, it is interpreted to be in this colorspace. Can be “srgb” or “physical”. Default “srgb”.
generate_mipmaps (bool) – If True, automatically generates mipmaps when transferring data to the GPU. Default False.
chunk_size (None | tuple | int) – The chunk size to use for uploading data to the GPU, expressed in elements (not bytes). When None (default) an optimal chunk size is determined automatically. A 3-tuple can be given to provide a size for each dimension, or an integer to apply for all dimensions.
force_contiguous (bool) – When set to true, the texture 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.TextureUsage) – The wgpu usage flag for this texture. Optional: typically pygfx can derive how the texture 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.
needed (extra memory-copies may be) – at upload time, which reduces performance when the data is changed often.
wgpu (* RGB textures do not exist in) – This may introduce extra memory copies, which reduces performance when data is changed often.
texture. (but are emulated with an RGBA) – This may introduce extra memory copies, which reduces performance when data is changed often.
and (* Setting force_contiguous ensures that the set data is contiguous) – not RGB, it is recommended to use this when the texture data is dynamic.

property dim: The dimensionality of the texture (1, 2, or 3).

property data

The data for this texture.

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

Can be None if the data only exists on the GPU. This is a view on the same memory as .data. It’s .shape[:3] matches reversed(size).

property nbytes: Get the number of bytes in the texture.

property size: The size of the texture as (width, height, depth). (always a 3-tuple, regardless of the dimension).

property format

The texture format.

Usually a pygfx format specifier (e.g. ‘u2’ for scalar uint16, or ‘3xf4’ for RGB float32), but can also be a value from wgpu.TextureFormat.

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

property colorspace: If this data is used as color, it is interpreted to be in this colorspace. Can be “srgb” or “physical”. Default “srgb”.

property generate_mipmaps: Whether to automatically generate mipmaps when uploading to the GPU.

set_data(data)

Reset the data to a new array.

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

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

update_indices(indices_x, indices_y, indices_z)

Mark specific indices for upload.

The given arrays represent the indices for x, y, and z, respectively. So they must be equal in length, similar to what np.where() returns. They can also be None, to indicate the full range, like “:” does with slicing.

update_range(offset, size): Mark a certain range of the data for upload to the GPU. The offset and (sub) size should be (width, height, depth) tuples. Numpy users beware that an arrays shape is (height, width)!