warp.Texture

class warp.Texture(*args, **kwargs)

Texture base class for hardware-accelerated sampling on GPU and software sampling on CPU.

Experimental

The texture API is experimental and subject to change without a formal deprecation cycle.

Textures provide hardware-accelerated filtering and addressing for regularly gridded data on CUDA devices. On CPU, software-based filtering and addressing is used. Supports linear/bilinear/trilinear interpolation and various addressing modes (wrap, clamp, mirror, border).

Supports warp.uint8, warp.uint16, warp.uint32, warp.int8, warp.int16, warp.int32, warp.float16, and warp.float32 data types. Unsigned 8- and 16-bit integer textures are read as normalized floats in [0, 1]; signed 8- and 16-bit integer textures are normalized to [-1, 1]; float types are returned as-is. Sampling a warp.uint32 or warp.int32 texture causes kernel execution to fail, but these dtypes remain usable for storage, copies, and interop; see texture_sample().

This class should not be instantiated directly. A specific subclass should be used instead (Texture1D, Texture2D, or Texture3D).

Example:

import warp as wp
import numpy as np

# Create a 1D texture
data_1d = np.random.rand(256).astype(np.float32)
tex1d = wp.Texture1D(data_1d, device="cuda:0")
# Create a 2D texture
data_2d = np.random.rand(256, 256).astype(np.float32)
tex2d = wp.Texture2D(data_2d, device="cuda:0")
# Create a 3D texture
data_3d = np.random.rand(64, 64, 64).astype(np.float32)
tex3d = wp.Texture3D(data_3d, device="cuda:0")

Create a texture.

Parameters:

• ndim – Number of texture dimensions.

• data – Initial texture data as a NumPy array or Warp array. For 1D: shape (width,) or (width, num_channels). For 2D: shape (height, width) or (height, width, num_channels). For 3D: shape (depth, height, width) or (depth, height, width, num_channels). Supported dtypes: warp.uint8, warp.uint16, warp.uint32, warp.int8, warp.int16, warp.int32, warp.float16, warp.float32. warp.uint32 and warp.int32 data can be stored and copied but not sampled.

• width – Texture width (required if data is None).

• height – Texture height (required if data is None).

• depth – Texture depth (required if data is None for 3D textures).

• num_channels – Number of channels (1, 2, or 4). Only used when data is None.

• dtype – Data type. Only used when data is None; otherwise inferred from the data.

• filter_mode – Filtering mode, see TextureFilterMode.

• address_mode – Address mode for all axes, see TextureAddressMode. Can be a single int or a tuple of per-axis values.

• address_mode_u – Per-axis address mode for U. Overrides address_mode if specified.

• address_mode_v – Per-axis address mode for V. Overrides address_mode if specified.

• address_mode_w – Per-axis address mode for W (3D only). Overrides address_mode if specified.

• normalized_coords – If True, coordinates are in [0, 1] range. If False, coordinates are in texel space. Mipmapped textures on a CUDA device require normalized_coords=True.

• num_mip_levels – Number of mipmap levels to allocate. Use 1 (default) to disable mipmapping. Use 0 to allocate the full mip chain down to a 1x1 (or 1x1x1) base level. When data is provided and num_mip_levels != 1, Warp auto-generates the lower mip levels using a 2x box filter. Requires data on construction; mipmap contents are immutable afterwards.

• mip_filter_mode – Filter mode used to blend between mip levels when sampling with a non-integer LOD, see TextureFilterMode.

• device – Device on which to create the texture.

• surface_access – If True and device is CUDA, allocates the backing CUDA array with surface load/store support so cuda_surface can be used.

• cuda_array – CUDA array handle to wrap an external texture (cudaArray_t).

Methods

copy_from(src)	Copy texture data from a source.
copy_to(dst)	Copy texture data to a destination.

Attributes

address_mode_u	Address mode for U axis.
address_mode_v	Address mode for V axis.
address_mode_w	Address mode for W axis (3D only).
cuda_array	CUDA array handle backing this texture.
cuda_surface	CUDA surface object handle backing this texture.
cuda_texture	CUDA texture object handle.
depth	Texture depth in pixels (1 for 2D textures).
dtype	Data type of the texture.
filter_mode	Filter mode used for intra-level sampling, see TextureFilterMode.
height	Texture height in pixels.
id	Device-independent texture identifier.
is_mipmapped	Whether the texture was allocated with more than one mip level.
mip_filter_mode	Filter mode used to blend between mip levels, see TextureFilterMode.
ndim	Texture dimensionality (1, 2, or 3).
normalized_coords	Whether texture uses normalized coordinates.
num_channels	Number of channels.
num_mip_levels	Number of mip levels allocated for this texture (1 if not mipmapped).
width	Texture width in pixels.

copy_from(src)

Copy texture data from a source.

Parameters:

src (array | numpy.ndarray | Texture) – The source can be a Warp array on the same device as the texture, a CPU Warp array, a NumPy array, or another texture.

copy_to(dst)

Copy texture data to a destination.

Parameters:

dst (array | numpy.ndarray | Texture) – The destination can be a Warp array on the same device as the texture, a CPU Warp array, a NumPy array, or another texture.

property ndim: int

Texture dimensionality (1, 2, or 3).

property width: int

Texture width in pixels.

property height: int

Texture height in pixels.

property depth: int

Texture depth in pixels (1 for 2D textures).

property num_channels: int

Number of channels.

property dtype

Data type of the texture.

property filter_mode: TextureFilterMode

Filter mode used for intra-level sampling, see TextureFilterMode.

property mip_filter_mode: TextureFilterMode

Filter mode used to blend between mip levels, see TextureFilterMode.

property num_mip_levels: int

Number of mip levels allocated for this texture (1 if not mipmapped).

property is_mipmapped: bool

Whether the texture was allocated with more than one mip level.

property address_mode_u: int

Address mode for U axis.

property address_mode_v: int

Address mode for V axis.

property address_mode_w: int

Address mode for W axis (3D only).

property normalized_coords: bool

Whether texture uses normalized coordinates.

property id: int

Device-independent texture identifier.

On CUDA textures, this is the same handle as cuda_texture (cudaTextureObject_t). On host textures, this is the backing host texture handle.

property cuda_array: int

CUDA array handle backing this texture.

Returns:

CUDA cudaArray_t handle for non-mipmapped CUDA textures.

property cuda_texture: int

CUDA texture object handle.

Returns:

CUDA cudaTextureObject_t handle for CUDA textures.

property cuda_surface: int

CUDA surface object handle backing this texture.

The surface object is created lazily on first access and cached for the texture lifetime.

Returns:

CUDA cudaSurfaceObject_t handle for CUDA textures with surface_access=True.