warp.Texture

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

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

This class handles 1D, 2D, and 3D textures. The dimensionality is provided explicitly via ndim or by using the Texture1D, Texture2D, or Texture3D subclasses.

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 wp.uint8, wp.uint16, wp.uint32, wp.int8, wp.int16, wp.int32, wp.float16, and wp.float32 data types. Unsigned integer textures are read as normalized floats in [0, 1]; signed integer textures are normalized to [-1, 1]; float types are returned as-is.

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

__init__(

data=None,

width=0,

height=0,

depth=0,

num_channels=1,

dtype=float32,

filter_mode=1,

address_mode=None,

address_mode_u=None,

address_mode_v=None,

address_mode_w=None,

normalized_coords=True,

device=None,

ndim=None,

surface_access=False,

)

Create a texture.

Parameters:

• data (np.ndarray | array | None) – Initial texture data as a NumPy array or Warp array. For 1D: shape (width,) or (width, num_channels). For 2D: shape (height, width), (height, width, 2), or (height, width, 4). For 3D: shape (depth, height, width), (depth, height, width, 2), or (depth, height, width, 4). Supported dtypes: wp.uint8, wp.uint16, wp.uint32, wp.int8, wp.int16, wp.int32, wp.float16, wp.float32.

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

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

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

• num_channels (int) – 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 (int) – Filtering mode — FILTER_POINT or FILTER_LINEAR.

• address_mode (int | tuple[int, ...] | None) – Address mode for all axes — ADDRESS_WRAP, ADDRESS_CLAMP, ADDRESS_MIRROR, or ADDRESS_BORDER. Can be a single int or a tuple of per-axis values.

• address_mode_u (int | None) – Per-axis address mode for U. Overrides address_mode if specified.

• address_mode_v (int | None) – Per-axis address mode for V. Overrides address_mode if specified.

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

• normalized_coords (bool) – If True, coordinates are in [0, 1] range. If False, coordinates are in texel space.

• device (DeviceLike) – Device on which to create the texture.

• ndim (int | None) – Explicit dimensionality (1, 2, or 3). Required when constructing the base Texture class directly.

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

Methods

__init__([data, width, height, depth, ...])

Create a texture.

Attributes

ADDRESS_BORDER	Return 0 for coordinates outside [0, 1].
ADDRESS_CLAMP	Clamp coordinates to [0, 1].
ADDRESS_MIRROR	Mirror coordinates at boundaries.
ADDRESS_WRAP	Wrap coordinates (tile the texture).
FILTER_LINEAR	Bilinear/trilinear filtering.
FILTER_POINT	Nearest-neighbor (point) filtering.
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.
height	Texture height in pixels.
id	Device-independent texture identifier.
ndim	Texture dimensionality (1, 2, or 3).
normalized_coords	Whether texture uses normalized coordinates.
num_channels	Number of channels.
width	Texture width in pixels.

ADDRESS_WRAP = 0

Wrap coordinates (tile the texture).

ADDRESS_CLAMP = 1

Clamp coordinates to [0, 1].

ADDRESS_MIRROR = 2

Mirror coordinates at boundaries.

ADDRESS_BORDER = 3

Return 0 for coordinates outside [0, 1].

FILTER_POINT = 0

Nearest-neighbor (point) filtering.

FILTER_LINEAR = 1

Bilinear/trilinear filtering.

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 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 cuda_texture: int

CUDA texture object handle.

Returns:

CUDA cudaTextureObject_t handle for CUDA textures.

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