Skip to main content

camera/
format.rs

1//! Capture requests, negotiated formats, and frame memory contracts.
2use 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)]
7/// Positive rational frame rate that preserves values such as 30_000/1_001.
8pub 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    /// Creates and normalizes a positive rational frame rate.
31    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    /// Returns the normalized frames-per-second numerator.
50    pub const fn numerator(self) -> u32 {
51        self.numerator
52    }
53    /// Returns the normalized frames-per-second denominator.
54    pub const fn denominator(self) -> u32 {
55        self.denominator
56    }
57    /// Returns the approximate frames per second as a floating-point value.
58    pub fn as_f64(self) -> f64 {
59        self.numerator as f64 / self.denominator as f64
60    }
61    /// Returns the nominal duration between consecutive frames.
62    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)]
99/// Possible values for `OverflowPolicy`.
100pub enum OverflowPolicy {
101    /// The `DropOldest` variant.
102    DropOldest,
103    /// The `DropNewest` variant.
104    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)]
117/// Values for `MemoryBudget`.
118pub struct MemoryBudget {
119    /// The buffers value.
120    pub buffers: usize,
121    /// Maximum byte budget.
122    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    /// Performs the `validate` operation.
134    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)]
158/// Values for `ReconnectPolicy`.
159pub struct ReconnectPolicy {
160    /// Maximum recovery attempts, or no limit.
161    pub max_attempts: Option<u32>,
162    /// Delay between recovery attempts.
163    pub delay: Duration,
164    /// Maximum interval without a frame before recovery.
165    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)]
260/// Possible values for `PixelFormat`.
261pub enum PixelFormat {
262    /// The `Rgb8` variant.
263    Rgb8,
264    /// The `Bgr8` variant.
265    Bgr8,
266    /// The `Bgra8` variant.
267    Bgra8,
268    /// The `Rgba8` variant.
269    Rgba8,
270    /// The `Argb8` variant.
271    Argb8,
272    /// The `Yuyv` variant.
273    Yuyv,
274    /// The `Uyvy` variant.
275    Uyvy,
276    /// The `Nv12` variant.
277    Nv12,
278    /// The `Nv21` variant.
279    Nv21,
280    /// The `Yuv420p` variant.
281    Yuv420p,
282    /// The `Gray8` variant.
283    Gray8,
284    /// The `Mjpeg` variant.
285    Mjpeg,
286    /// The `H264` variant.
287    H264,
288}
289#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
290/// Possible values for `ColorMatrix`.
291pub enum ColorMatrix {
292    #[default]
293    /// The `Unknown` variant.
294    Unknown,
295    /// The `Bt601` variant.
296    Bt601,
297    /// The `Bt709` variant.
298    Bt709,
299    /// The `Bt2020` variant.
300    Bt2020,
301    /// The `Smpte240M` variant.
302    Smpte240M,
303}
304#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
305/// Possible values for `ColorRange`.
306pub enum ColorRange {
307    #[default]
308    /// The `Unknown` variant.
309    Unknown,
310    /// The `Full` variant.
311    Full,
312    /// The `Limited` variant.
313    Limited,
314}
315#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
316/// Values for `ColorInfo`.
317pub struct ColorInfo {
318    /// The matrix value.
319    pub matrix: ColorMatrix,
320    /// The range value.
321    pub range: ColorRange,
322    /// The primaries value.
323    pub primaries: ColorPrimaries,
324    /// The transfer value.
325    pub transfer: TransferFunction,
326}
327#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
328/// Possible values for `ColorPrimaries`.
329pub enum ColorPrimaries {
330    #[default]
331    /// The `Unknown` variant.
332    Unknown,
333    /// The `Bt709` variant.
334    Bt709,
335    /// The `Bt601_525` variant.
336    Bt601_525,
337    /// The `Bt601_625` variant.
338    Bt601_625,
339    /// The `Bt2020` variant.
340    Bt2020,
341    /// The `DisplayP3` variant.
342    DisplayP3,
343}
344#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
345/// Possible values for `TransferFunction`.
346pub enum TransferFunction {
347    #[default]
348    /// The `Unknown` variant.
349    Unknown,
350    /// The `Linear` variant.
351    Linear,
352    /// The `Srgb` variant.
353    Srgb,
354    /// The `Bt709` variant.
355    Bt709,
356    /// The `Pq` variant.
357    Pq,
358    /// The `Hlg` variant.
359    Hlg,
360}
361#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
362/// Possible values for `ClockDomain`.
363pub enum ClockDomain {
364    #[default]
365    /// The `Unknown` variant.
366    Unknown,
367    /// The `HostMonotonic` variant.
368    HostMonotonic,
369    /// The `MediaPresentation` variant.
370    MediaPresentation,
371    /// The `DeviceMonotonic` variant.
372    DeviceMonotonic,
373}
374#[derive(Clone, Copy, Debug, PartialEq, Eq)]
375/// Values for `SourceTimestamp`.
376pub struct SourceTimestamp {
377    /// The nanoseconds value.
378    pub nanoseconds: i64,
379    /// The clock value.
380    pub clock: ClockDomain,
381}
382#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
383/// Values for `Orientation`.
384pub struct Orientation {
385    /// The rotation degrees value.
386    pub rotation_degrees: u16,
387    /// The mirrored value.
388    pub mirrored: bool,
389}
390#[derive(Clone, Copy, Debug, PartialEq, Eq)]
391/// Values for `PlaneLayout`.
392pub struct PlaneLayout {
393    /// Byte offset from the beginning of the frame.
394    pub offset: usize,
395    /// Length in bytes.
396    pub length: usize,
397    /// Distance in bytes between adjacent rows.
398    pub row_stride: usize,
399    /// Distance in bytes between adjacent pixels.
400    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/// Recognize the adjacent, overlapping U/V views commonly returned for
422/// YUV_420_888. The lower view must contain every byte described by the upper
423/// view and the complete visible chroma area; otherwise callers must retain the
424/// original three-plane representation.
425#[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)]
467/// Values for `FrameLayout`.
468pub struct FrameLayout {
469    /// Frame width in pixels.
470    pub width: u32,
471    /// Frame height in pixels.
472    pub height: u32,
473    /// Pixel or capture format.
474    pub format: PixelFormat,
475    /// Plane layouts in storage order.
476    pub planes: Vec<PlaneLayout>,
477    /// Color-space metadata.
478    pub color: ColorInfo,
479    /// Display orientation metadata.
480    pub orientation: Orientation,
481    /// Whether row zero is the bottom image row (e.g. a Windows RGB DIB).
482    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    /// Build a single packed/encoded plane. Padding remains part of the payload.
506    #[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    /// Performs the `validate` operation.
536    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}