1use crate::{CameraError, CameraResult, VideoFormat};
3use std::time::Duration;
4
5#[cfg_attr(feature = "serde", derive(serde::Serialize))]
6#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
7pub struct FrameRate {
9 numerator: u32,
10 denominator: u32,
11}
12
13#[cfg(feature = "serde")]
14impl<'de> serde::Deserialize<'de> for FrameRate {
15 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
16 where
17 D: serde::Deserializer<'de>,
18 {
19 #[derive(serde::Deserialize)]
20 struct RawFrameRate {
21 numerator: u32,
22 denominator: u32,
23 }
24
25 let raw = RawFrameRate::deserialize(deserializer)?;
26 Self::new(raw.numerator, raw.denominator).map_err(serde::de::Error::custom)
27 }
28}
29impl FrameRate {
30 pub fn new(numerator: u32, denominator: u32) -> CameraResult<Self> {
32 if numerator == 0 || denominator == 0 {
33 return Err(CameraError::invalid_config(
34 "Frame rate must be positive".into(),
35 ));
36 }
37 let mut a = numerator;
38 let mut b = denominator;
39 while b != 0 {
40 let r = a % b;
41 a = b;
42 b = r;
43 }
44 Ok(Self {
45 numerator: numerator / a,
46 denominator: denominator / a,
47 })
48 }
49 pub const fn numerator(self) -> u32 {
51 self.numerator
52 }
53 pub const fn denominator(self) -> u32 {
55 self.denominator
56 }
57 pub fn as_f64(self) -> f64 {
59 self.numerator as f64 / self.denominator as f64
60 }
61 pub fn interval(self) -> Duration {
63 Duration::from_secs_f64(1.0 / self.as_f64()).max(Duration::from_nanos(1))
64 }
65}
66impl PartialOrd for FrameRate {
67 fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
68 Some(self.cmp(other))
69 }
70}
71impl Ord for FrameRate {
72 fn cmp(&self, other: &Self) -> std::cmp::Ordering {
73 (u64::from(self.numerator) * u64::from(other.denominator))
74 .cmp(&(u64::from(other.numerator) * u64::from(self.denominator)))
75 }
76}
77impl Default for FrameRate {
78 fn default() -> Self {
79 Self {
80 numerator: 30,
81 denominator: 1,
82 }
83 }
84}
85
86#[derive(Clone, Copy, Debug, PartialEq, Eq)]
87pub enum OutputFormat {
88 Rgb8,
89 Native,
90}
91#[derive(Clone, Copy, Debug, PartialEq, Eq)]
92pub enum SelectionPolicy {
93 #[allow(dead_code)]
94 Exact,
95 Closest,
96}
97#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
98#[derive(Clone, Copy, Debug, PartialEq, Eq)]
99pub enum OverflowPolicy {
101 DropOldest,
103 DropNewest,
105}
106#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
107#[derive(Clone, Copy, Debug, PartialEq, Eq)]
108pub enum DeliveryPolicy {
109 Latest,
110 Buffered {
111 capacity: usize,
112 overflow: OverflowPolicy,
113 },
114}
115#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
116#[derive(Clone, Copy, Debug, PartialEq, Eq)]
117pub struct MemoryBudget {
119 pub buffers: usize,
121 pub bytes: usize,
123}
124impl Default for MemoryBudget {
125 fn default() -> Self {
126 Self {
127 buffers: 6,
128 bytes: 192 * 1024 * 1024,
129 }
130 }
131}
132impl MemoryBudget {
133 pub fn validate(self) -> CameraResult<()> {
135 if !(2..=256).contains(&self.buffers) || self.bytes == 0 {
136 return Err(CameraError::invalid_config(
137 "Memory budget requires 2..=256 buffers and nonzero bytes".into(),
138 ));
139 }
140 Ok(())
141 }
142}
143#[derive(Clone, Debug)]
144pub struct StreamRequest {
145 pub(crate) width: u32,
146 pub(crate) height: u32,
147 pub(crate) fps: FrameRate,
148 pub(crate) format: Option<VideoFormat>,
149 pub(crate) output: OutputFormat,
150 pub(crate) selection: SelectionPolicy,
151 pub(crate) memory: MemoryBudget,
152 pub(crate) startup_timeout: Duration,
153 pub(crate) driver_buffers: Option<usize>,
154 pub(crate) reconnect: Option<ReconnectPolicy>,
155}
156#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
157#[derive(Clone, Debug)]
158pub struct ReconnectPolicy {
160 pub max_attempts: Option<u32>,
162 pub delay: Duration,
164 pub stall_timeout: Duration,
166}
167impl Default for ReconnectPolicy {
168 fn default() -> Self {
169 Self {
170 max_attempts: Some(10),
171 delay: Duration::from_secs(1),
172 stall_timeout: Duration::from_secs(5),
173 }
174 }
175}
176#[derive(Clone, Debug)]
177pub struct StreamRequestBuilder(StreamRequest);
178impl StreamRequest {
179 pub fn builder() -> StreamRequestBuilder {
180 StreamRequestBuilder(Self {
181 width: 640,
182 height: 480,
183 fps: FrameRate::default(),
184 format: None,
185 output: OutputFormat::Native,
186 selection: SelectionPolicy::Closest,
187 memory: MemoryBudget::default(),
188 startup_timeout: Duration::from_secs(3),
189 driver_buffers: None,
190 reconnect: None,
191 })
192 }
193}
194impl StreamRequestBuilder {
195 pub fn resolution(mut self, w: u32, h: u32) -> Self {
196 self.0.width = w;
197 self.0.height = h;
198 self
199 }
200 pub fn frame_rate(mut self, fps: FrameRate) -> Self {
201 self.0.fps = fps;
202 self
203 }
204 pub fn capture_format(mut self, format: VideoFormat) -> Self {
205 self.0.format = Some(format);
206 self
207 }
208 pub fn output(mut self, v: OutputFormat) -> Self {
209 self.0.output = v;
210 self
211 }
212 pub fn selection(mut self, v: SelectionPolicy) -> Self {
213 self.0.selection = v;
214 self
215 }
216 pub fn memory_budget(mut self, v: MemoryBudget) -> Self {
217 self.0.memory = v;
218 self
219 }
220 pub fn startup_timeout(mut self, v: Duration) -> Self {
221 self.0.startup_timeout = v;
222 self
223 }
224 pub fn reconnect(mut self, v: ReconnectPolicy) -> Self {
225 self.0.reconnect = Some(v);
226 self
227 }
228 pub fn build(self) -> CameraResult<StreamRequest> {
229 let r = self.0;
230 r.memory.validate()?;
231 let rgb = (r.width as usize)
232 .checked_mul(r.height as usize)
233 .and_then(|n| n.checked_mul(3));
234 if r.width == 0 || r.height == 0 || rgb.is_none() || r.startup_timeout.is_zero() {
235 return Err(CameraError::invalid_config(
236 "Invalid resolution/startup deadline".into(),
237 ));
238 }
239 if r.output == OutputFormat::Rgb8 && rgb.unwrap() > r.memory.bytes / r.memory.buffers {
240 return Err(CameraError::invalid_config(
241 "RGB buffers exceed memory budget".into(),
242 ));
243 }
244 if r.driver_buffers.is_some_and(|n| !(2..=32).contains(&n)) {
245 return Err(CameraError::invalid_config(
246 "Driver buffer count must be 2..=32".into(),
247 ));
248 }
249 if r.reconnect.as_ref().is_some_and(|p| {
250 p.delay.is_zero() || p.stall_timeout.is_zero() || p.max_attempts == Some(0)
251 }) {
252 return Err(CameraError::invalid_config(
253 "Invalid reconnect policy".into(),
254 ));
255 }
256 Ok(r)
257 }
258}
259#[derive(Clone, Copy, Debug, PartialEq, Eq)]
260pub enum PixelFormat {
262 Rgb8,
264 Bgr8,
266 Bgra8,
268 Rgba8,
270 Argb8,
272 Yuyv,
274 Uyvy,
276 Nv12,
278 Nv21,
280 Yuv420p,
282 Gray8,
284 Mjpeg,
286 H264,
288}
289#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
290pub enum ColorMatrix {
292 #[default]
293 Unknown,
295 Bt601,
297 Bt709,
299 Bt2020,
301 Smpte240M,
303}
304#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
305pub enum ColorRange {
307 #[default]
308 Unknown,
310 Full,
312 Limited,
314}
315#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
316pub struct ColorInfo {
318 pub matrix: ColorMatrix,
320 pub range: ColorRange,
322 pub primaries: ColorPrimaries,
324 pub transfer: TransferFunction,
326}
327#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
328pub enum ColorPrimaries {
330 #[default]
331 Unknown,
333 Bt709,
335 Bt601_525,
337 Bt601_625,
339 Bt2020,
341 DisplayP3,
343}
344#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
345pub enum TransferFunction {
347 #[default]
348 Unknown,
350 Linear,
352 Srgb,
354 Bt709,
356 Pq,
358 Hlg,
360}
361#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
362pub enum ClockDomain {
364 #[default]
365 Unknown,
367 HostMonotonic,
369 MediaPresentation,
371 DeviceMonotonic,
373}
374#[derive(Clone, Copy, Debug, PartialEq, Eq)]
375pub struct SourceTimestamp {
377 pub nanoseconds: i64,
379 pub clock: ClockDomain,
381}
382#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
383pub struct Orientation {
385 pub rotation_degrees: u16,
387 pub mirrored: bool,
389}
390#[derive(Clone, Copy, Debug, PartialEq, Eq)]
391pub struct PlaneLayout {
393 pub offset: usize,
395 pub length: usize,
397 pub row_stride: usize,
399 pub pixel_stride: usize,
401}
402
403#[derive(Clone, Copy, Debug, PartialEq, Eq)]
404#[cfg(any(target_os = "android", test))]
405pub(crate) struct ChromaPlaneSpan {
406 pub start: usize,
407 pub length: usize,
408 pub row_stride: usize,
409 pub pixel_stride: usize,
410}
411
412#[derive(Clone, Copy, Debug, PartialEq, Eq)]
413#[cfg(any(target_os = "android", test))]
414pub(crate) struct InterleavedChromaLayout {
415 pub start: usize,
416 pub length: usize,
417 pub row_stride: usize,
418 pub format: PixelFormat,
419}
420
421#[cfg(any(target_os = "android", test))]
426pub(crate) fn interleaved_chroma_layout(
427 width: usize,
428 height: usize,
429 u: ChromaPlaneSpan,
430 v: ChromaPlaneSpan,
431) -> Option<InterleavedChromaLayout> {
432 if width == 0
433 || height == 0
434 || u.pixel_stride != 2
435 || v.pixel_stride != 2
436 || u.row_stride != v.row_stride
437 {
438 return None;
439 }
440 let (base, other, format) = if u.start.checked_add(1) == Some(v.start) {
441 (u, v, PixelFormat::Nv12)
442 } else if v.start.checked_add(1) == Some(u.start) {
443 (v, u, PixelFormat::Nv21)
444 } else {
445 return None;
446 };
447 let base_end = base.start.checked_add(base.length)?;
448 let other_end = other.start.checked_add(other.length)?;
449 let row_bytes = width.div_ceil(2).checked_mul(2)?;
450 let required = height
451 .div_ceil(2)
452 .checked_sub(1)?
453 .checked_mul(base.row_stride)?
454 .checked_add(row_bytes)?;
455 if other_end > base_end || base.row_stride < row_bytes || base.length < required {
456 return None;
457 }
458 Some(InterleavedChromaLayout {
459 start: base.start,
460 length: base.length,
461 row_stride: base.row_stride,
462 format,
463 })
464}
465
466#[derive(Clone, Debug, PartialEq, Eq)]
467pub struct FrameLayout {
469 pub width: u32,
471 pub height: u32,
473 pub format: PixelFormat,
475 pub planes: Vec<PlaneLayout>,
477 pub color: ColorInfo,
479 pub orientation: Orientation,
481 pub bottom_up: bool,
483}
484impl FrameLayout {
485 #[allow(dead_code)]
486 pub(crate) fn rgb(w: u32, h: u32) -> Self {
487 Self {
488 width: w,
489 height: h,
490 format: PixelFormat::Rgb8,
491 planes: vec![PlaneLayout {
492 offset: 0,
493 length: (w as usize)
494 .checked_mul(h as usize)
495 .and_then(|n| n.checked_mul(3))
496 .unwrap_or(0),
497 row_stride: (w as usize).checked_mul(3).unwrap_or(0),
498 pixel_stride: 3,
499 }],
500 color: ColorInfo::default(),
501 orientation: Orientation::default(),
502 bottom_up: false,
503 }
504 }
505 #[allow(dead_code)]
507 pub(crate) fn packed(
508 w: u32,
509 h: u32,
510 format: PixelFormat,
511 stride: usize,
512 length: usize,
513 ) -> Self {
514 let pixel_stride = match format {
515 PixelFormat::Rgb8 | PixelFormat::Bgr8 => 3,
516 PixelFormat::Bgra8 | PixelFormat::Rgba8 | PixelFormat::Argb8 => 4,
517 PixelFormat::Yuyv | PixelFormat::Uyvy => 2,
518 _ => 1,
519 };
520 Self {
521 width: w,
522 height: h,
523 format,
524 planes: vec![PlaneLayout {
525 offset: 0,
526 length,
527 row_stride: stride,
528 pixel_stride,
529 }],
530 color: ColorInfo::default(),
531 orientation: Orientation::default(),
532 bottom_up: false,
533 }
534 }
535 pub fn validate(&self, length: usize) -> CameraResult<()> {
537 let invalid =
538 || CameraError::invalid_frame("Invalid frame dimensions, planes, or strides".into());
539 if self.width == 0
540 || self.height == 0
541 || ![0, 90, 180, 270].contains(&self.orientation.rotation_degrees)
542 {
543 return Err(invalid());
544 }
545 let (w, h) = (self.width as usize, self.height as usize);
546 let mut specs = [(0, 0, 0); 3];
547 let spec_count = match self.format {
548 PixelFormat::Mjpeg | PixelFormat::H264 => {
549 specs[0] = (1, 1, 1);
550 1
551 }
552 PixelFormat::Nv12 | PixelFormat::Nv21 => {
553 specs[0] = (w, h, 1);
554 specs[1] = (w.div_ceil(2), h.div_ceil(2), 2);
555 2
556 }
557 PixelFormat::Yuv420p => {
558 specs[0] = (w, h, 1);
559 specs[1] = (w.div_ceil(2), h.div_ceil(2), 1);
560 specs[2] = (w.div_ceil(2), h.div_ceil(2), 1);
561 3
562 }
563 PixelFormat::Rgb8 | PixelFormat::Bgr8 => {
564 specs[0] = (w, h, 3);
565 1
566 }
567 PixelFormat::Bgra8 | PixelFormat::Rgba8 | PixelFormat::Argb8 => {
568 specs[0] = (w, h, 4);
569 1
570 }
571 PixelFormat::Yuyv | PixelFormat::Uyvy => {
572 if w % 2 != 0 {
573 return Err(invalid());
574 }
575 specs[0] = (w, h, 2);
576 1
577 }
578 PixelFormat::Gray8 => {
579 specs[0] = (w, h, 1);
580 1
581 }
582 };
583 if self.planes.len() != spec_count {
584 return Err(invalid());
585 }
586 for (p, (cols, rows, channels)) in
587 self.planes.iter().zip(specs[..spec_count].iter().copied())
588 {
589 if p.length == 0 || p.offset.checked_add(p.length).is_none_or(|n| n > length) {
590 return Err(invalid());
591 }
592 if matches!(self.format, PixelFormat::Mjpeg | PixelFormat::H264) {
593 continue;
594 }
595 let row = (cols - 1)
596 .checked_mul(p.pixel_stride)
597 .and_then(|n| n.checked_add(channels))
598 .ok_or_else(invalid)?;
599 let required = (rows - 1)
600 .checked_mul(p.row_stride)
601 .and_then(|n| n.checked_add(row))
602 .ok_or_else(invalid)?;
603 if (matches!(self.format, PixelFormat::Yuyv | PixelFormat::Uyvy) && p.pixel_stride != 2)
604 || p.pixel_stride < channels
605 || p.row_stride < row
606 || p.length < required
607 {
608 return Err(invalid());
609 }
610 }
611 Ok(())
612 }
613}
614
615#[cfg(test)]
616mod interleaved_chroma_tests {
617 use super::*;
618
619 fn plane(start: usize, length: usize) -> ChromaPlaneSpan {
620 ChromaPlaneSpan {
621 start,
622 length,
623 row_stride: 4,
624 pixel_stride: 2,
625 }
626 }
627
628 #[test]
629 fn detects_overlapping_nv12_and_nv21_without_assuming_missing_tail_bytes() {
630 let nv12 = interleaved_chroma_layout(4, 4, plane(100, 8), plane(101, 7)).unwrap();
631 assert_eq!(nv12.start, 100);
632 assert_eq!(nv12.length, 8);
633 assert_eq!(nv12.row_stride, 4);
634 assert_eq!(nv12.format, PixelFormat::Nv12);
635
636 let nv21 = interleaved_chroma_layout(4, 4, plane(101, 7), plane(100, 8)).unwrap();
637 assert_eq!(nv21.start, 100);
638 assert_eq!(nv21.length, 8);
639 assert_eq!(nv21.format, PixelFormat::Nv21);
640
641 assert!(interleaved_chroma_layout(4, 4, plane(100, 8), plane(101, 8)).is_none());
642 assert!(interleaved_chroma_layout(4, 6, plane(100, 8), plane(101, 7)).is_none());
643 }
644
645 #[test]
646 fn rejects_disjoint_or_incompatible_chroma_planes() {
647 assert!(interleaved_chroma_layout(4, 4, plane(100, 8), plane(200, 8)).is_none());
648
649 let mut wrong_stride = plane(101, 7);
650 wrong_stride.row_stride = 6;
651 assert!(interleaved_chroma_layout(4, 4, plane(100, 8), wrong_stride).is_none());
652
653 let mut planar = plane(101, 7);
654 planar.pixel_stride = 1;
655 assert!(interleaved_chroma_layout(4, 4, plane(100, 8), planar).is_none());
656 }
657}