Enum TensorDyn 

#[non_exhaustive]
pub enum TensorDyn {
    U8(Tensor<u8>),
    I8(Tensor<i8>),
    U16(Tensor<u16>),
    I16(Tensor<i16>),
    U32(Tensor<u32>),
    I32(Tensor<i32>),
    U64(Tensor<u64>),
    I64(Tensor<i64>),
    F16(Tensor<f16>),
    F32(Tensor<f32>),
    F64(Tensor<f64>),
}

Type-erased tensor. Wraps a Tensor<T> with runtime element type.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

U8(Tensor<u8>)

Unsigned 8-bit integer tensor.

I8(Tensor<i8>)

Signed 8-bit integer tensor.

U16(Tensor<u16>)

Unsigned 16-bit integer tensor.

I16(Tensor<i16>)

Signed 16-bit integer tensor.

U32(Tensor<u32>)

Unsigned 32-bit integer tensor.

I32(Tensor<i32>)

Signed 32-bit integer tensor.

U64(Tensor<u64>)

Unsigned 64-bit integer tensor.

I64(Tensor<i64>)

Signed 64-bit integer tensor.

F16(Tensor<f16>)

16-bit floating-point tensor.

F32(Tensor<f32>)

32-bit floating-point tensor.

F64(Tensor<f64>)

64-bit floating-point tensor.

Implementations

impl TensorDyn

pub fn as_typed<T: Element>(&self) -> Option<&Tensor<T>>

Borrow this tensor as a statically-typed Tensor<T>, or None when the element type does not match.

pub fn as_typed_mut<T: Element>(&mut self) -> Option<&mut Tensor<T>>

Mutably borrow this tensor as a statically-typed Tensor<T>, or None when the element type does not match.

impl TensorDyn

pub fn dtype(&self) -> DType

Return the runtime element type discriminant.

pub fn pin_host(&self, access: CpuAccess) -> Result<HostPin<'static>>

Return the tensor shape. Cross-package protocol descriptor (see crate::protocol).

This is the contract between independently-linked EdgeFirst packages: they cannot share a Rust or PyO3 type, so they exchange this instead. Pin a stable host address for this tensor’s data.

See Tensor::pin_host. Dispatches to the concrete element type behind the erasure. Returns a 'static pin.

TensorDyn erases to a fixed set of concrete numeric element types, all of which are 'static, so the keepalive genuinely can outlive any borrow — which is what lets a pin cross into a PyCapsule handed to Python. Eliding to &self’s lifetime here would make the pin escape its own producer.

pub fn map_bytes(&self, access: CpuAccess) -> Result<HostView<'static, u8>>

Map this tensor’s whole extent for CPU access, type-erased to raw bytes. Returns a 'static view.

TensorDyn has no byte-level counterpart to TensorTrait::map_with — every typed Tensor<T> maps to HostView<'_, T>, and a type-erased caller (a C ABI consumer, which does not know T) cannot use that. This dispatches exactly the way pin_host and the other dispatch! accessors above do — one arm per concrete element type, calling the same TensorTrait::map_with each typed Tensor<T> already implements (with its declared-vs-requested telemetry, row-stride bookkeeping, and plane-offset handling intact) — then re-views the resulting HostView<'_, T> as HostView<'_, u8> via HostView::into_bytes, which keeps the same underlying pin (so the same platform sync bracket still runs on Drop) and just restates element count as byte count.

The 'static lifetime is the same story as pin_host: map_with’s 'a is a free parameter bounding how long the backing allocation lives, not a borrow of self — the returned view shares ownership through its pin’s keepalive Arc, never a reference into this tensor — and TensorDyn erases to a fixed set of concrete element types that are all 'static, so nothing stops choosing 'a = 'static here. Eliding to &self’s lifetime instead would tie the view to this call’s borrow for no reason, forcing every caller (a C ABI entry point chief among them) into an artificial self-referential shape to hold onto it past this function returning.

Errors

Same as map_with: Error::InvalidArgument for CpuAccess::None, plus whatever the concrete backend’s map can fail with (capacity, stride, or platform-lock errors).

pub fn try_map_bytes(&self, access: CpuAccess) -> Result<HostView<'static, u8>>

Non-blocking map_bytes: returns Err(Error::IoError(WouldBlock)) while a GPU copy the map depends on is still in flight, and makes progress on a retry. Dispatches to each typed tensor’s TensorTrait::try_map_with, which aliases map_with for every backing but the Windows D3D11 texture.

pub fn sync_for_cpu(&self, access: CpuAccess) -> Result<()>

See Tensor::sync_for_cpu.

pub fn sync_for_device(&self, access: CpuAccess) -> Result<()>

See Tensor::sync_for_device.

pub fn descriptor(&self) -> TensorDesc

pub fn descriptor_pinned(&self, pin: Option<&HostPin<'_>>) -> TensorDesc

Descriptor carrying a pinned host address.

A bare descriptor is descriptive only: a consumer learns the shape, format and backing kind but cannot reach the bytes. Supplying a HostPin fills in ptr, and the caller is responsible for keeping that pin alive at least as long as the descriptor is used — which is what the capsule keepalive does.

pub fn shape(&self) -> &[usize]

pub fn set_logical_shape(&mut self, shape: &[usize]) -> Result<()>

Set the logical shape to any shape whose bytes fit the allocation, without reshape’s equal-count constraint. See crate::TensorTrait::set_logical_shape.

pub fn capacity_bytes(&self) -> usize

See Tensor::capacity_bytes.

pub fn name(&self) -> String

Return the tensor name.

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

Return the pixel format (None if not an image tensor).

pub fn width(&self) -> Option<usize>

Return the image width (None if not an image tensor).

pub fn height(&self) -> Option<usize>

Return the image height (None if not an image tensor).

pub fn size(&self) -> usize

Return the total size of this tensor in bytes.

pub fn set_dtype(&mut self, dtype: DType) -> Result<()>

Retag this tensor’s element type, keeping its bytes untouched.

The recorded dtype is metadata over the same allocation: U8 and I8 address identical bytes and differ only in how a consumer reads them. edgefirst-image relies on exactly that – a PBO or DMA buffer is allocated as u8 and handed back as i8, with the int8 shader applying an XOR 0x80 bias over the same buffer.

Refuses a dtype of a different width. That is not a retag but a reinterpretation: len() and size() are derived from the shape and the element width, so widening or narrowing here would silently change how many elements the tensor claims to hold over an allocation whose size did not change.

Errors

crate::Error::InvalidArgument when dtype.size() differs from the current dtype’s. The tensor is left untouched.

pub fn memory(&self) -> TensorMemory

Return the memory allocation type.

pub fn cpu_access(&self) -> CpuAccess

The CPU access declared for this tensor at allocation.

See Tensor::cpu_access; dispatches to the concrete element type behind the erasure, the same way memory and dtype do. .writes() on the result is the declaration query a type-erased caller (a C ABI consumer deciding whether a writable map is allowed) needs before mapping – unlike TensorMapTrait::is_writable, which answers a different question about an already-open map guard (“was this particular mapping opened writable”), this answers it about the tensor itself, before any map exists.

pub fn reshape(&mut self, shape: &[usize]) -> Result<()>

Reshape this tensor. Total element count must remain the same.

pub fn set_format(&mut self, format: PixelFormat) -> Result<()>

Attach pixel format metadata to this tensor.

Validates that the tensor’s shape is compatible with the format’s layout (packed, planar, or semi-planar).

Arguments

• format - The pixel format to attach

Returns

Ok(()) on success, with the format stored as metadata on the tensor.

Errors

Returns Error::InvalidShape if the tensor shape doesn’t match the expected layout for the given format.

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

Attach pixel format metadata, consuming and returning self.

Enables builder-style chaining.

Arguments

• format - The pixel format to attach

Returns

The tensor with format metadata attached.

Errors

Returns Error::InvalidShape if the tensor shape doesn’t match the expected layout for the given format.

pub fn colorimetry(&self) -> Option<Colorimetry>

Colorimetry metadata (None = undefined; never auto-filled).

pub fn set_colorimetry(&mut self, c: Option<Colorimetry>)

Attach/clear colorimetry metadata.

pub fn with_colorimetry(self, c: Colorimetry) -> Self

Builder-style colorimetry attach (consumes and returns self).

pub fn row_stride(&self) -> Option<usize>

Row stride in bytes (None = tightly packed).

pub fn effective_row_stride(&self) -> Option<usize>

Effective row stride: stored stride or computed from format and width.

pub fn configure_image( &mut self, width: usize, height: usize, format: PixelFormat, ) -> Result<()>

Set logical dimensions + format to a decoded image, reusing the allocation. See Tensor::configure_image.

pub fn set_row_stride(&mut self, stride: usize) -> Result<()>

Set the row stride in bytes for externally allocated buffers with row padding.

Must be called before the tensor is first used for rendering. The format must be set before calling this method.

pub fn with_row_stride(self, stride: usize) -> Result<Self>

Builder-style: set row stride, consuming and returning self.

pub fn set_row_stride_unchecked(&mut self, stride: usize)

Set the row stride in bytes without format validation. See Tensor::set_row_stride_unchecked. Added for tensor-capi’s ef_tensor_set_row_stride_unchecked (task 17): the dynamic backend needs a type-erased entry point the same way Self::set_row_stride already gives it one for the checked setter.

pub fn plane_offset(&self) -> Option<usize>

Byte offset within the DMA-BUF where image data starts (None = 0).

pub fn view_origin(&self) -> Option<ViewOrigin>

The parent-image snapshot if this tensor is a view/ batch sub-region; None for a whole tensor. See Tensor::view_origin.

pub fn set_plane_offset(&mut self, offset: usize)

Set the byte offset within the DMA-BUF where image data starts.

pub fn batch(&self, n: usize) -> Result<TensorDyn>

Borrow batch element n of a batched tensor (leading N dimension) as a zero-copy view sharing this tensor’s allocation. See Tensor::batch.

pub fn view(&self, region: Region) -> Result<TensorDyn>

Borrow a rectangular spatial sub-region (the destination/source crop) as a zero-copy view sharing this tensor’s allocation. See Tensor::view.

pub fn cuda(&self) -> Option<&CudaHandle>

The CUDA registration for this tensor, if any.

Returns None when no CUDA handle has been attached (the common non-CUDA case). This check is a pure local field read — no thread routing occurs.

pub fn cuda_map(&self) -> Option<CudaMap<'_>>

Fast-fail CUDA map: None when no handle is attached; else maps the PBO through the GL worker and returns a scoped device-pointer guard.

The same try-cuda_map-then-map fallback pattern that applies to Tensor::cuda_map applies here: call cuda_map() first for a zero-copy device pointer; when it returns None (no CUDA handle attached), fall back to the typed host mapping via the inner tensor.

Example

use edgefirst_tensor::TensorDyn;
if let Some(cuda) = t.cuda_map() {
    feed_tensorrt(cuda.device_ptr(), cuda.len());
} else {
    // No CUDA handle — use the typed inner tensor for host access.
    // See Tensor::cuda_map for the full fallback example.
}

pub fn cuda_map_mut(&self) -> Option<CudaMap<'_>>

Writable counterpart of cuda_map. See CudaHandle::map_mut for which backings distinguish the two.

pub fn set_cuda_handle(&mut self, h: CudaHandle)

Attach a CUDA handle (PBO cudaGraphicsGLRegisterBuffer).

pub fn is_cuda_attached(&self) -> bool

Whether a CUDA registration is attached.

pub fn quantization(&self) -> Option<&Quantization>

Quantization metadata. Returns None for float variants (F16, F32, F64) — quantization does not apply to floating-point tensors. Otherwise delegates to the typed Tensor<T>::quantization() accessor.

pub fn set_quantization(&mut self, q: Quantization) -> Result<()>

Attach quantization metadata. Fails on float variants with crate::Error::QuantizationInvalid; delegates to the typed setter for integer variants.

pub fn with_quantization(self, q: Quantization) -> Result<Self>

Builder-style variant of Self::set_quantization. Consumes self and returns it with quantization applied (or the original error).

pub fn clear_quantization(&mut self)

Clear any quantization metadata. No-op on float variants.

pub fn clone_fd(&self) -> Result<OwnedFd>

Clone the file descriptor associated with this tensor.

pub fn dmabuf_clone(&self) -> Result<OwnedFd>

Clone the DMA-BUF file descriptor backing this tensor (Linux only).

Returns

An owned duplicate of the DMA-BUF file descriptor.

Errors

• Error::NotImplemented if the tensor is not DMA-backed (Mem/Shm/Pbo)
• Error::IoError if the fd clone syscall fails (e.g., fd limit reached)

pub fn dmabuf(&self) -> Result<BorrowedFd<'_>>

Borrow the DMA-BUF file descriptor backing this tensor (Linux only).

Returns

A borrowed reference to the DMA-BUF file descriptor, tied to self’s lifetime.

Errors

• Error::NotImplemented if the tensor is not DMA-backed

pub fn is_multiplane(&self) -> bool

Return true if this tensor uses separate plane allocations.

pub fn chroma_dyn(&self) -> Option<TensorDyn>

Owned chroma plane as its own TensorDyn, or None if this is not a two-allocation semi-planar tensor.

pub fn buffer_identity(&self) -> &BufferIdentity

Return the BufferIdentity of the underlying allocation.

Two TensorDyn values share a crate::BufferIdentity::id iff they were produced by cloning the same allocation (e.g. through DmaTensor::try_clone). Separate imports of the same physical buffer (e.g. two from_fd calls on the same dmabuf fd) have distinct identities — use aliases if you need to detect that case.

pub fn aliases(&self, other: &Self) -> bool

Return true if self and other reference the same underlying buffer.

This is the correct check for APIs that require distinct input and output tensors (e.g. ImageProcessor::draw_decoded_masks, where aliasing dst and background would cause the GL backend to read and write the same texture — undefined behaviour on most drivers).

Matching is conservative:

1. Matching crate::BufferIdentity::id → same buffer (always).
2. Matching backing type + matching dmabuf fd number (Linux, DMA tensors only) → same buffer, even across separate from_fd imports in the same process.

Two distinct dup’d fds pointing at the same kernel dma-buf are not detected — there is no cheap way to resolve that without a round-trip through the kernel.

pub fn as_u8(&self) -> Option<&Tensor<u8>>

Returns a shared reference to the inner tensor if the type matches.

pub fn as_u8_mut(&mut self) -> Option<&mut Tensor<u8>>

Returns a mutable reference to the inner tensor if the type matches.

pub fn into_u8(self) -> Result<Tensor<u8>, Self>

Unwraps the inner tensor if the type matches, otherwise returns self as Err. The Err variant is necessarily large (returns the unconsumed TensorDyn).

pub fn as_i8(&self) -> Option<&Tensor<i8>>

Returns a shared reference to the inner tensor if the type matches.

pub fn as_i8_mut(&mut self) -> Option<&mut Tensor<i8>>

Returns a mutable reference to the inner tensor if the type matches.

pub fn into_i8(self) -> Result<Tensor<i8>, Self>

Unwraps the inner tensor if the type matches, otherwise returns self as Err. The Err variant is necessarily large (returns the unconsumed TensorDyn).

pub fn as_u16(&self) -> Option<&Tensor<u16>>

Returns a shared reference to the inner tensor if the type matches.

pub fn as_u16_mut(&mut self) -> Option<&mut Tensor<u16>>

Returns a mutable reference to the inner tensor if the type matches.

pub fn into_u16(self) -> Result<Tensor<u16>, Self>

Unwraps the inner tensor if the type matches, otherwise returns self as Err. The Err variant is necessarily large (returns the unconsumed TensorDyn).

pub fn as_i16(&self) -> Option<&Tensor<i16>>

Returns a shared reference to the inner tensor if the type matches.

pub fn as_i16_mut(&mut self) -> Option<&mut Tensor<i16>>

Returns a mutable reference to the inner tensor if the type matches.

pub fn into_i16(self) -> Result<Tensor<i16>, Self>

Unwraps the inner tensor if the type matches, otherwise returns self as Err. The Err variant is necessarily large (returns the unconsumed TensorDyn).

pub fn as_u32(&self) -> Option<&Tensor<u32>>

Returns a shared reference to the inner tensor if the type matches.

pub fn as_u32_mut(&mut self) -> Option<&mut Tensor<u32>>

Returns a mutable reference to the inner tensor if the type matches.

pub fn into_u32(self) -> Result<Tensor<u32>, Self>

Unwraps the inner tensor if the type matches, otherwise returns self as Err. The Err variant is necessarily large (returns the unconsumed TensorDyn).

pub fn as_i32(&self) -> Option<&Tensor<i32>>

Returns a shared reference to the inner tensor if the type matches.

pub fn as_i32_mut(&mut self) -> Option<&mut Tensor<i32>>

Returns a mutable reference to the inner tensor if the type matches.

pub fn into_i32(self) -> Result<Tensor<i32>, Self>

Unwraps the inner tensor if the type matches, otherwise returns self as Err. The Err variant is necessarily large (returns the unconsumed TensorDyn).

pub fn as_u64(&self) -> Option<&Tensor<u64>>

Returns a shared reference to the inner tensor if the type matches.

pub fn as_u64_mut(&mut self) -> Option<&mut Tensor<u64>>

Returns a mutable reference to the inner tensor if the type matches.

pub fn into_u64(self) -> Result<Tensor<u64>, Self>

Unwraps the inner tensor if the type matches, otherwise returns self as Err. The Err variant is necessarily large (returns the unconsumed TensorDyn).

pub fn as_i64(&self) -> Option<&Tensor<i64>>

Returns a shared reference to the inner tensor if the type matches.

pub fn as_i64_mut(&mut self) -> Option<&mut Tensor<i64>>

Returns a mutable reference to the inner tensor if the type matches.

pub fn into_i64(self) -> Result<Tensor<i64>, Self>

Unwraps the inner tensor if the type matches, otherwise returns self as Err. The Err variant is necessarily large (returns the unconsumed TensorDyn).

pub fn as_f16(&self) -> Option<&Tensor<f16>>

Returns a shared reference to the inner tensor if the type matches.

pub fn as_f16_mut(&mut self) -> Option<&mut Tensor<f16>>

Returns a mutable reference to the inner tensor if the type matches.

pub fn into_f16(self) -> Result<Tensor<f16>, Self>

Unwraps the inner tensor if the type matches, otherwise returns self as Err. The Err variant is necessarily large (returns the unconsumed TensorDyn).

pub fn as_f32(&self) -> Option<&Tensor<f32>>

Returns a shared reference to the inner tensor if the type matches.

pub fn as_f32_mut(&mut self) -> Option<&mut Tensor<f32>>

Returns a mutable reference to the inner tensor if the type matches.

pub fn into_f32(self) -> Result<Tensor<f32>, Self>

Unwraps the inner tensor if the type matches, otherwise returns self as Err. The Err variant is necessarily large (returns the unconsumed TensorDyn).

pub fn as_f64(&self) -> Option<&Tensor<f64>>

Returns a shared reference to the inner tensor if the type matches.

pub fn as_f64_mut(&mut self) -> Option<&mut Tensor<f64>>

Returns a mutable reference to the inner tensor if the type matches.

pub fn into_f64(self) -> Result<Tensor<f64>, Self>

Unwraps the inner tensor if the type matches, otherwise returns self as Err. The Err variant is necessarily large (returns the unconsumed TensorDyn).

pub fn new( shape: &[usize], dtype: DType, memory: Option<TensorMemory>, name: Option<&str>, ) -> Result<Self>

Create a type-erased tensor with the given shape and element type.

pub fn from_fd( fd: OwnedFd, shape: &[usize], dtype: DType, name: Option<&str>, ) -> Result<Self>

Import an existing buffer as a type-erased tensor, taking ownership of its file descriptor. No bytes are copied.

Dispatches to Tensor::from_fd for dtype and inherits its contract in full: on Linux the backend is detected from the fd’s filesystem magic — DMA_BUF_MAGIC imports as TensorMemory::DmaBuf, TMPFS_MAGIC (both /dev/shm and memfd) as TensorMemory::Shm — and any other filesystem is rejected rather than assumed to be shared memory. On non-Linux Unix the fd is always adopted as SHM.

Errors

• Error::UnknownBufferType - the fd is neither a DMA-BUF nor tmpfs-backed; carries the observed fstatfs magic. Linux only.
• Error::UnknownDeviceType - the fd lives on a real block device. Linux only.
• Error::InvalidSize - shape is empty or describes zero elements.
• Error::NixError - a syscall on the descriptor failed.

Callers that require zero-copy must check memory() on the result rather than treating a successful import as proof of DMA backing.

pub unsafe fn from_client_pbo( state: EfClientState, map_fn: EfPboMapFn, unmap_fn: EfPboUnmapFn, buffer_id: u32, size: usize, shape: &[usize], dtype: DType, ) -> Result<TensorDyn>

Build a PBO-backed tensor from a client’s callback channel – the .so-side half of ef_tensor_wrap_pbo.

The GL buffer stays the client’s; what crosses is the channel, per crate::EfClientState’s contract. The result is ordinary TensorStorage::Pbo storage: memory() reports Pbo, map() goes through the client’s map_fn, and view() produces a real PBO sub-view rather than a host placeholder.

Safety

state, map_fn and unmap_fn must satisfy crate::client_state_pbo_ops’s contract.

pub unsafe fn from_raw_host( ptr: *mut u8, shape: &[usize], dtype: DType, name: Option<&str>, ) -> Result<Self>

Wrap a producer’s host pointer as a type-erased tensor without copying, aliasing rather than owning it.

This is Self::from_foreign_ptr with owner: None — the consumer half of the capsule protocol’s HOST kind (crate::protocol::kind::HOST). The descriptor’s ptr is only meaningful while the producer’s capsule keepalive is alive; nothing here takes a reference to extend that lifetime, so the caller (the capsule machinery) is responsible for it. See TensorDyn::import_descriptor for the full contract.

Safety

Same as Self::from_foreign_ptr: ptr must be non-null, aligned to dtype, and valid for shape.product() elements of dtype for as long as the returned tensor — and every view/map sharing its backing — is used.

pub unsafe fn from_raw_host_with_capacity( ptr: *mut u8, shape: &[usize], capacity_bytes: usize, dtype: DType, name: Option<&str>, ) -> Result<Self>

Self::from_raw_host, additionally recording that the producer’s allocation holds capacity_bytes bytes rather than exactly shape.product() * dtype.size() – the consumer half of crate::TensorDesc::capacity. See Tensor::from_foreign_with_capacity for why: a producer’s pool tensor (or one padded to a decoder’s MCU/pitch alignment) is larger than the shape it currently reports, and without this the imported alias would be clamped to today’s shape and unable to grow back into memory the producer actually has.

Safety

Same as Self::from_raw_host, except ptr must be valid for capacity_bytes bytes (or the tight shape footprint, whichever is larger).

pub unsafe fn from_foreign_ptr( ptr: *mut u8, shape: &[usize], dtype: DType, owner: Option<ForeignOwner>, name: Option<&str>, ) -> Result<Self>

Wrap externally-owned memory as a type-erased tensor without copying. The tensor borrows [ptr, ptr + shape.product() * dtype.size()) as TensorMemory::Mem; owner, when Some, co-owns the source so it outlives the tensor (and all derived views/maps). See crate::ForeignOwner and Tensor::from_foreign.

Safety

ptr must be non-null, aligned to the element type, and valid for shape.product() elements of dtype for as long as the returned tensor — and every view/map sharing its backing — is alive. Pass an owner that co-owns the source to uphold that contract.

pub unsafe fn from_foreign_ptr_with_capacity( ptr: *mut u8, shape: &[usize], dtype: DType, capacity_bytes: usize, owner: Option<ForeignOwner>, name: Option<&str>, ) -> Result<Self>

Self::from_foreign_ptr, additionally recording that the allocation behind ptr holds capacity_bytes bytes rather than exactly shape.product() * dtype.size(). See Tensor::from_foreign_with_capacity.

Safety

Same as Self::from_foreign_ptr, except ptr must be valid for capacity_bytes bytes (or the tight shape footprint, whichever is larger).

pub fn pbo_id(&self) -> Option<u32>

GL buffer ID for this PBO. Returns None when the tensor is not PBO-backed.

pub fn pbo_is_mapped(&self) -> Option<bool>

Whether this PBO currently holds (or is establishing) a CPU mapping. None when the tensor is not PBO-backed. See crate::Tensor::pbo_is_mapped.

pub fn pbo_vtable_ptr(&self) -> Option<*const c_void>

The C-ABI PboOpsVtable address for this PBO, for cross-cdylib export via crate::TensorDesc::ptr (see that field’s doc comment). Returns None when the tensor is not PBO-backed.

pub fn pbo_keepalive(&self) -> Option<Arc<dyn Send + Sync>>

A type-erased keepalive that must stay alive for at least as long as Self::pbo_vtable_ptr’s address is used. None when the tensor is not PBO-backed. See crate::pbo::PboTensor::pbo_keepalive’s own doc comment.

pub fn gpu_write_value(&self) -> u64

The fence value of the newest GPU write recorded on this tensor, or 0 when there is none; every platform, 0 off Windows. See Tensor::gpu_write_value.

pub fn copy_to_flat(&self, dst: &mut [u8]) -> Result<()>

Copy the tensor’s logical bytes into dst, compacting away any recorded row-stride padding — see Tensor::copy_to_flat for the full contract. dst.len() must equal the tight byte footprint (shape product × element size).

pub fn image( width: usize, height: usize, format: PixelFormat, dtype: DType, memory: Option<TensorMemory>, access: CpuAccess, ) -> Result<Self>

Create a type-erased image tensor.

Arguments

• width - Image width in pixels
• height - Image height in pixels
• format - Pixel format
• dtype - Element type discriminant
• memory - Optional memory backend (None selects the best available)

Returns

A new TensorDyn wrapping an image tensor of the requested element type.

Errors

Returns an error if the underlying Tensor::image call fails.

pub fn image_desc(desc: &ImageDesc) -> Result<Self>

Allocate an image tensor from a declarative crate::ImageDesc request — dispatching on desc.dtype(). See Tensor::image_desc for the compression-request semantics.

pub fn compression(&self) -> Option<CompressionScheme>

The recorded vendor tile-compression scheme (see Tensor::compression).

pub fn image_with_stride( width: usize, height: usize, format: PixelFormat, dtype: DType, row_stride_bytes: usize, memory: Option<TensorMemory>, access: CpuAccess, ) -> Result<Self>

Create a DMA-backed image tensor with an explicit row stride that may exceed the natural width * channels * sizeof(T) pitch.

See Tensor::image_with_stride for the detailed contract and constraints. The TensorDyn wrapper dispatches to the appropriate monomorphised Tensor<T> based on dtype.

Example

use edgefirst_tensor::{CpuAccess, TensorDyn, PixelFormat, DType, TensorMemory};
// Allocate a 3004×1688 RGBA8 canvas with 64-byte pitch alignment
// (12032 bytes per row instead of the natural 12016).
let img = TensorDyn::image_with_stride(
    3004, 1688,
    PixelFormat::Rgba, DType::U8,
    12032,
    Some(TensorMemory::DmaBuf),
    CpuAccess::ReadWrite,
)?;
assert_eq!(img.width(), Some(3004));       // logical, unchanged
assert_eq!(img.effective_row_stride(), Some(12032)); // padded

impl TensorDyn

pub fn into_raw(self) -> Raw

Give up ownership, yielding a raw handle the caller must return to TensorDyn::from_raw or leak.

pub unsafe fn from_raw(p: Raw) -> TensorDyn

Retake ownership of a handle produced by TensorDyn::into_raw.

Safety

p must have come from into_raw in this build and must not have been passed here before.

pub unsafe fn with_raw<R>(p: Raw, f: impl FnOnce(&mut TensorDyn) -> R) -> R

Borrow a TensorDyn from a raw handle for the duration of f. ManuallyDrop prevents ownership — and the destructor — being taken.

Safety

p must be a live handle from into_raw in this build.

impl TensorDyn

pub fn import_descriptor(desc: &TensorDesc) -> Result<Self>

Rebuild a tensor addressing the memory an crate::TensorDesc describes — the consumer half of the cross-package tensor protocol (see crate::protocol’s module docs).

Borrow semantics. The result aliases the producer’s memory; it is valid only while the producer keeps that memory alive. For the capsule protocol, that is the capsule’s own lifetime: the capsule’s keepalive holds the producing tensor (and, for a HOST descriptor, its pin) for as long as the capsule itself is alive. A DMABUF import is the one exception with its own, narrower guarantee — this function dups the fd, so the imported tensor’s fd stays valid even after the producer’s tensor drops (closing its own copy); the underlying dma-buf allocation itself is still only alive as long as some fd or GPU import references it. D3D11_TEXTURE behaves the same way for the same reason: the import duplicates the texture and fence NT handles it keeps, so the result outlives the producer’s tensor while the texture itself lives as long as some handle or view references it. Both of the descriptor’s handle values must be valid in this process — the protocol duplicates, it does not reach into another process’s handle table (the blob transport does; see crate::blob::import). A consumer needing to survive past the capsule for any other kind (HOST, IOSURFACE) must take its own reference explicitly — this function does not.

Errors

• Error::NotImplemented — an ABI major this build does not understand (desc.version), a dtype/kind code this build does not recognise, or a kind this platform cannot import (e.g. dma-buf off Linux).
• Error::InvalidArgument — a malformed descriptor: a missing fd/surface id/host address for the kind it claims to be, or (macOS/iOS) a surface id that no longer resolves to a live IOSurface.

Trait Implementations

impl Debug for TensorDyn

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

Formats the value using the given formatter.

impl From<Tensor<f16>> for TensorDyn

fn from(t: Tensor<f16>) -> Self

Converts to this type from the input type.

impl From<Tensor<f32>> for TensorDyn

fn from(t: Tensor<f32>) -> Self

Converts to this type from the input type.

impl From<Tensor<f64>> for TensorDyn

fn from(t: Tensor<f64>) -> Self

Converts to this type from the input type.

impl From<Tensor<i8>> for TensorDyn

fn from(t: Tensor<i8>) -> Self

Converts to this type from the input type.

impl From<Tensor<i16>> for TensorDyn

fn from(t: Tensor<i16>) -> Self

Converts to this type from the input type.

impl From<Tensor<i32>> for TensorDyn

fn from(t: Tensor<i32>) -> Self

Converts to this type from the input type.

impl From<Tensor<i64>> for TensorDyn

fn from(t: Tensor<i64>) -> Self

Converts to this type from the input type.

impl From<Tensor<u8>> for TensorDyn

fn from(t: Tensor<u8>) -> Self

Converts to this type from the input type.

impl From<Tensor<u16>> for TensorDyn

fn from(t: Tensor<u16>) -> Self

Converts to this type from the input type.

impl From<Tensor<u32>> for TensorDyn

fn from(t: Tensor<u32>) -> Self

Converts to this type from the input type.

impl From<Tensor<u64>> for TensorDyn

fn from(t: Tensor<u64>) -> Self

Converts to this type from the input type.