Struct CudaSurface 

pub struct CudaSurface { /* private fields */ }

Available on crate feature wgpu only.

Opaque CUDA CUsurfObject bound to a CUarray, used as a surf2Dwrite kernel write target.

Unlike CudaPtr2D (flat device memory) this wraps a surface object — the driver handle a kernel writes through into a tiled CUDA array. The array itself is typically a foreign-API texture (D3D12 / Vulkan / GL) imported as a CUmipmappedArray → CUarray, so a CUDA consumer writes post-YUV→RGB pixels straight into a wgpu-readable driver-tiled texture with no intermediate copy.

format carries the array’s element format (the wgpu render-target format the producer allocated — Rgba8Unorm or Rgba16Float). It is informational for the binding ABI (the kernel learns its output format from the params blob, not this handle); it lets the bridge and any diagnostics reason about the surface without a driver query. Because the field is a wgpu::TextureFormat, the whole newtype is gated on the crate’s wgpu feature — matching the precedent set by crate::PlaneFormat::to_wgpu_texture_format: backend-agnostic code carries crate-native types, wgpu types appear only behind the gate.

keep_alive retains the underlying import chain (cuSurfObjectCreate → CUarray → CUmipmappedArray → cuImportExternalMemory) for at least the lifetime of any kernel launch that receives this handle.

Implementations

impl CudaSurface

pub unsafe fn try_from_raw( surf: u64, width: u32, height: u32, format: TextureFormat, uuid: Option<[u8; 16]>, keep_alive: Option<KeepAlive>, ) -> Result<Self, InvalidHandleError>

Wrap a raw CUsurfObject. Borrowing: the handle is stored non-owningly, this type has no Drop, and every obligation below extends to each Clone.

Safety

• surf must be a live CUsurfObject created by cuSurfObjectCreate and not yet destroyed, on the CUDA device identified by uuid when that is Some.
• The bound CUarray must actually have element format format and dimensions width × height. Kernels reached through this handle issue surf2Dwrites sized by format and clipped by width / height; a mismatch writes the wrong number of bytes per texel or past the array’s last row. Zero extents are rejected as InvalidHandleError::InvalidValue and a zero surf as InvalidHandleError::NullHandle, so neither is a caller obligation.
• Lifetime — the whole import chain, not just the surface. keep_alive (or the caller, when it is None) must retain every link of cuSurfObjectCreate → CUarray → CUmipmappedArray → cuImportExternalMemory, and the foreign texture underneath it, for at least as long as any kernel launch that receives this handle can still be running. A surface object outliving its array, or an array outliving the external-memory import, is a use-after-free inside the kernel. Nothing is retained here and there is no Drop.
• The caller must not cuSurfObjectDestroy while this value or any Clone of it is reachable.

pub fn surf(&self) -> u64

pub fn width(&self) -> u32

pub fn height(&self) -> u32

pub fn format(&self) -> TextureFormat

pub fn uuid(&self) -> Option<[u8; 16]>

pub fn keep_alive(&self) -> Option<&KeepAlive>

Trait Implementations

impl Clone for CudaSurface

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CudaSurface

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Send for CudaSurface

impl Sync for CudaSurface