Crate edgefirst_tensor

Expand description

EdgeFirst HAL - Tensor Module

The edgefirst_tensor crate provides a unified interface for managing multi-dimensional arrays (tensors) with support for different memory types, including Direct Memory Access (DMA), POSIX Shared Memory (Shm), and system memory. The crate defines traits and structures for creating, reshaping, and mapping tensors into memory.

§Examples

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");

§Overview

The main structures and traits provided by the edgefirst_tensor crate are TensorTrait and TensorMapTrait, which define the behavior of Tensors and their memory mappings, respectively. The Tensor<T> struct wraps a backend-specific storage with optional image format metadata (PixelFormat), while the TensorMap enum provides access to the underlying data. The TensorDyn type-erased enum wraps Tensor<T> for runtime element-type dispatch.

Re-exports§

pub use colorimetry::ColorEncoding;
pub use colorimetry::ColorRange;
pub use colorimetry::ColorSpace;
pub use colorimetry::ColorTransfer;
pub use colorimetry::Colorimetry;
pub use colorimetry::MatrixWeights;
pub use colorimetry::RangeScaling;

Modules§

colorimetry: Colorimetry metadata for image/video tensors.
covguard: Coverage-capture resilience for crash-on-shutdown hardware (e.g. the i.MX Vivante EGL driver SIGABRTs during teardown after tests pass). Under coverage instrumentation only, install a SIGABRT handler that flushes the LLVM profile to LLVM_PROFILE_FILE before the abort completes, then restores the default disposition and re-raises so the process exit status is unchanged (the CI workflow already treats JUnit as the source of truth).

Structs§

BufferIdentity: Unique identity for a tensor’s underlying buffer.
ChromaLayout: Chroma addressing parameters for a semi-planar (NV12/NV16/NV24) format — the single source of truth shared by the codec writer, CPU readers, and the Linux + macOS GL shaders. See PixelFormat::chroma_layout.
CudaHandle: CUDA registration for a GPU-backed tensor. Held as Option on the tensor.
CudaMap: Scoped CUDA device-pointer mapping. Drop unmaps a GlBuffer (so GL may reuse the PBO for the next convert() call). ExternalMem mappings are persistent — Drop is a no-op.
PackedRgba16fLayout: Geometry of the RGBA16F-packed surface backing a planar F16 image tensor.
PboMap
PboMapping: Raw mapped pointer from a PBO. CPU-accessible while the buffer is mapped. The pointer is only valid between map and unmap calls.
PboTensor: A tensor backed by an OpenGL Pixel Buffer Object.
PlaneDescriptor: Per-plane DMA-BUF descriptor for external buffer import.
Quantization: Quantization parameters for an integer tensor.
Region: A rectangular sub-region of a tensor’s leading spatial frame, in pixels.
Tensor: Multi-backend tensor with optional image format metadata.
ViewOrigin: The parent image a view/batch sub-region was carved from, snapshotted at the time the view was created.
f16: Re-export of half::f16 so downstream crates can write Tensor::<edgefirst_tensor::f16>::from_iosurface(…) without adding half to their own dependency list. The version stays in lockstep with the half workspace dep. A 16-bit floating point type implementing the IEEE 754-2008 standard binary16 a.k.a “half” format.

Enums§

DType: Element type discriminant for runtime type identification.
Error
PixelFormat: Pixel format identifier.
PixelLayout: Memory layout category.
QuantMode: Semantic mode discriminant for hot-path kernel dispatch.
TensorDyn: Type-erased tensor. Wraps a Tensor<T> with runtime element type.
TensorMap
TensorMemory

Traits§

CudaGlOps: Routes cudaGraphicsMapResources/Unmap/Unregister through the GL worker thread (the GL context must be current there). Implemented by the image crate.
IntegerType: Integer element types that may carry quantization metadata.
PboOps: Trait for PBO GL operations, implemented by the image crate.
TensorMapTrait
TensorTrait

Functions§

gl_map_resource: Map a registered resource → (device ptr as usize, size). GL-thread only.
gl_register_buffer: Register a GL buffer (PBO) with CUDA. Returns the resource as usize (pointer) or None. MUST be called on the thread where the GL context is current.
gl_unmap_resource: Unmap a previously mapped resource. GL-thread only.
gl_unregister_resource: Unregister a previously registered resource. GL-thread only.
is_cuda_available: True iff libcudart loaded and all interop symbols resolved. Cached, cheap.
is_dma_available: Check if Linux DMA-BUF allocation is available on this system.
is_gpu_buffer_available: Portable probe for the platform’s native zero-copy GPU buffer allocator (DMA-BUF on Linux, IOSurface on macOS). Returns false on Windows and other platforms with no equivalent. Use this when writing cross-platform code that cares whether the Dma tensor variant will work, not which underlying mechanism is used.
is_iosurface_available
is_shm_available: Check if POSIX shared memory allocation is available on this system.
memcpy_device_to_host^⚠: Copy count bytes from a CUDA device pointer to host. Returns false on failure or if libcudart is unavailable.
packed_rgba16f_layout: Canonical geometry for the RGBA16F-packed surface backing a planar F16 image tensor.
stream_create: Create a CUDA stream. Returns None if libcudart is unavailable or stream creation fails. The returned stream must be released with stream_destroy. Intended for clients (e.g. the codec’s nvJPEG backend) that submit async device work and synchronise on it.
stream_destroy^⚠: Destroy a CUDA stream. No-op if libcudart is unavailable.
stream_synchronize^⚠: Block until all work submitted to stream completes. Returns false on failure or if libcudart is unavailable.

Type Aliases§

CudaStream
ForeignOwner: Opaque keep-alive handle for a foreign-memory tensor (see Tensor::from_foreign / TensorDyn::from_foreign_ptr).
Result