edgefirst_hal/lib.rs
1// SPDX-FileCopyrightText: Copyright 2025 Au-Zone Technologies
2// SPDX-License-Identifier: Apache-2.0
3
4//! The EdgeFirst Hardware Abstraction Layer, as one dependency.
5//!
6//! This crate is a re-export shell. Every type you interact with is defined in
7//! a sub-crate, and depending on this umbrella costs nothing over depending on
8//! them individually — you get one version number and one feature surface
9//! instead of five.
10//!
11//! | Module | Crate | What it does |
12//! |---|---|---|
13//! | [`tensor`] | [`edgefirst_tensor`] | Zero-copy tensor memory: platform GPU buffer, SHM, PBO, heap |
14//! | [`codec`] | [`edgefirst_codec`] | Decodes JPEG/PNG **into** pre-allocated tensors |
15//! | [`image`] | [`edgefirst_image`] | Colour conversion, resize, rotation via OpenGL, G2D, or CPU |
16//! | [`decoder`] | [`edgefirst_decoder`] | Decodes model **output** tensors into detections |
17//! | `tracker` | `edgefirst-tracker` | ByteTrack multi-object tracking (feature `tracker`, off by default) |
18//! | [`trace`] | local | Process-wide span capture to Chrome JSON (feature `tracing`) |
19//!
20//! `codec` and `decoder` are unrelated despite the names: `codec` sits at the
21//! front of the pipeline turning image bytes into tensors, `decoder` at the
22//! back turning model outputs into detections.
23//!
24//! # Feature flags
25//!
26//! `ndarray`, `opengl`, and `tracing` are on by default. `tracker` is opt-in
27//! because it pulls in additional dependencies.
28//!
29//! # Tracing
30//!
31//! The sub-crates emit [`tracing`] spans on their hot paths that cost a single
32//! relaxed atomic load while no subscriber is installed. [`trace::start_tracing`]
33//! is what turns them into a trace file:
34//!
35//! ```no_run
36//! # #[cfg(feature = "tracing")]
37//! # {
38//! edgefirst_hal::trace::start_tracing("/tmp/trace.json").expect("start tracing");
39//! // ... run the pipeline ...
40//! edgefirst_hal::trace::stop_tracing();
41//! # }
42//! ```
43//!
44//! Load the result at <https://ui.perfetto.dev/>. Only one session is
45//! supported per process lifetime.
46
47pub use edgefirst_codec as codec;
48pub use edgefirst_decoder as decoder;
49pub use edgefirst_image as image;
50pub use edgefirst_tensor as tensor;
51#[cfg(feature = "tracker")]
52pub use edgefirst_tracker as tracker;
53
54#[cfg(feature = "tracing")]
55pub mod trace;