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

Examples

Offscreen Rendering

Offscreen Rendering

Orbit Camera

Orbit Camera

Use gfx.show to show a Scene

Use gfx.show to show a Scene

Geometry Image

Geometry Image

Show Image

Show Image

Geometry Cubes

Geometry Cubes

Minip Volume Rendering

Minip Volume Rendering

Torus knot

Torus knot

Mesh dynamic

Mesh dynamic

Line Segments

Line Segments

Volume Slice 1

Volume Slice 1

Transform Control without Matrix Updating

Transform Control without Matrix Updating

Simulating grass with point sprites

Simulating grass with point sprites

Geometry Plane

Geometry Plane

Toon Rendering 1

Toon Rendering 1

Bounding Box Coordinates

Bounding Box Coordinates

Volume Slice 2

Volume Slice 2

Measure distances in 2D

Measure distances in 2D

Image with Points Overlaid

Image with Points Overlaid

Use a Skybox

Use a Skybox

Physical Color

Physical Color

Panzoom Camera

Panzoom Camera

Instancing

Instancing

Synced Video Rendering

Synced Video Rendering

Color Picking

Color Picking

Colormap Channels

Colormap Channels

Image with another image overlaid

Image with another image overlaid

Volume Rendering 1

Volume Rendering 1

Displaying an image in a scene

Displaying an image in a scene

Paint to a texture

Paint to a texture

Paint to a texture directly

Paint to a texture directly

Use a Skybox

Use a Skybox

Measure distances in 3D

Measure distances in 3D

Nested Scenes

Nested Scenes

PBR Rendering 1

PBR Rendering 1

Mesh and Volume Slicing 2

Mesh and Volume Slicing 2

Lightmap

Lightmap

Volume and Mesh Slicing 1

Volume and Mesh Slicing 1

Mesh Picking

Mesh Picking

Ambient occlusion

Ambient occlusion

Dynamic Environment Map

Dynamic Environment Map

Image Click Events

Image Click Events

Colormap Image

Colormap Image

Subplots Video

Subplots Video

Labelled Image Grid

Labelled Image Grid

PBR Rendering 2

PBR Rendering 2

Environment Map Effects

Environment Map Effects

Mesh with quads

Mesh with quads

Toon Rendering 2

Toon Rendering 2

Earth

Earth

Colormap Mesh

Colormap Mesh

Remote glTF Viewer

Remote glTF Viewer

Video YUV

Video YUV

Audio Visualizer

Audio Visualizer

Image Material

Image Material

Image on Plane Geometry 1

Image on Plane Geometry 1

Simple Colormap

Simple Colormap

srgb texture colorspace

srgb texture colorspace

Tiny Image Validation

Tiny Image Validation

Validate send_data

Validate send_data

Validate Skybox

Validate Skybox

Volume and Volume Slice Rendering

Volume and Volume Slice Rendering

Validate view offset

Validate view offset

Mesh Colormaps

Mesh Colormaps

Mesh slice

Mesh slice

Fullscreen Postprocessing 2

Fullscreen Postprocessing 2

Full-Screen Post Processing 1

Full-Screen Post Processing 1

Interactive Segmentation with SAM2

Interactive Segmentation with SAM2