Struct Tensor

Source

pub struct Tensor<T>where
    T: Num + Clone + Debug + Send + Sync,
{ /* private fields */ }

Expand description

Multi-backend tensor with optional image format metadata.

When format is Some, this tensor represents an image. Width, height, and channels are derived from shape + format. When format is None, this is a raw tensor (identical to the pre-refactoring behavior).

Implementations§

Source §

impl<T> Tensor<T>
where T: Num + Clone + Debug + Send + Sync,

Source

pub fn from_slice(values: &[T], shape: &[usize]) -> Result<Self>
where T: Copy,

Construct a tensor from a row-major element slice + shape. Allocates a new buffer (TensorMemory::Mem) and memcpys the contents; caller retains ownership of the input slice.

§Errors

Error::InvalidShape if values.len() != shape.iter().product().
Propagates any allocation error from Self::new.

Source

pub fn from_arrayview3(view: ArrayView3<'_, T>) -> Result<Self>
where T: Copy,

Construct a tensor from a 3-D ndarray view. Respects strides — one copy in all cases; contiguous views take a memcpy fast path.

Only available when the ndarray feature is enabled.

Source

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

Create a new tensor with the given shape, memory type, and optional name. If no name is given, a random name will be generated. If no memory type is given, the best available memory type will be chosen based on the platform and environment variables.

On Linux platforms, the order of preference is: Dma -> Shm -> Mem. On other Unix platforms (macOS), the order is: Shm -> Mem. On non-Unix platforms, only Mem is available.

§Environment Variables

EDGEFIRST_TENSOR_FORCE_MEM: If set to a non-zero and non-false value, forces the use of regular system memory allocation (TensorMemory::Mem) regardless of platform capabilities.

§Example

use edgefirst_tensor::{Error, Tensor, TensorMemory, TensorTrait};
let tensor = Tensor::<f32>::new(&[2, 3, 4], Some(TensorMemory::Mem), Some("test_tensor"))?;
assert_eq!(tensor.memory(), TensorMemory::Mem);
assert_eq!(tensor.name(), "test_tensor");

Source

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

Create an image tensor with the given format.

Source

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

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

Used for image tensors that need GPU pitch alignment padding: the underlying DMA-BUF is sized to row_stride * height bytes, but the tensor’s logical shape stays at [height, width, channels]. width() / height() / shape() continue to report the user-requested values; the padding is visible only via row_stride() / effective_row_stride() and is automatically propagated to the GL backend’s EGLImage import so Mali Valhall accepts the buffer.

§Supported formats

Currently only packed pixel layouts (RGBA8, BGRA8, RGB888, Grey, etc.) are supported — the formats the GL backend uses as render destinations. Semi-planar formats (NV12, NV16) come from external allocators (camera capture, video decoders) and are imported via TensorDyn::from_fd + set_row_stride, which already supports padded strides.

§Supported memory

Currently only TensorMemory::Dma is supported. PBO and Mem storage don’t go through EGLImage import so they don’t need pitch alignment; if you pass any other memory type this returns NotImplemented. None (auto-select) is treated as Dma.

§Errors

InvalidArgument if row_stride_bytes < width * channels * sizeof(T) (the requested stride would not fit a single row)
NotImplemented for non-packed formats or non-DMA memory
IoError if the DMA-heap allocation fails (propagated from DmaTensor::new_with_byte_size)

Source

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

Attach format metadata to an existing tensor.

§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 is incompatible with the format’s layout (packed expects [H, W, C], planar expects [C, H, W], semi-planar expects [H*k, W] with format-specific height constraints).

Source

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

Pixel format (None if not an image).

Source

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

Image width (None if not an image).

Source

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

Image height (None if not an image).

Source

pub fn from_planes( luma: Tensor<T>, chroma: Tensor<T>, format: PixelFormat, ) -> Result<Self>

Create from separate Y and UV planes (multiplane NV12/NV16).

Source

pub fn is_multiplane(&self) -> bool

Whether this tensor uses separate plane allocations.

Source

pub fn chroma(&self) -> Option<&Tensor<T>>

Access the chroma plane for multiplane semi-planar images.

Source

pub fn chroma_mut(&mut self) -> Option<&mut Tensor<T>>

Mutable access to the chroma plane for multiplane semi-planar images.

Source

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

Row stride in bytes (None = tightly packed).

Source

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

Effective row stride in bytes: the stored stride if set, otherwise the minimum stride computed from the format, width, and element size. Returns None only when no format is set and no explicit stride was stored via set_row_stride.

Source

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

Set the row stride in bytes for externally allocated buffers with row padding (e.g. V4L2 or GStreamer allocators).

The stride is propagated to the EGL DMA-BUF import attributes so the GPU interprets the padded buffer layout correctly. Must be called after set_format and before the tensor is first passed to [ImageProcessor::convert]. The stored stride is cleared automatically if the pixel format is later changed.

No stride-vs-buffer-size validation is performed because the backing allocation size is not reliably known: external DMA-BUFs may be over-allocated by the allocator, and internal tensors store a logical (unpadded) shape. An incorrect stride will be caught by the EGL driver at import time.

§Arguments

stride - Row stride in bytes. Must be >= the minimum stride for the format (width * channels * sizeof(T) for packed, width * sizeof(T) for planar/semi-planar).

§Errors

InvalidArgument if no pixel format is set on this tensor
InvalidArgument if stride is less than the minimum for the format and width

Source

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

Set the row stride without format validation.

Use this for raw sub-tensors (e.g. chroma planes) that don’t carry format metadata. The caller is responsible for ensuring the stride is valid.

Source

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

Builder-style variant of set_row_stride, consuming and returning self.

§Errors

Same conditions as set_row_stride.

Source

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

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

Source

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

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

Propagated to EGL_DMA_BUF_PLANE0_OFFSET_EXT on GPU import. Unlike set_row_stride, no format is required since the offset is format-independent.

Source

pub fn with_plane_offset(self, offset: usize) -> Self

Builder-style variant of set_plane_offset, consuming and returning self.

Source

pub fn as_pbo(&self) -> Option<&PboTensor<T>>

Downcast to PBO tensor reference (for GL backends).

Source

pub fn as_dma(&self) -> Option<&DmaTensor<T>>

Downcast to DMA tensor reference (for EGL import, G2D).

Source

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

Borrow the DMA-BUF file descriptor backing this tensor.

§Returns

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

§Errors

Returns Error::NotImplemented if the tensor is not DMA-backed.

Source

pub fn from_pbo(pbo: PboTensor<T>) -> Self

Construct a Tensor from a PBO tensor (for GL backends that allocate PBOs).

Source §

impl<T> Tensor<T>
where T: IntegerType + Num + Clone + Debug + Send + Sync,

Source

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

Quantization metadata for this tensor, if set.

Source

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

Attach quantization metadata to this tensor. Validates against the tensor’s shape — returns Error::QuantizationInvalid on any inconsistency (mismatched scale/zp lengths, out-of-range axis, etc.).

Source

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

Builder-style variant of Self::set_quantization. Consumes self and returns Result<Self> — on success yields the tensor with the attached quantization; on validation failure returns Error::QuantizationInvalid and drops self (the tensor is not returned in the error arm).

Source

pub fn clear_quantization(&mut self)

Clear any quantization metadata on this tensor.

Trait Implementations§

Source §

impl<T> Debug for Tensor<T>
where T: Num + Clone + Debug + Send + Sync + Debug,

Source §

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

Formats the value using the given formatter. Read more

Source §