1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
//! Streaming reader and writer for the YUV4MPEG2 (`.y4m`) uncompressed
//! planar video format.
//!
//! The decoder works over any [`std::io::Read`] and the encoder over any
//! [`std::io::Write`]. Design points:
//!
//! - **Borrowed frames.** [`Decoder::read_frame`] returns a [`FrameRef`]
//! borrowing one reusable internal buffer, so the decode and encode hot
//! paths reuse the same storage for every frame. The counting-allocator
//! test `tests/zero_alloc.rs` pins both loops at zero heap allocations.
//! - **Defined endianness.** Samples deeper than 8 bits are little-endian on
//! the wire on every host. [`FrameRef::plane_u16`] yields host-order
//! samples, and [`Encoder::write_frame_u16`] converts host-order samples to
//! little-endian wire bytes.
//! - **Byte-exact round-trips.** Raw header and frame parameter bytes are
//! preserved verbatim, so decode followed by re-encode reproduces the
//! input byte-for-byte.
//! - **Typed errors.** Malformed, truncated, or over-budget input yields a
//! matching [`Error`] variant, and all size arithmetic is checked.
//!
//! # Reading
//!
//! ```
//! use y4m_codec::{Decoder, Error};
//!
//! let data: &[u8] = b"YUV4MPEG2 W2 H2 F25:1 C420\nFRAME\n\x00\x01\x02\x03\x80\x80";
//! let mut decoder = Decoder::new(data)?;
//! assert_eq!((decoder.width(), decoder.height()), (2, 2));
//! let frame = decoder.read_frame()?;
//! assert_eq!(frame.y(), &[0x00, 0x01, 0x02, 0x03]);
//! assert!(matches!(decoder.read_frame(), Err(Error::EndOfStream)));
//! # Ok::<(), y4m_codec::Error>(())
//! ```
//!
//! # Writing
//!
//! ```
//! use y4m_codec::{EncoderBuilder, Ratio};
//!
//! let mut out = Vec::new();
//! let mut encoder = EncoderBuilder::new(2, 2, Ratio::new(25, 1)).write_header(&mut out)?;
//! encoder.write_frame([&[0, 1, 2, 3], &[0x80], &[0x80]])?;
//! assert!(out.starts_with(b"YUV4MPEG2 W2 H2 F25:1 C420\nFRAME\n"));
//! # Ok::<(), y4m_codec::Error>(())
//! ```
pub use ;
pub use ;
pub use ;
pub use Error;
/// An exact rational value, used for the `F` (framerate) and `A` (pixel
/// aspect) header tags. `0:0` is the unknown-aspect sentinel.
/// Interlacing mode from the stream header `I` tag.
///
/// Metadata only: plane layout is unaffected, and an absent tag reads as
/// [`Interlace::Unknown`], treated as progressive.