rustcv_core/
frame.rs

1use crate::pixel_format::PixelFormat;
2use std::time::Duration;
3
4#[cfg(unix)]
5use std::os::unix::io::RawFd;
6
7/// 核心帧结构体
8/// 使用生命周期 'a 绑定到底层 Ring Buffer，实现零拷贝。
9#[derive(Debug)]
10pub struct Frame<'a> {
11    /// 原始图像数据切片
12    pub data: &'a [u8],
13
14    /// 图像宽度 (Pixels)
15    pub width: u32,
16
17    /// 图像高度 (Pixels)
18    pub height: u32,
19
20    /// 【关键】跨距/步长 (Bytes per line)
21    /// GPU 和 SIMD 往往要求 256/512 字节对齐，Stride 可能大于 width * bpp
22    pub stride: usize,
23
24    /// 像素格式 (含 Bayer, MJPEG 等)
25    pub format: PixelFormat,
26
27    /// 帧索引 (用于底层 Buffer 回收或丢帧统计)
28    pub sequence: u64,
29
30    /// 时间戳集合 (工业级同步核心)
31    pub timestamp: Timestamp,
32
33    /// 帧级元数据 (曝光、增益、GPIO状态)
34    pub metadata: FrameMetadata,
35
36    /// 内部句柄 (用于实现 Backend 特有的互操作，如 export_dmabuf)
37    pub backend_handle: &'a dyn BackendBufferHandle,
38}
39
40#[derive(Debug, Clone, Copy)]
41pub struct Timestamp {
42    /// 硬件原始时间戳 (纳秒，单调递增，来源各异)
43    pub hw_raw_ns: u64,
44
45    /// 【核心特性】经过 Software PLL 矫正后的系统时间
46    /// 对齐到 CLOCK_REALTIME 或 CLOCK_MONOTONIC，消除晶振温漂
47    pub system_synced: Duration,
48}
49
50#[derive(Debug, Clone, Default)]
51pub struct FrameMetadata {
52    pub actual_exposure_us: Option<u32>, // 实际曝光时间
53    pub actual_gain_db: Option<f32>,     // 实际增益
54    pub trigger_fired: bool,             // 是否由硬件触发产生
55    pub strobe_active: bool,             // 闪光灯是否点亮
56}
57
58/// GPU 互操作特质 (Linux)
59/// 允许用户直接获取 DMA-BUF fd 喂给 CUDA/Vulkan
60#[cfg(unix)]
61pub trait AsDmaBuf {
62    /// 获取底层的 DMA-BUF 文件描述符。
63    /// 注意：不要关闭它，所有权属于 Backend。
64    fn as_dmabuf_fd(&self) -> Option<RawFd>;
65}
66
67/// GPU 互操作特质 (Windows)
68#[cfg(windows)]
69pub trait AsDxResource {
70    fn as_resource_handle(&self) -> Option<*mut std::ffi::c_void>;
71}
72
73// 内部 Trait，用于 Frame 调用底层的方法
74pub trait BackendBufferHandle: std::fmt::Debug + Send + Sync {}
75
76impl BackendBufferHandle for () {}
rustcv_core/frame.rs

rustcv_core/
frame.rs
