cuda.core.textures.CUDAArray#

class cuda.core.textures.CUDAArray(*args, **kwargs)#

An opaque, hardware-laid-out GPU allocation for texture/surface access.

Distinct from Buffer: a CUarray has no exposed device pointer and can only be accessed from kernels through a TextureObject or SurfaceObject. Its memory layout is chosen by the driver for 2D/3D spatial locality.

Copy-only interop. Because the layout is opaque and there is no linear device pointer, a CUDAArray cannot expose __cuda_array_interface__ / DLPack and cannot be shared zero-copy with NumPy, CuPy, numba-cuda, or PyTorch. Moving data in or out is therefore always a copy: use copy_from() / copy_to() against a linear Buffer or a host buffer-protocol object. There is no allocation helper — allocate the linear Buffer yourself (e.g. mr.allocate(arr.size_bytes, stream=s)) and copy.

Construct via from_descriptor(). Only plain 1D/2D/3D allocations are supported in this initial version; layered/cubemap/sparse variants will follow once their shape semantics are settled.

Methods

__init__(*args, **kwargs)#
close(self)#

Release this object’s reference to the underlying CUarray.

Destruction (cuArrayDestroy) happens via the handle’s deleter when the last reference is dropped; for a non-owning handle (graphics interop or a mipmap-level view) nothing is destroyed. Idempotent: a second call (or destruction after close()) is a no-op.

copy_from(self, src, *, stream) → None#

Copy a full-array’s worth of data into this array.

Parameters:

  • src (Buffer or buffer-protocol object) – Source data. Must contain at least self.size_bytes bytes of contiguous data.

  • stream (Stream or GraphBuilder) – Stream to issue the copy on. A GraphBuilder is accepted so the copy can be captured into a graph.

copy_to(self, dst, *, stream)#

Copy a full-array’s worth of data out of this array.

Parameters:

  • dst (Buffer or writable buffer-protocol object) – Destination. Must have at least self.size_bytes bytes of writable, contiguous space.

  • stream (Stream or GraphBuilder) – Stream to issue the copy on. A GraphBuilder is accepted so the copy can be captured into a graph.

Return type:

The dst object, for parity with Buffer.copy_to().

classmethod from_descriptor(
cls,
*,
shape,
format,
num_channels,
is_surface_load_store=False,
)#

Allocate a new CUDA array.

Parameters:

  • shape (tuple of int) – (width,), (width, height), or (width, height, depth) in elements.

  • format (ArrayFormat) – Element format.

  • num_channels (int) – Channels per element. Must be 1, 2, or 4.

  • is_surface_load_store (bool) – If True, allocate with CUDA_ARRAY3D_SURFACE_LDST so the array can be bound as a SurfaceObject for kernel-side writes. Default False.

Return type:

CUDAArray

Attributes

device#

The Device this array was allocated on.

element_size#

Bytes per element (format size * channels).

format#

The element ArrayFormat.

handle#

The underlying CUarray as an integer.

is_surface_load_store#

True if this array was created with CUDA_ARRAY3D_SURFACE_LDST and can be bound as a SurfaceObject.

num_channels#

Channels per element (1, 2, or 4).

shape#

Allocation shape, in elements.

size_bytes#

Total bytes of array storage (prod(shape) * element_size).