Skip to main content

framefinery_api/
frame.rs

1use std::fmt;
2use std::str::FromStr;
3
4use crate::error::{MediaError, Result};
5
6/// Checked planar sample bit depth for raw frame formats.
7#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
8pub struct SampleBitDepth(u8);
9
10/// Chroma subsampling layout for planar YUV or monochrome data.
11#[derive(Debug, Clone, Copy, PartialEq, Eq)]
12pub enum ChromaSampling {
13    /// One luma or gray plane with no chroma planes.
14    Monochrome,
15    /// 4:2:0 chroma, subsampled by two in width and height.
16    Cs420,
17    /// 4:2:2 chroma, subsampled by two in width only.
18    Cs422,
19    /// 4:4:4 chroma, no chroma subsampling.
20    Cs444,
21}
22
23/// Raw pixel layout accepted by FrameFinery frame buffers.
24#[derive(Debug, Clone, Copy, PartialEq, Eq)]
25pub enum PixelFormat {
26    /// Planar YUV with explicit chroma sampling and sample bit depth.
27    PlanarYuv {
28        /// Chroma sampling layout.
29        chroma_sampling: ChromaSampling,
30        /// Bits per sample.
31        bit_depth: SampleBitDepth,
32    },
33    /// Monochrome gray plane with explicit sample bit depth.
34    Gray {
35        /// Bits per sample.
36        bit_depth: SampleBitDepth,
37    },
38    /// Planar GBR, 8 bits per sample, ordered G plane, B plane, R plane.
39    Gbrp8,
40    /// Packed RGB, 8 bits per channel, ordered R, G, B per pixel.
41    Rgb24,
42}
43
44impl ChromaSampling {
45    /// Horizontal subsampling factor.
46    pub const fn subsample_x(self) -> usize {
47        match self {
48            Self::Monochrome | Self::Cs444 => 1,
49            Self::Cs420 | Self::Cs422 => 2,
50        }
51    }
52
53    /// Vertical subsampling factor.
54    pub const fn subsample_y(self) -> usize {
55        match self {
56            Self::Monochrome | Self::Cs422 | Self::Cs444 => 1,
57            Self::Cs420 => 2,
58        }
59    }
60
61    /// Number of samples in one chroma plane for this layout.
62    pub fn chroma_plane_samples(self, width: usize, height: usize) -> Option<usize> {
63        let luma = width.checked_mul(height)?;
64        match self {
65            Self::Monochrome => Some(0),
66            Self::Cs420 => luma.checked_div(4),
67            Self::Cs422 => luma.checked_div(2),
68            Self::Cs444 => Some(luma),
69        }
70    }
71}
72
73impl SampleBitDepth {
74    /// Number of bits used for each stored sample.
75    pub const fn bits(self) -> u8 {
76        self.0
77    }
78
79    /// Create a bit depth in the supported 8 through 16 bit range.
80    pub const fn new(bits: u8) -> Option<Self> {
81        if bits >= 8 && bits <= 16 {
82            Some(Self(bits))
83        } else {
84            None
85        }
86    }
87
88    /// Alias for [`SampleBitDepth::new`].
89    pub const fn from_bits(bits: u8) -> Option<Self> {
90        Self::new(bits)
91    }
92
93    const fn new_unchecked(bits: u8) -> Self {
94        Self(bits)
95    }
96
97    /// Number of bytes used to store one sample.
98    pub fn bytes_per_sample(self) -> usize {
99        if self.bits() <= 8 {
100            1
101        } else {
102            2
103        }
104    }
105
106    /// Maximum legal sample value for this bit depth.
107    pub fn max_sample(self) -> u16 {
108        (1u32.checked_shl(self.bits() as u32).unwrap() - 1) as u16
109    }
110}
111
112impl PixelFormat {
113    // TODO(deprecated): prefer numeric constructors such as
114    // `PixelFormat::yuv420(8)` over named 8-bit compatibility constants.
115    #[allow(non_upper_case_globals)]
116    /// Compatibility constant for 8-bit 4:2:0 planar YUV.
117    pub const Yuv420p8: Self =
118        Self::planar_yuv(ChromaSampling::Cs420, SampleBitDepth::new_unchecked(8));
119    #[allow(non_upper_case_globals)]
120    /// Compatibility constant for 8-bit 4:2:2 planar YUV.
121    pub const Yuv422p8: Self =
122        Self::planar_yuv(ChromaSampling::Cs422, SampleBitDepth::new_unchecked(8));
123    #[allow(non_upper_case_globals)]
124    /// Compatibility constant for 8-bit 4:4:4 planar YUV.
125    pub const Yuv444p8: Self =
126        Self::planar_yuv(ChromaSampling::Cs444, SampleBitDepth::new_unchecked(8));
127    #[allow(non_upper_case_globals)]
128    /// Compatibility constant for 8-bit monochrome gray.
129    pub const Gray8: Self = Self::gray_with_depth(SampleBitDepth::new_unchecked(8));
130
131    /// Create a planar YUV format from chroma sampling and checked bit depth.
132    pub const fn planar_yuv(chroma_sampling: ChromaSampling, bit_depth: SampleBitDepth) -> Self {
133        Self::PlanarYuv {
134            chroma_sampling,
135            bit_depth,
136        }
137    }
138
139    /// Create a planar YUV format from chroma sampling and numeric bit depth.
140    pub const fn yuv(chroma_sampling: ChromaSampling, bit_depth: u8) -> Option<Self> {
141        match SampleBitDepth::new(bit_depth) {
142            Some(bit_depth) => Some(Self::planar_yuv(chroma_sampling, bit_depth)),
143            None => None,
144        }
145    }
146
147    /// Create a 4:2:0 planar YUV format with the requested bit depth.
148    pub const fn yuv420(bit_depth: u8) -> Option<Self> {
149        Self::yuv(ChromaSampling::Cs420, bit_depth)
150    }
151
152    /// Create a 4:2:2 planar YUV format with the requested bit depth.
153    pub const fn yuv422(bit_depth: u8) -> Option<Self> {
154        Self::yuv(ChromaSampling::Cs422, bit_depth)
155    }
156
157    /// Create a 4:4:4 planar YUV format with the requested bit depth.
158    pub const fn yuv444(bit_depth: u8) -> Option<Self> {
159        Self::yuv(ChromaSampling::Cs444, bit_depth)
160    }
161
162    /// Create a monochrome gray format with the requested bit depth.
163    pub const fn gray(bit_depth: u8) -> Option<Self> {
164        match SampleBitDepth::new(bit_depth) {
165            Some(bit_depth) => Some(Self::Gray { bit_depth }),
166            None => None,
167        }
168    }
169
170    const fn gray_with_depth(bit_depth: SampleBitDepth) -> Self {
171        Self::Gray { bit_depth }
172    }
173
174    /// Canonical CLI/raw-format name for this pixel format.
175    pub fn name(self) -> String {
176        match self {
177            Self::PlanarYuv {
178                chroma_sampling,
179                bit_depth,
180            } => {
181                let sampling = match chroma_sampling {
182                    ChromaSampling::Cs420 => "420",
183                    ChromaSampling::Cs422 => "422",
184                    ChromaSampling::Cs444 => "444",
185                    ChromaSampling::Monochrome => unreachable!("YUV cannot be monochrome"),
186                };
187                if bit_depth.bits() == 8 {
188                    format!("yuv{sampling}p8")
189                } else {
190                    format!("yuv{}p{}le", sampling, bit_depth.bits())
191                }
192            }
193            Self::Gray { bit_depth } => {
194                if bit_depth.bits() == 8 {
195                    "gray8".to_string()
196                } else {
197                    format!("gray{}le", bit_depth.bits())
198                }
199            }
200            Self::Gbrp8 => "gbrp8".to_string(),
201            Self::Rgb24 => "rgb24".to_string(),
202        }
203    }
204
205    /// Sample bit depth used by this format.
206    pub fn bit_depth(self) -> SampleBitDepth {
207        match self {
208            Self::PlanarYuv { bit_depth, .. } | Self::Gray { bit_depth } => bit_depth,
209            Self::Gbrp8 | Self::Rgb24 => SampleBitDepth::new_unchecked(8),
210        }
211    }
212
213    /// Number of bytes used to store one sample in this format.
214    pub fn bytes_per_sample(self) -> usize {
215        self.bit_depth().bytes_per_sample()
216    }
217
218    /// Return whether this is planar YUV 4:2:0.
219    pub fn is_yuv420(self) -> bool {
220        self.chroma_sampling() == Some(ChromaSampling::Cs420)
221    }
222
223    /// Return whether this is a planar YUV format.
224    pub fn is_yuv(self) -> bool {
225        self.chroma_sampling()
226            .is_some_and(|sampling| sampling != ChromaSampling::Monochrome)
227    }
228
229    /// Return whether this is planar RGB-family data.
230    pub fn is_planar_rgb(self) -> bool {
231        self == Self::Gbrp8
232    }
233
234    /// Return whether this is an RGB-family format.
235    pub fn is_rgb(self) -> bool {
236        matches!(self, Self::Gbrp8 | Self::Rgb24)
237    }
238
239    /// Chroma sampling for planar formats, or `None` for RGB-family formats.
240    pub fn chroma_sampling(self) -> Option<ChromaSampling> {
241        match self {
242            Self::PlanarYuv {
243                chroma_sampling, ..
244            } => Some(chroma_sampling),
245            Self::Gray { .. } => Some(ChromaSampling::Monochrome),
246            Self::Gbrp8 | Self::Rgb24 => None,
247        }
248    }
249
250    /// Number of samples in one chroma plane for the given frame geometry.
251    pub fn chroma_plane_samples(self, width: usize, height: usize) -> Option<usize> {
252        self.chroma_sampling()?.chroma_plane_samples(width, height)
253    }
254
255    /// Return the same planar layout with a different bit depth.
256    pub fn with_bit_depth(self, bit_depth: SampleBitDepth) -> Option<Self> {
257        match self.chroma_sampling()? {
258            ChromaSampling::Cs420 | ChromaSampling::Cs422 | ChromaSampling::Cs444 => {
259                Some(Self::planar_yuv(self.chroma_sampling()?, bit_depth))
260            }
261            ChromaSampling::Monochrome => Some(Self::gray_with_depth(bit_depth)),
262        }
263    }
264
265    /// Total byte length of one frame with this format and geometry.
266    pub fn frame_len(self, width: usize, height: usize) -> Option<usize> {
267        let luma = width.checked_mul(height)?;
268        let bytes_per_sample = self.bytes_per_sample();
269        match self.chroma_sampling() {
270            Some(ChromaSampling::Cs420 | ChromaSampling::Cs422 | ChromaSampling::Cs444) => {
271                let chroma_plane = self.chroma_plane_samples(width, height)?;
272                luma.checked_add(chroma_plane.checked_mul(2)?)?
273                    .checked_mul(bytes_per_sample)
274            }
275            Some(ChromaSampling::Monochrome) => luma.checked_mul(bytes_per_sample),
276            None => luma.checked_mul(3),
277        }
278    }
279
280    /// Validate that geometry is legal for this format and has an addressable length.
281    pub fn validate_geometry(self, width: usize, height: usize) -> Result<()> {
282        if width == 0 || height == 0 {
283            return Err(MediaError::InvalidDimensions { width, height });
284        }
285
286        if self.is_yuv420() && (!width.is_multiple_of(2) || !height.is_multiple_of(2)) {
287            return Err(MediaError::IncompatibleFormat {
288                format: self.name(),
289                reason: "width and height must be even".to_string(),
290            });
291        }
292
293        if matches!(self.chroma_sampling(), Some(ChromaSampling::Cs422)) && !width.is_multiple_of(2)
294        {
295            return Err(MediaError::IncompatibleFormat {
296                format: self.name(),
297                reason: "width must be even".to_string(),
298            });
299        }
300
301        self.frame_len(width, height)
302            .ok_or(MediaError::LengthOverflow)?;
303        Ok(())
304    }
305}
306
307/// Convert a planar YUV or gray frame between supported bit depths.
308///
309/// The chroma layout must remain the same; this helper does not convert RGB,
310/// YUV, or chroma subsampling.
311pub fn convert_planar_frame_bit_depth(
312    input: &[u8],
313    width: usize,
314    height: usize,
315    source_format: PixelFormat,
316    target_format: PixelFormat,
317) -> Result<Vec<u8>> {
318    if source_format.chroma_sampling().is_none() || target_format.chroma_sampling().is_none() {
319        return Err(MediaError::Message(
320            "bit-depth conversion supports only planar YUV and gray formats".to_string(),
321        ));
322    }
323    if source_format.chroma_sampling() != target_format.chroma_sampling() {
324        return Err(MediaError::Message(format!(
325            "bit-depth conversion cannot change chroma layout: {source_format} -> {target_format}"
326        )));
327    }
328
329    source_format.validate_geometry(width, height)?;
330    target_format.validate_geometry(width, height)?;
331    let expected = source_format
332        .frame_len(width, height)
333        .ok_or(MediaError::LengthOverflow)?;
334    if input.len() != expected {
335        return Err(MediaError::BufferLength {
336            expected,
337            actual: input.len(),
338        });
339    }
340
341    let target_bytes = target_format.bytes_per_sample();
342    let sample_count = expected / source_format.bytes_per_sample();
343    let mut output = vec![0; sample_count * target_bytes];
344    for sample_idx in 0..sample_count {
345        let source_sample = read_planar_sample(input, sample_idx, source_format.bit_depth())
346            .expect("validated source frame length must contain every source sample");
347        let target_sample = scale_sample_bit_depth(
348            source_sample,
349            source_format.bit_depth(),
350            target_format.bit_depth(),
351        );
352        write_planar_sample(
353            &mut output,
354            sample_idx,
355            target_sample,
356            target_format.bit_depth(),
357        )
358        .expect("allocated target frame length must contain every target sample");
359    }
360    Ok(output)
361}
362
363/// Convert between closely related raw frame formats.
364///
365/// Currently supports same-format copies, planar bit-depth conversion, and
366/// reversible `rgb24` to/from `gbrp8` repacking.
367pub fn convert_frame_format(
368    input: &[u8],
369    width: usize,
370    height: usize,
371    source_format: PixelFormat,
372    target_format: PixelFormat,
373) -> Result<Vec<u8>> {
374    source_format.validate_geometry(width, height)?;
375    target_format.validate_geometry(width, height)?;
376    let expected = source_format
377        .frame_len(width, height)
378        .ok_or(MediaError::LengthOverflow)?;
379    if input.len() != expected {
380        return Err(MediaError::BufferLength {
381            expected,
382            actual: input.len(),
383        });
384    }
385    if source_format == target_format {
386        return Ok(input.to_vec());
387    }
388    match (source_format, target_format) {
389        (PixelFormat::Rgb24, PixelFormat::Gbrp8) => rgb24_to_gbrp8(input, width, height),
390        (PixelFormat::Gbrp8, PixelFormat::Rgb24) => gbrp8_to_rgb24(input, width, height),
391        _ => convert_planar_frame_bit_depth(input, width, height, source_format, target_format),
392    }
393}
394
395fn rgb24_to_gbrp8(input: &[u8], width: usize, height: usize) -> Result<Vec<u8>> {
396    let pixels = width
397        .checked_mul(height)
398        .ok_or(MediaError::LengthOverflow)?;
399    let expected = pixels.checked_mul(3).ok_or(MediaError::LengthOverflow)?;
400    if input.len() != expected {
401        return Err(MediaError::BufferLength {
402            expected,
403            actual: input.len(),
404        });
405    }
406    let mut output = vec![0; expected];
407    let (g_plane, br_planes) = output.split_at_mut(pixels);
408    let (b_plane, r_plane) = br_planes.split_at_mut(pixels);
409    for (idx, pixel) in input.chunks_exact(3).enumerate() {
410        r_plane[idx] = pixel[0];
411        g_plane[idx] = pixel[1];
412        b_plane[idx] = pixel[2];
413    }
414    Ok(output)
415}
416
417fn gbrp8_to_rgb24(input: &[u8], width: usize, height: usize) -> Result<Vec<u8>> {
418    let pixels = width
419        .checked_mul(height)
420        .ok_or(MediaError::LengthOverflow)?;
421    let expected = pixels.checked_mul(3).ok_or(MediaError::LengthOverflow)?;
422    if input.len() != expected {
423        return Err(MediaError::BufferLength {
424            expected,
425            actual: input.len(),
426        });
427    }
428    let (g_plane, br_planes) = input.split_at(pixels);
429    let (b_plane, r_plane) = br_planes.split_at(pixels);
430    let mut output = vec![0; expected];
431    for idx in 0..pixels {
432        let offset = idx * 3;
433        output[offset] = r_plane[idx];
434        output[offset + 1] = g_plane[idx];
435        output[offset + 2] = b_plane[idx];
436    }
437    Ok(output)
438}
439
440/// Scale one sample value between two bit depths with rounding.
441pub fn scale_sample_bit_depth(
442    sample: u16,
443    source_depth: SampleBitDepth,
444    target_depth: SampleBitDepth,
445) -> u16 {
446    let source_max = u32::from(source_depth.max_sample());
447    let target_max = u32::from(target_depth.max_sample());
448    let sample = u32::from(sample).min(source_max);
449    if source_max == target_max {
450        return sample as u16;
451    }
452    ((sample * target_max + (source_max / 2)) / source_max) as u16
453}
454
455/// Read one little-endian planar sample from a raw sample buffer.
456///
457/// Returns `None` when `sample_index` is out of bounds.
458pub fn read_planar_sample(
459    input: &[u8],
460    sample_index: usize,
461    bit_depth: SampleBitDepth,
462) -> Option<u16> {
463    let offset = sample_index.checked_mul(bit_depth.bytes_per_sample())?;
464    if bit_depth.bits() <= 8 {
465        input.get(offset).copied().map(u16::from)
466    } else {
467        Some(u16::from_le_bytes([
468            *input.get(offset)?,
469            *input.get(offset + 1)?,
470        ]))
471    }
472}
473
474/// Write one little-endian planar sample into a raw sample buffer.
475///
476/// Returns `None` when `sample_index` is out of bounds.
477pub fn write_planar_sample(
478    output: &mut [u8],
479    sample_index: usize,
480    sample: u16,
481    bit_depth: SampleBitDepth,
482) -> Option<()> {
483    let offset = sample_index.checked_mul(bit_depth.bytes_per_sample())?;
484    if bit_depth.bits() <= 8 {
485        if offset >= output.len() {
486            return None;
487        }
488        output[offset] = sample as u8;
489    } else {
490        if offset + 1 >= output.len() {
491            return None;
492        }
493        let bytes = sample.to_le_bytes();
494        output[offset] = bytes[0];
495        output[offset + 1] = bytes[1];
496    }
497    Some(())
498}
499
500/// Compute sum of squared error for two equally sized planar sample buffers.
501///
502/// Returns `None` when the buffers differ in length or high-bit-depth buffers
503/// are not made of complete little-endian samples.
504pub fn planar_sample_sse(
505    source: &[u8],
506    reconstruction: &[u8],
507    bit_depth: SampleBitDepth,
508) -> Option<u64> {
509    if source.len() != reconstruction.len() {
510        return None;
511    }
512    if bit_depth.bits() <= 8 {
513        return Some(
514            source
515                .iter()
516                .zip(reconstruction)
517                .map(|(&src, &rec)| {
518                    let diff = i32::from(src) - i32::from(rec);
519                    (diff * diff) as u64
520                })
521                .sum(),
522        );
523    }
524    if !source.len().is_multiple_of(2) {
525        return None;
526    }
527
528    Some(
529        source
530            .chunks_exact(2)
531            .zip(reconstruction.chunks_exact(2))
532            .map(|(src, rec)| {
533                let src = u16::from_le_bytes([src[0], src[1]]).min(bit_depth.max_sample());
534                let rec = u16::from_le_bytes([rec[0], rec[1]]).min(bit_depth.max_sample());
535                let diff = i32::from(src) - i32::from(rec);
536                (diff * diff) as u64
537            })
538            .sum(),
539    )
540}
541
542impl FromStr for PixelFormat {
543    type Err = String;
544
545    fn from_str(value: &str) -> std::result::Result<Self, Self::Err> {
546        let value = value.trim().to_ascii_lowercase();
547        match value.as_str() {
548            "yuv420p" | "yuv420p8" | "i420" => Ok(Self::Yuv420p8),
549            "yuv422p" | "yuv422p8" | "i422" => Ok(Self::Yuv422p8),
550            "yuv444p" | "yuv444p8" | "i444" => Ok(Self::Yuv444p8),
551            "gray8" | "y8" => Ok(Self::Gray8),
552            "gbrp" | "gbrp8" => Ok(Self::Gbrp8),
553            "rgb24" => Ok(Self::Rgb24),
554            other => {
555                if let Some(format) = parse_planar_yuv_pixel_format(other)? {
556                    return Ok(format);
557                }
558                if let Some(format) = parse_gray_pixel_format(other)? {
559                    return Ok(format);
560                }
561                if let Some(format) = parse_hardware_yuv_alias(other)? {
562                    return Ok(format);
563                }
564                Err(format!(
565                    "unsupported format '{other}'; supported formats: yuv420p8..16le, yuv422p8..16le, yuv444p8..16le, gray8..16le, gbrp8, and rgb24"
566                ))
567            }
568        }
569    }
570}
571
572fn parse_planar_yuv_pixel_format(value: &str) -> std::result::Result<Option<PixelFormat>, String> {
573    for (prefix, chroma_sampling) in [
574        ("yuv420p", ChromaSampling::Cs420),
575        ("yuv422p", ChromaSampling::Cs422),
576        ("yuv444p", ChromaSampling::Cs444),
577    ] {
578        let Some(suffix) = value.strip_prefix(prefix) else {
579            continue;
580        };
581        let bit_depth = parse_planar_bit_depth_suffix(value, suffix)?;
582        return Ok(Some(PixelFormat::planar_yuv(chroma_sampling, bit_depth)));
583    }
584    Ok(None)
585}
586
587fn parse_gray_pixel_format(value: &str) -> std::result::Result<Option<PixelFormat>, String> {
588    for prefix in ["gray", "y"] {
589        let Some(suffix) = value.strip_prefix(prefix) else {
590            continue;
591        };
592        let bit_depth = parse_planar_bit_depth_suffix(value, suffix)?;
593        return Ok(Some(PixelFormat::gray_with_depth(bit_depth)));
594    }
595    Ok(None)
596}
597
598fn parse_hardware_yuv_alias(value: &str) -> std::result::Result<Option<PixelFormat>, String> {
599    let Some(rest) = value.strip_prefix('i') else {
600        return Ok(None);
601    };
602    if rest.len() != 3 {
603        return Ok(None);
604    }
605    let (sampling_digit, depth_text) = rest.split_at(1);
606    let chroma_sampling = match sampling_digit {
607        "0" => ChromaSampling::Cs420,
608        "2" => ChromaSampling::Cs422,
609        "4" => ChromaSampling::Cs444,
610        _ => return Ok(None),
611    };
612    let bit_depth = parse_bit_depth(value, depth_text)?;
613    Ok(Some(PixelFormat::planar_yuv(chroma_sampling, bit_depth)))
614}
615
616fn parse_planar_bit_depth_suffix(
617    value: &str,
618    suffix: &str,
619) -> std::result::Result<SampleBitDepth, String> {
620    let suffix = suffix.strip_suffix("le").unwrap_or(suffix);
621    if suffix.ends_with("be") {
622        return Err(format!(
623            "unsupported format '{value}'; big-endian raw samples are not supported yet"
624        ));
625    }
626    if suffix.is_empty() {
627        return Ok(SampleBitDepth::new_unchecked(8));
628    }
629    parse_bit_depth(value, suffix)
630}
631
632fn parse_bit_depth(value: &str, bits: &str) -> std::result::Result<SampleBitDepth, String> {
633    let parsed = bits
634        .parse::<u8>()
635        .map_err(|_| format!("unsupported format '{value}'; bit depth must be 8..16"))?;
636    SampleBitDepth::new(parsed)
637        .ok_or_else(|| format!("unsupported format '{value}'; bit depth must be 8..16"))
638}
639
640impl fmt::Display for PixelFormat {
641    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
642        f.write_str(&self.name())
643    }
644}
645
646/// Validated raw frame geometry and pixel format.
647#[derive(Debug, Clone, Copy, PartialEq, Eq)]
648pub struct FrameInfo {
649    /// Frame width in pixels.
650    pub width: usize,
651    /// Frame height in pixels.
652    pub height: usize,
653    /// Raw pixel format.
654    pub format: PixelFormat,
655}
656
657impl FrameInfo {
658    /// Validate and create frame metadata.
659    pub fn new(width: usize, height: usize, format: PixelFormat) -> Result<Self> {
660        format.validate_geometry(width, height)?;
661        Ok(Self {
662            width,
663            height,
664            format,
665        })
666    }
667
668    /// Byte length required for one complete frame with this metadata.
669    pub fn expected_len(self) -> usize {
670        self.format
671            .frame_len(self.width, self.height)
672            .expect("validated frame dimensions must have a byte length")
673    }
674}
675
676/// Owned raw frame buffer paired with validated frame metadata.
677#[derive(Debug, Clone, PartialEq, Eq)]
678pub struct Frame {
679    info: FrameInfo,
680    data: Vec<u8>,
681}
682
683/// Borrowed raw frame buffer paired with validated frame metadata.
684#[derive(Debug, Clone, Copy, PartialEq, Eq)]
685pub struct FrameRef<'a> {
686    info: FrameInfo,
687    data: &'a [u8],
688}
689
690/// Per-plane and aggregate PSNR values for a reconstructed frame.
691#[derive(Debug, Clone, Copy, PartialEq)]
692pub struct FramePsnr {
693    /// First plane PSNR. For RGB-family formats this is red.
694    pub plane0: f64,
695    /// Second plane PSNR. For RGB-family formats this is green.
696    pub plane1: f64,
697    /// Third plane PSNR. For RGB-family formats this is blue.
698    pub plane2: f64,
699    /// Aggregate PSNR over every sample.
700    pub all: f64,
701}
702
703impl Frame {
704    /// Create an owned frame, validating that `data` has exactly the expected length.
705    pub fn new(info: FrameInfo, data: Vec<u8>) -> Result<Self> {
706        let expected = info.expected_len();
707        let actual = data.len();
708        if actual != expected {
709            return Err(MediaError::BufferLength { expected, actual });
710        }
711
712        Ok(Self { info, data })
713    }
714
715    /// Create an all-zero frame with the expected byte length for `info`.
716    pub fn blank(info: FrameInfo) -> Self {
717        Self {
718            info,
719            data: vec![0; info.expected_len()],
720        }
721    }
722
723    /// Metadata describing this frame.
724    pub fn info(&self) -> FrameInfo {
725        self.info
726    }
727
728    /// Raw frame bytes.
729    pub fn data(&self) -> &[u8] {
730        &self.data
731    }
732
733    /// Borrow this frame as a [`FrameRef`].
734    pub fn as_frame_ref(&self) -> FrameRef<'_> {
735        FrameRef {
736            info: self.info,
737            data: &self.data,
738        }
739    }
740
741    /// Consume the frame and return its raw bytes.
742    pub fn into_data(self) -> Vec<u8> {
743        self.data
744    }
745}
746
747impl<'a> FrameRef<'a> {
748    /// Create a borrowed frame, validating that `data` has exactly the expected length.
749    pub fn new(info: FrameInfo, data: &'a [u8]) -> Result<Self> {
750        let expected = info.expected_len();
751        let actual = data.len();
752        if actual != expected {
753            return Err(MediaError::BufferLength { expected, actual });
754        }
755
756        Ok(Self { info, data })
757    }
758
759    /// Metadata describing this borrowed frame.
760    pub fn info(self) -> FrameInfo {
761        self.info
762    }
763
764    /// Raw borrowed frame bytes.
765    pub fn data(self) -> &'a [u8] {
766        self.data
767    }
768
769    /// Copy this borrowed frame into an owned [`Frame`].
770    pub fn to_owned_frame(self) -> Frame {
771        Frame {
772            info: self.info,
773            data: self.data.to_vec(),
774        }
775    }
776}
777
778/// Compute PSNR between a source frame and reconstruction.
779///
780/// Returns `None` when the buffers do not match the byte length implied by
781/// `info` or the format is unsupported by the metric helper.
782pub fn frame_psnr(info: FrameInfo, source: &[u8], reconstruction: &[u8]) -> Option<FramePsnr> {
783    let luma_samples = info.width.checked_mul(info.height)?;
784    if info.format == PixelFormat::Rgb24 {
785        return rgb24_frame_psnr(luma_samples, source, reconstruction);
786    }
787    if info.format == PixelFormat::Gbrp8 {
788        return gbrp8_frame_psnr(luma_samples, source, reconstruction);
789    }
790    let chroma_sampling = info.format.chroma_sampling()?;
791    let chroma_width = info.width.checked_div(chroma_sampling.subsample_x())?;
792    let chroma_height = info.height.checked_div(chroma_sampling.subsample_y())?;
793    let chroma_samples = chroma_width.checked_mul(chroma_height)?;
794    let bytes_per_sample = info.format.bit_depth().bytes_per_sample();
795    let luma_len = luma_samples.checked_mul(bytes_per_sample)?;
796    let chroma_len = chroma_samples.checked_mul(bytes_per_sample)?;
797    let frame_len = luma_len.checked_add(chroma_len.checked_mul(2)?)?;
798    if source.len() != frame_len || reconstruction.len() != frame_len {
799        return None;
800    }
801    if source == reconstruction {
802        return Some(FramePsnr::infinite());
803    }
804
805    let y_src = &source[..luma_len];
806    let y_rec = &reconstruction[..luma_len];
807    let u_start = luma_len;
808    let v_start = luma_len + chroma_len;
809    let u_src = &source[u_start..v_start];
810    let u_rec = &reconstruction[u_start..v_start];
811    let v_src = &source[v_start..frame_len];
812    let v_rec = &reconstruction[v_start..frame_len];
813
814    let bit_depth = info.format.bit_depth();
815    let y_sse = planar_sample_sse(y_src, y_rec, bit_depth)?;
816    let u_sse = planar_sample_sse(u_src, u_rec, bit_depth)?;
817    let v_sse = planar_sample_sse(v_src, v_rec, bit_depth)?;
818    let max_sample = f64::from(bit_depth.max_sample());
819    Some(FramePsnr {
820        plane0: psnr_from_sse(y_sse, luma_samples, max_sample),
821        plane1: psnr_from_sse(u_sse, chroma_samples, max_sample),
822        plane2: psnr_from_sse(v_sse, chroma_samples, max_sample),
823        all: psnr_from_sse(
824            y_sse + u_sse + v_sse,
825            luma_samples + chroma_samples * 2,
826            max_sample,
827        ),
828    })
829}
830
831impl FramePsnr {
832    fn infinite() -> Self {
833        Self {
834            plane0: f64::INFINITY,
835            plane1: f64::INFINITY,
836            plane2: f64::INFINITY,
837            all: f64::INFINITY,
838        }
839    }
840}
841
842fn gbrp8_frame_psnr(pixels: usize, source: &[u8], reconstruction: &[u8]) -> Option<FramePsnr> {
843    let plane_len = pixels;
844    let frame_len = plane_len.checked_mul(3)?;
845    if source.len() != frame_len || reconstruction.len() != frame_len {
846        return None;
847    }
848    if source == reconstruction {
849        return Some(FramePsnr::infinite());
850    }
851
852    let (source_g, source_chroma) = source.split_at(plane_len);
853    let (source_b, source_r) = source_chroma.split_at(plane_len);
854    let (recon_g, recon_chroma) = reconstruction.split_at(plane_len);
855    let (recon_b, recon_r) = recon_chroma.split_at(plane_len);
856    let r_sse = planar_sample_sse(source_r, recon_r, SampleBitDepth::new_unchecked(8))?;
857    let g_sse = planar_sample_sse(source_g, recon_g, SampleBitDepth::new_unchecked(8))?;
858    let b_sse = planar_sample_sse(source_b, recon_b, SampleBitDepth::new_unchecked(8))?;
859    Some(FramePsnr {
860        plane0: psnr_from_sse(r_sse, pixels, 255.0),
861        plane1: psnr_from_sse(g_sse, pixels, 255.0),
862        plane2: psnr_from_sse(b_sse, pixels, 255.0),
863        all: psnr_from_sse(r_sse + g_sse + b_sse, frame_len, 255.0),
864    })
865}
866
867fn rgb24_frame_psnr(pixels: usize, source: &[u8], reconstruction: &[u8]) -> Option<FramePsnr> {
868    let frame_len = pixels.checked_mul(3)?;
869    if source.len() != frame_len || reconstruction.len() != frame_len {
870        return None;
871    }
872    if source == reconstruction {
873        return Some(FramePsnr::infinite());
874    }
875
876    let mut r_sse = 0u64;
877    let mut g_sse = 0u64;
878    let mut b_sse = 0u64;
879    for (src, rec) in source.chunks_exact(3).zip(reconstruction.chunks_exact(3)) {
880        let r_diff = src[0] as i32 - rec[0] as i32;
881        let g_diff = src[1] as i32 - rec[1] as i32;
882        let b_diff = src[2] as i32 - rec[2] as i32;
883        r_sse += (r_diff * r_diff) as u64;
884        g_sse += (g_diff * g_diff) as u64;
885        b_sse += (b_diff * b_diff) as u64;
886    }
887
888    Some(FramePsnr {
889        plane0: psnr_from_sse(r_sse, pixels, 255.0),
890        plane1: psnr_from_sse(g_sse, pixels, 255.0),
891        plane2: psnr_from_sse(b_sse, pixels, 255.0),
892        all: psnr_from_sse(r_sse + g_sse + b_sse, frame_len, 255.0),
893    })
894}
895
896fn psnr_from_sse(sse: u64, samples: usize, max_sample: f64) -> f64 {
897    if sse == 0 {
898        f64::INFINITY
899    } else {
900        10.0 * ((max_sample * max_sample * samples as f64) / sse as f64).log10()
901    }
902}
903
904#[cfg(test)]
905mod tests {
906    use super::*;
907
908    #[test]
909    fn computes_common_frame_lengths() {
910        assert_eq!(PixelFormat::Yuv420p8.frame_len(16, 16), Some(384));
911        assert_eq!(PixelFormat::Yuv444p8.frame_len(16, 16), Some(768));
912        assert_eq!(PixelFormat::Gbrp8.frame_len(16, 16), Some(768));
913        assert_eq!(PixelFormat::Rgb24.frame_len(16, 16), Some(768));
914        assert_eq!(PixelFormat::yuv420(9).unwrap().frame_len(16, 16), Some(768));
915        assert_eq!(
916            PixelFormat::yuv420(10).unwrap().frame_len(16, 16),
917            Some(768)
918        );
919        assert_eq!(
920            PixelFormat::yuv444(15).unwrap().frame_len(16, 16),
921            Some(1536)
922        );
923    }
924
925    #[test]
926    fn chroma_sampling_reports_subsampling_factors() {
927        assert_eq!(ChromaSampling::Cs420.subsample_x(), 2);
928        assert_eq!(ChromaSampling::Cs420.subsample_y(), 2);
929        assert_eq!(ChromaSampling::Cs422.subsample_x(), 2);
930        assert_eq!(ChromaSampling::Cs422.subsample_y(), 1);
931        assert_eq!(ChromaSampling::Cs444.subsample_x(), 1);
932        assert_eq!(ChromaSampling::Cs444.subsample_y(), 1);
933    }
934
935    #[test]
936    fn planar_sample_sse_handles_8_and_high_bit_depth_samples() {
937        assert_eq!(
938            planar_sample_sse(&[0, 10, 20], &[1, 8, 20], SampleBitDepth::new(8).unwrap()),
939            Some(5)
940        );
941
942        let source = [0u16, 1023, 512]
943            .into_iter()
944            .flat_map(u16::to_le_bytes)
945            .collect::<Vec<_>>();
946        let reconstruction = [1u16, 1020, 512]
947            .into_iter()
948            .flat_map(u16::to_le_bytes)
949            .collect::<Vec<_>>();
950        assert_eq!(
951            planar_sample_sse(&source, &reconstruction, SampleBitDepth::new(10).unwrap()),
952            Some(10)
953        );
954        assert_eq!(
955            planar_sample_sse(
956                &source[..5],
957                &reconstruction[..5],
958                SampleBitDepth::new(10).unwrap()
959            ),
960            None
961        );
962        assert_eq!(
963            planar_sample_sse(
964                &source,
965                &reconstruction[..4],
966                SampleBitDepth::new(10).unwrap()
967            ),
968            None
969        );
970    }
971
972    #[test]
973    fn rejects_odd_420_dimensions() {
974        let err = FrameInfo::new(15, 16, PixelFormat::Yuv420p8).unwrap_err();
975        assert!(err.to_string().contains("must be even"));
976    }
977
978    #[test]
979    fn validates_frame_buffer_length() {
980        let info = FrameInfo::new(8, 8, PixelFormat::Yuv444p8).unwrap();
981        let frame = Frame::new(info, vec![0; 192]);
982        assert!(frame.is_ok());
983
984        let err = Frame::new(info, vec![0; 191]).unwrap_err();
985        assert_eq!(
986            err,
987            MediaError::BufferLength {
988                expected: 192,
989                actual: 191,
990            }
991        );
992    }
993
994    #[test]
995    fn frame_ref_validates_borrowed_frame_length() {
996        let info = FrameInfo::new(4, 4, PixelFormat::Rgb24).unwrap();
997        let data = vec![7; info.expected_len()];
998        let view = FrameRef::new(info, &data).expect("valid borrowed frame");
999
1000        assert_eq!(view.info(), info);
1001        assert_eq!(view.data(), data.as_slice());
1002        assert_eq!(view.to_owned_frame(), Frame::new(info, data).unwrap());
1003    }
1004
1005    #[test]
1006    fn frame_psnr_reports_yuv422p8() {
1007        let info = FrameInfo::new(4, 2, PixelFormat::Yuv422p8).unwrap();
1008        let source = vec![0u8; info.expected_len()];
1009        let mut reconstruction = source.clone();
1010        reconstruction[0] = 16;
1011        reconstruction[8] = 8;
1012        reconstruction[12] = 4;
1013
1014        let psnr = frame_psnr(info, &source, &reconstruction).expect("4:2:2 PSNR");
1015        assert!(psnr.plane0.is_finite());
1016        assert!(psnr.plane1.is_finite());
1017        assert!(psnr.plane2.is_finite());
1018        assert!(psnr.all.is_finite());
1019    }
1020
1021    #[test]
1022    fn frame_psnr_uses_high_bit_depth_peak_sample() {
1023        let info = FrameInfo::new(4, 2, PixelFormat::yuv420(10).unwrap()).unwrap();
1024        let mut source = vec![0u8; info.expected_len()];
1025        let mut reconstruction = source.clone();
1026        source[0..2].copy_from_slice(&1023u16.to_le_bytes());
1027        reconstruction[0..2].copy_from_slice(&1022u16.to_le_bytes());
1028
1029        let psnr = frame_psnr(info, &source, &reconstruction).expect("10-bit PSNR");
1030        assert!(psnr.all > 70.0, "10-bit peak sample should be used");
1031    }
1032
1033    #[test]
1034    fn parses_hardware_model_pixel_format_aliases() {
1035        assert_eq!(
1036            "i010".parse::<PixelFormat>(),
1037            Ok(PixelFormat::yuv420(10).unwrap())
1038        );
1039        assert_eq!("yuv444p".parse::<PixelFormat>(), Ok(PixelFormat::Yuv444p8));
1040        assert_eq!("gbrp".parse::<PixelFormat>(), Ok(PixelFormat::Gbrp8));
1041        assert_eq!("gbrp8".parse::<PixelFormat>(), Ok(PixelFormat::Gbrp8));
1042        assert_eq!("rgb24".parse::<PixelFormat>(), Ok(PixelFormat::Rgb24));
1043    }
1044
1045    #[test]
1046    fn parses_planar_input_depths_between_8_and_16_bits() {
1047        assert_eq!(
1048            "yuv420p9le".parse::<PixelFormat>(),
1049            Ok(PixelFormat::yuv420(9).unwrap())
1050        );
1051        assert_eq!(
1052            "yuv422p11le".parse::<PixelFormat>(),
1053            Ok(PixelFormat::yuv422(11).unwrap())
1054        );
1055        assert_eq!(
1056            "yuv444p14le".parse::<PixelFormat>(),
1057            Ok(PixelFormat::yuv444(14).unwrap())
1058        );
1059        assert_eq!(
1060            "gray15le".parse::<PixelFormat>(),
1061            Ok(PixelFormat::gray(15).unwrap())
1062        );
1063        assert_eq!(
1064            SampleBitDepth::from_bits(13),
1065            Some(SampleBitDepth::new(13).unwrap())
1066        );
1067    }
1068
1069    #[test]
1070    fn maps_planar_formats_to_the_same_layout_at_another_depth() {
1071        assert_eq!(
1072            PixelFormat::yuv420(13)
1073                .unwrap()
1074                .with_bit_depth(SampleBitDepth::new(8).unwrap()),
1075            Some(PixelFormat::Yuv420p8)
1076        );
1077        assert_eq!(
1078            PixelFormat::Yuv444p8.with_bit_depth(SampleBitDepth::new(16).unwrap()),
1079            PixelFormat::yuv444(16)
1080        );
1081        assert_eq!(
1082            PixelFormat::Rgb24.with_bit_depth(SampleBitDepth::new(8).unwrap()),
1083            None
1084        );
1085        assert_eq!(
1086            PixelFormat::Gbrp8.with_bit_depth(SampleBitDepth::new(8).unwrap()),
1087            None
1088        );
1089    }
1090
1091    #[test]
1092    fn converts_planar_frame_bit_depth_without_changing_layout() {
1093        let input = [
1094            0u16, 1023, 512, 256, // Y
1095            128, // U
1096            768, // V
1097        ]
1098        .into_iter()
1099        .flat_map(u16::to_le_bytes)
1100        .collect::<Vec<_>>();
1101
1102        let output = convert_planar_frame_bit_depth(
1103            &input,
1104            2,
1105            2,
1106            PixelFormat::yuv420(10).unwrap(),
1107            PixelFormat::Yuv420p8,
1108        )
1109        .unwrap();
1110
1111        assert_eq!(output, vec![0, 255, 128, 64, 32, 191]);
1112    }
1113
1114    #[test]
1115    fn converts_packed_rgb24_to_planar_gbrp8_and_back() {
1116        let rgb24 = vec![
1117            10, 20, 30, //
1118            40, 50, 60, //
1119            70, 80, 90, //
1120            100, 110, 120,
1121        ];
1122
1123        let gbrp8 =
1124            convert_frame_format(&rgb24, 2, 2, PixelFormat::Rgb24, PixelFormat::Gbrp8).unwrap();
1125        assert_eq!(
1126            gbrp8,
1127            vec![20, 50, 80, 110, 30, 60, 90, 120, 10, 40, 70, 100]
1128        );
1129
1130        let roundtrip =
1131            convert_frame_format(&gbrp8, 2, 2, PixelFormat::Gbrp8, PixelFormat::Rgb24).unwrap();
1132        assert_eq!(roundtrip, rgb24);
1133    }
1134
1135    #[test]
1136    fn convert_frame_format_preserves_existing_planar_bit_depth_path() {
1137        let input = [
1138            0u16, 1023, 512, 256, // Y
1139            128, // U
1140            768, // V
1141        ]
1142        .into_iter()
1143        .flat_map(u16::to_le_bytes)
1144        .collect::<Vec<_>>();
1145
1146        let output = convert_frame_format(
1147            &input,
1148            2,
1149            2,
1150            PixelFormat::yuv420(10).unwrap(),
1151            PixelFormat::Yuv420p8,
1152        )
1153        .unwrap();
1154
1155        assert_eq!(output, vec![0, 255, 128, 64, 32, 191]);
1156    }
1157
1158    #[test]
1159    fn rejects_bit_depth_conversion_that_changes_chroma_layout() {
1160        let input = vec![0; PixelFormat::yuv420(10).unwrap().frame_len(2, 2).unwrap()];
1161        let err = convert_planar_frame_bit_depth(
1162            &input,
1163            2,
1164            2,
1165            PixelFormat::yuv420(10).unwrap(),
1166            PixelFormat::Yuv444p8,
1167        )
1168        .unwrap_err();
1169        assert!(err.to_string().contains("cannot change chroma layout"));
1170    }
1171
1172    #[test]
1173    fn reads_and_writes_planar_samples_by_numeric_bit_depth() {
1174        let depth = SampleBitDepth::new(10).unwrap();
1175        let mut data = vec![0; 4];
1176        assert_eq!(write_planar_sample(&mut data, 0, 1023, depth), Some(()));
1177        assert_eq!(write_planar_sample(&mut data, 1, 1, depth), Some(()));
1178        assert_eq!(read_planar_sample(&data, 0, depth), Some(1023));
1179        assert_eq!(read_planar_sample(&data, 1, depth), Some(1));
1180        assert_eq!(read_planar_sample(&data, 2, depth), None);
1181    }
1182}