Crate edgefirst_tensor

Expand description

EdgeFirst HAL - Tensor Module

The edgefirst_tensor crate provides a unified interface for managing multi-dimensional arrays (tensors) across four memory backends: the platform’s native zero-copy GPU buffer, POSIX shared memory, the system heap, and an OpenGL Pixel Buffer Object. 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); mapping a tensor yields a HostView, which implements TensorMapTrait and derefs to the underlying elements. The TensorDyn type-erased enum wraps Tensor<T> for runtime element-type dispatch.

TensorMemory::DmaBuf is one variant with three implementations behind it — a Linux DMA-heap DMA-BUF, a macOS/iOS IOSurfaceRef, or an Android AHardwareBuffer. Callers ask for Dma and get whichever the platform provides, so portable code never branches on the mechanism.

§Image tensors

Images go through Tensor::image (or Tensor::image_desc for the full-featured request) rather than Tensor::new. Two things set them apart:

They take a CpuAccess declaration (ReadWrite is the default). Hardware access — GPU, NPU, ISP, codec — is always implied; what the CPU intends is the one thing the allocator cannot guess. A CPU map, pin or sync beyond the declaration fails with Error::CpuAccessDenied.
DMA-backed images carry a 64-byte-aligned row stride in every layout, because Mali and Vivante reject an EGLImage import at an unaligned pitch. Read the real pitch from Tensor::effective_row_stride; don’t assume width * bpp.

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;
pub use blob::BlobError;
pub use blob::BlobHeader;
pub use blob::BlobPlane;
pub use blob::BlobStrings;
pub use blob::BlobView;
pub use blob::Regions;
pub use blob::TransportMode;
pub use blob::HEADER_LEN;
pub use blob::PLANE_RECORD_LEN;
pub use lens::Element;
pub use pin::HostPin;
pub use protocol::dtype_to_dtype;
pub use protocol::format as tensor_format;
pub use protocol::format_from_code;
pub use protocol::SendPtr;
pub use protocol::TensorDesc;
pub use protocol::ABI_VERSION;
pub use view::HostView;

Modules§

blob: The tensor blob: a size-prefixed, append-only serialization of a tensor.
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).
d3d11_layout: (PixelFormat, DType, width, height) -> D3D11 texture layout.
lens: Tensor<T> as a typed lens over [TensorDyn].
pin: Persistent host mapping, decoupled from cache coherency.
protocol: The cross-package tensor protocol.
view: One CPU-access window, for every backend.

Macros§

ef_vocabulary: Declare a vocabulary once, emit every surface from it.

Structs§

BorrowedTensor: A TensorDyn borrowed from a raw handle the caller keeps owning, returned by TensorDyn::borrow_raw.
BoundingBox: A bounding box with f32 coordinates in XYXY format
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.
ContentRegion: Where the image content sits in a destination: in pixels, and as [xmin, ymin, xmax, ymax] normalized by the destination size, the form unletter_norm and the semantic decoder take.
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) and copies a writable D3d11 mapping back into the texture. ExternalMem mappings are persistent — Drop is a no-op.
DetectBox: A detection box with f32 bbox and score
EfClientState: Client-owned state a library entry point calls back into — frozen by value, forever, and reused verbatim by every domain that needs one (PBO today; CUDA-GL next).
ImageDesc: Declarative image-allocation request — the full-featured front door for image tensors (TensorDyn::image_desc and the image crate’s ImageProcessor::create_image_desc).
Normalization: Per-channel (x - mean) / std on 0–255 pixel values, in RGB order.
PackedRgb888Layout: Geometry of the RGBA8888 surface backing a packed RGB u8/i8 image tensor.
PackedRgba16fLayout: Geometry of the RGBA16F-packed surface backing a planar F16 image tensor.
PboClientParts: The C-ABI parts ef_tensor_wrap_pbo takes, from a PboTensor at the origin of its buffer.
PboMapping: Raw mapped pointer from a PBO. CPU-accessible while the buffer is mapped. The pointer is only valid between map and unmap calls.
PboOpsVtableParts: The three parts of a [PboOpsVtable], read out of a descriptor’s ptr or supplied directly by a C caller.
PboTensor: A tensor backed by an OpenGL Pixel Buffer Object.
PlaneDescriptor: Per-plane DMA-BUF descriptor for external buffer import.
PlaneGeometry: Where one plane’s bytes physically live inside a tensor’s allocation.
PreprocessSpec: A model’s input preprocessing as plain values: what the image crate needs to build a convert, produced by the decoder from model metadata.
ProtoData: Raw prototype data for fused decode+render pipelines.
Quantization: Quantization parameters for an integer tensor.
Region: A rectangular sub-region of a tensor’s leading spatial frame, in pixels.
Segmentation: A segmentation result paired with the normalized bounding box that describes the spatial extent of segmentation.
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§

Compression: Requested tile-compression behavior for an image allocation (set via ImageDesc::with_compression).
CompressionScheme: Vendor tile-compression schemes the HAL recognizes and records.
Contiguity: Whether a tensor’s memory is known to be physically contiguous (Tensor::contiguity).
CpuAccess: Declared CPU involvement for a tensor, chosen at allocation.
DType: Element type discriminant for runtime type identification.
Error
Fit: How a source is fit into the requested destination shape.
FitMode: How a source is fit into the destination, without the letterbox pad colour. The code is the one the C EF_FIT_* enumerators and the Python Fit enum use.
IdentityKind: What kind of system key an identity was derived from. Participates in the id so that, say, inode 7 and IOSurfaceID 7 cannot collide.
Interpolation: Resampling filter. The code is the one the C EF_INTERPOLATION_* enumerators use; the string is the edgefirst.json and Python name.
LetterboxPlacement: Where a letterboxed image sits inside the destination. The code is the one the C EF_LETTERBOX_PLACEMENT_* enumerators and the Python LetterboxPlacement enum use; the string is the edgefirst.json name.
NormalizationPreset: A named Normalization. The code is the one the C EF_NORMALIZATION_* enumerators and the Python NormalizationPreset enum use; the names match the edgefirst.json presets.
PadSpace: The space a letterbox pad value is expressed in. The code is the one the C EF_PAD_SPACE_* enumerators use; the string is the edgefirst.json name.
PixelFormat: Pixel format identifier.
PixelLayout: Memory layout category.
ProtoLayout: Memory layout of the prototype tensor within ProtoData.
QuantMode: Semantic mode discriminant for hot-path kernel dispatch.
TensorDyn: Type-erased tensor. Wraps a Tensor<T> with runtime element type.
TensorMemory: Which memory backend a tensor is (or should be) allocated from.

Traits§

ContentRegionSource: Something that knows where it puts the image content in a destination, such as the image crate’s ConvertOptions or a PreprocessSpec. The decoder takes it to map its output back to the source image with the same geometry the convert used.
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: The operations every memory backend implements.

Functions§

broadcast_rgb: One value repeated for every RGB channel, or three values as given; None for any other count.
client_state_cuda_ops^⚠: Build CudaGlOps from a client’s frozen EfClientState and the three CUDA op functions. Retains the channel; Drop of the returned Arc releases it.
client_state_pbo_ops^⚠: Build a live PboOps from a client’s EfClientState and its two op functions — the one place the three parts are assembled, whether they arrived through a crate::TensorDesc under [crate::protocol::kind::PBO] or through ef_tensor_wrap_pbo’s arguments.
compression_fallback_count: Number of Compression::Any requests since process start that resolved to a linear layout instead of a vendor tile scheme. A steady-state pipeline holds this flat after warmup; growth means an allocation path keeps requesting compression it never gets.
compression_support: Whether this platform can allocate (format, dtype) images in a vendor tile-compressed layout. true requires an Android build, an eligible format (RGBA8888 u8/i8 initially), and a positively identified GPU vendor; everywhere else the answer is false and Compression::Any requests fall back to linear.
cuda_runtime_path: The runtime load() opened, if any – see CudaTable::runtime_path for what this points to on each platform. None iff no runtime loaded.
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.
image_dims_from_shape: The logical (width, height) an allocation shape describes for format – the inverse of PixelFormat::allocation_shape.
is_ahardwarebuffer_available: Always returns false on non-Android platforms.
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/iOS, AHardwareBuffer on Android, D3D11 textures on Windows). Returns false on 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.
letterbox_rect: The rectangle an src_w×src_h source occupies when letterboxed into a dst_w×dst_h destination: the larger axis fills, the other is scaled to keep the aspect ratio (rounded, at least one pixel), and placement positions it. A zero-sized source fills the destination.
memcpy_device_to_host^⚠: Copy count bytes from a CUDA device pointer to host. Returns false on failure or if libcudart is unavailable.
memcpy_host_to_device^⚠: Copy count bytes from host to a CUDA device pointer. Returns false on failure or if libcudart is unavailable.
packed_rgb888_layout: Geometry of the RGBA8888-packed surface backing a packed RGB u8/i8 image tensor.
packed_rgba16f_layout: Canonical geometry for the RGBA16F-packed surface backing a planar F16 image tensor.
read_pbo_vtable_parts^⚠: Read a crate::TensorDesc::ptr’s vtable into its parts, so a caller can hand them to a constructor rather than reassembling a dyn PboOps first.
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.
unletter_norm: Invert a letterbox: map a BoundingBox normalized over the model input back to normalized-over-the-crop, given the content bounds [lx0, ly0, lx1, ly1]. The box is canonicalised first, a degenerate (zero-span) letterbox axis maps with unit scale (no divide-by-zero), and the result is clamped to [0, 1].

Type Aliases§

CudaStream
EfPboMapFn: Map a PBO for CPU access. 0 on success; -1 when the GL context is gone; any other non-zero value a generic failure.
EfPboUnmapFn: Unmap a PBO previously mapped by an EfPboMapFn. Same return codes.
ForeignOwner: Opaque keep-alive handle for a foreign-memory tensor (see Tensor::from_foreign / TensorDyn::from_foreign_ptr).
Raw: The C-facing handle pointer type. Declared in both backends with the same name, so a -capi crate’s signatures do not change with the backend.
Result