pygfx.resources.Texture

class pygfx.resources.Texture(data=None, *, dim, size=None, format=None, colorspace='srgb', colorrange='limited', 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 format 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”, “tex-srgb”, “physical”, “yuv420p”, or “yuv444p”. Default “srgb”.
colorrange (str) – For YUV textures, this is either “limited”, or “full”. For the limited range, the luma plane is limited between 16-235, and the chroma planes (U and V) are limited to 16-240. While it may seem suboptimal, many videos are stored in the limited colorrange.
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”, “tex-srgb”, “physical”, “yuv420p”, or “yuv444p”. Default “srgb”.

“srgb”: the data represents intensity, rgb, or rgba pixels in the sRGB space. sRGB is a standard color space designed for consistent representation of colors across devices like monitors. Most images store colors in this space. The shader convers sRGB colors to physical in the shader before doing color computations.
“tex-srgb”: the underlying texture will be of an sRGB format. This means the data is automatically converted to sRGB when it is sampled. This results in better glTF compliance (because interpolation in the sampling happens in linear space). Note that sampling always results in the sRGB values, also when not interpreted as color. Only supported for rgb and rgba data.
“physical”: the colors are (already) in the physical / linear space, where lighting calculations can be applied. Shader code that interprets the data as color will use it as-is.
“yuv420p”: A common video format. The data is represented as 3 planes (y, u, and v). The y represents intensity, and is at full resolution. The u and v planes are a quarter of the size. The planes must be stored in two layers of the texture, with the u and v plane next to each-other in top half the second layer.
“yuv444p”: A lesser common video format. The data is represented as 3 planes (y, u, and v) similar to yuv420p however the u and v planes are stored at full resolution.

property colorrange

For YUV textures, this is either “limited”, or “full”.

“limited”: The luma plane (Y) is limited to the range of 16-235 for 8 bits.
The chroma planes (U and V) are limited to the range of 16-240 for 8 bits
“full”: The luma plane and chroma plane use the full range of the storage format.

See the following links from the FFMPEG documentation for more details: https://trac.ffmpeg.org/wiki/colorspace https://ffmpeg.org/doxygen/7.0/pixfmt_8h_source.html#l00609

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

send_data(offset, data)

Send a chunk of data to the GPU.

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

The offset must be a (width, height, depth) tuple. 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:

tex = gfx.Texture(
    size=(64, 64, 1),
    dim=2,
    format=wgpu.TextureFormat.rgba8unorm,
    usage=wgpu.TextureUsage.COPY_DST,
    force_contiguous=True,
)

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