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 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 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).

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 §