Struct CudaPtr2D 

pub struct CudaPtr2D { /* private fields */ }

2D (pitched) CUDA device pointer (CUdeviceptr aliased as u64).

For multi-plane formats (NV12 / P010 / I420 …) ptr points at the first plane (Y). Subsequent planes live at producer-defined byte offsets carried in Self::plane_byte_offsets — when set, the importer trusts them verbatim. When None, importers fall back to the trivial format-inferred offset (row_pitch * height for plane 1 in NV12 / P010, etc.), which only matches producers that allocate planes back-to-back at the user-specified height. NVDEC’s cuMemAllocPitch pool rounds the Y-plane footprint up to a driver-chosen alignment, so producers wrapping NVDEC frames must call Self::with_plane_byte_offsets with the actual data[i] - data[0] offsets they observed.

Intrinsic dimensions. Unlike D3D11Texture / VkImage / MetalTextureHandle, a CUdeviceptr is opaque memory — there is no driver-side metadata to query for (width, height). Producers that know the logical dimensions attach them via Self::with_size, and any importer that wasn’t given an explicit size from the caller side falls back to this hint — an auto-import path typically has no size context of its own.

Implementations

impl CudaPtr2D

pub unsafe fn try_from_raw( ptr: u64, row_pitch: u32, uuid: Option<[u8; 16]>, keep_alive: Option<KeepAlive>, ) -> Result<Self, InvalidHandleError>

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

Safety

• ptr must be a live CUdeviceptr — device memory that is currently allocated (cuMemAlloc, cuMemAllocPitch, an NVDEC pool slot, or a cuExternalMemoryGetMappedBuffer mapping) and not yet freed. Only ptr == 0 is checked, and it is reported as InvalidHandleError::NullHandle rather than being a caller obligation.
• Context affinity. A CUdeviceptr is meaningful only inside the CUDA context that allocated it (or a context sharing its address space via unified addressing). The caller must ensure the consumer runs against that context; the handle carries no context of its own, only uuid.
• uuid, when Some, must equal the CUDA device’s CUuuid as reported by cuDeviceGetUuid. Importers compare it against the wgpu adapter’s UUID to refuse cross-GPU imports; a wrong value defeats that check.
• row_pitch must be the plane-0 device row pitch in bytes, as returned by cuMemAllocPitch or reported by the producer. It is what every consumer multiplies by the row index, so an under-sized value reads a shifted image and an over-sized one reads past the allocation.
• Extent: this constructor is given no dimensions, so nothing here bounds the reads a consumer will make. The allocation must be large enough for whatever extent the consumer is later told about — via Self::with_size or the caller’s import size — at row_pitch stride, including every plane reachable through Self::with_plane_byte_offsets / Self::with_plane_row_pitches.
• Lifetime: nothing is retained and there is no Drop, so cuMemFree (or the pool slot’s recycle) must not run while this value or any Clone of it is reachable. Pass a keep_alive anchor to discharge that; with None the caller carries it.
• No thread affinity beyond CUDA’s own: the pointer is valid on any thread that has the owning context current, which is what backs the unsafe impl Send + Sync below.

pub fn with_plane_byte_offsets(self, offsets: [u32; 3]) -> Self

Attach explicit per-plane byte offsets (planes 1, 2, 3 relative to ptr). Used by producers whose pool layout deviates from the trivial row_pitch * height rule — NVDEC being the canonical example. Pass 0 for unused tail entries.

pub fn with_plane_row_pitches(self, pitches: [u32; 3]) -> Self

Attach explicit per-plane device row pitches (bytes) for planes 1, 2, 3 (plane 0 uses Self::row_pitch). Required only when a producer’s planes do NOT all share one pitch; the NVDEC / cuMemAllocPitch single-allocation layout ties every plane to row_pitch, so those producers leave this None. Pass 0 for unused tail entries.

pub fn with_size(self, width: u32, height: u32) -> Self

Attach the logical (width, height) of the foreign frame (luma plane for multi-plane formats). See the struct-level docs for why CUDA needs this when D3D11 / Vulkan / Metal don’t.

pub fn with_format(self, format: PixelFormat) -> Self

Attach the pixel format of the foreign frame. Importers fall back to this when the caller passes no explicit format.

pub fn ptr(&self) -> u64

pub fn row_pitch(&self) -> u32

pub fn plane_byte_offsets(&self) -> Option<[u32; 3]>

Per-plane byte offsets, when the producer attached them. See the struct-level docs for the semantics of None.

pub fn plane_row_pitches(&self) -> Option<[u32; 3]>

Raw per-plane device row pitches (planes 1, 2, 3), when the producer attached them. None ⇒ every plane shares Self::row_pitch. Prefer Self::plane_row_pitch for the resolved-with-fallback value at a given plane index.

pub fn plane_row_pitch(&self, index: u8) -> u32

Device row pitch (bytes) of plane index, resolved against the None-means-uniform contract: plane 0 (and any plane the producer left unset) returns Self::row_pitch; planes 1..=3 return their explicit pitch when Self::with_plane_row_pitches supplied a non-zero entry. index >= 4 clamps to plane 0.

pub fn size(&self) -> Option<(u32, u32)>

Logical (width, height) hint, when the producer attached them. Importers fall back to this when no explicit import size is available.

pub fn format(&self) -> Option<PixelFormat>

Pixel format hint. Importers fall back to this when the caller passes no explicit format.

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

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

Trait Implementations

impl Clone for CudaPtr2D

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 CudaPtr2D

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

Formats the value using the given formatter.

impl Send for CudaPtr2D

impl Sync for CudaPtr2D