cuda.core.textures.SurfaceObject#

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

A bindless surface handle for kernel-side typed load/store.

Wraps cuSurfObjectCreate. Unlike a TextureObject, a surface has no sampling state (no filtering, no addressing modes, no normalization); kernels read and write through it using integer pixel coordinates.

The backing CUDAArray must have been created with is_surface_load_store=True and is kept alive for the lifetime of this object to prevent dangling handles.

Construct via from_array() or from_descriptor(). Passes to kernels as a 64-bit handle (via the handle property).

Methods

__init__(*args, **kwargs)#

close(self)#

Release this object’s reference to the underlying CUsurfObject.

Destruction (cuSurfObjectDestroy) and release of the backing array happen via the handle’s deleter when the last reference is dropped. Idempotent.

classmethod from_array(cls, array)#

Create a surface object directly from an CUDAArray.

The array must have been created with is_surface_load_store=True.

classmethod from_descriptor(cls, *, resource)#

Create a surface object from a ResourceDescriptor.

Parameters:: resource (ResourceDescriptor) – Must wrap an CUDAArray allocated with is_surface_load_store=True. Linear/pitch2d resources are not valid surface backings.

Attributes

device#

handle#: The underlying CUsurfObject as an integer (64-bit kernel arg).

resource#: The ResourceDescriptor this surface was built from.