Skip to content
rachel/esp32-radio
File

Blob: firmware/vendor/str0m/src/packet/h265_profile.rs

rust375 lines
1use std::collections::HashMap;
2 
3use serde::{Deserialize, Serialize};
4 
5/// H.265/HEVC profile, tier, and level combination.
6///
7/// Represents the three SDP fmtp parameters `profile-id`, `tier-flag`, and `level-id`
8/// as defined in RFC 7798 §7.1 and ITU-T H.265 Annex A.
9#[derive(Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize)]
10pub struct H265ProfileTierLevel {
11    profile: H265Profile,
12    tier: H265Tier,
13    level: H265Level,
14}
15 
16impl H265ProfileTierLevel {
17    // RFC 7798 §7.1 default values when parameters are absent from SDP:
18    // profile-id=1 (Main), tier-flag=0 (Main tier), level-id=93 (Level 3.1).
19    // https://www.rfc-editor.org/rfc/rfc7798#section-7.1
20    pub(crate) const FALLBACK: Self = Self {
21        profile: H265Profile::Main,
22        tier: H265Tier::Main,
23        level: H265Level::Level3_1,
24    };
25 
26    /// Construct a new H265ProfileTierLevel from profile_id, tier_flag, and level_id.
27    ///
28    /// Returns `Some(Self)` only if the provided parameters identify valid values.
29    pub(crate) fn new(profile_id: u8, tier_flag: u8, level_id: u8) -> Option<Self> {
30        let profile = H265Profile::from_id(profile_id)?;
31        let tier = H265Tier::from_flag(tier_flag)?;
32        let level = H265Level::from_id(level_id)?;
33 
34        Some(Self {
35            profile,
36            tier,
37            level,
38        })
39    }
40 
41    /// Parse H265ProfileTierLevel from SDP fmtp parameters.
42    ///
43    /// Expects keys: "profile-id", "tier-flag", "level-id"
44    /// Returns None if any required parameter is missing or invalid.
45    pub(crate) fn from_fmtp(params: &HashMap<String, String>) -> Option<Self> {
46        let profile_id: u8 = params.get("profile-id")?.parse().ok()?;
47        let tier_flag: u8 = params.get("tier-flag")?.parse().ok()?;
48        let level_id: u8 = params.get("level-id")?.parse().ok()?;
49 
50        Self::new(profile_id, tier_flag, level_id)
51    }
52 
53    /// Returns the H.265 profile (Main, Main10, etc.).
54    pub fn profile(&self) -> H265Profile {
55        self.profile
56    }
57 
58    /// Returns the H.265 tier (Main or High).
59    pub fn tier(&self) -> H265Tier {
60        self.tier
61    }
62 
63    /// Returns the H.265 level (Level 3.1, Level 4.0, etc.).
64    pub fn level(&self) -> H265Level {
65        self.level
66    }
67 
68    /// Returns a copy with the level replaced.
69    pub fn with_level(self, level: H265Level) -> Self {
70        Self { level, ..self }
71    }
72 
73    /// Returns the numeric profile_id value for SDP serialization.
74    pub fn profile_id(&self) -> u8 {
75        self.profile.to_id()
76    }
77 
78    /// Returns the numeric tier_flag value for SDP serialization.
79    pub fn tier_flag(&self) -> u8 {
80        self.tier.to_flag()
81    }
82 
83    /// Returns the numeric level_id value for SDP serialization.
84    pub fn level_id(&self) -> u8 {
85        self.level.to_id()
86    }
87}
88 
89impl From<(u8, u8, u8)> for H265ProfileTierLevel {
90    fn from(value: (u8, u8, u8)) -> Self {
91        Self::new(value.0, value.1, value.2).unwrap_or(Self::FALLBACK)
92    }
93}
94 
95/// H.265 profile as defined in ITU-T H.265 Annex A.
96#[derive(Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize)]
97pub enum H265Profile {
98    /// Main profile (profile_id=1).
99    Main,
100    /// Main 10 profile (profile_id=2).
101    Main10,
102    /// Main Still Picture profile (profile_id=3).
103    MainStillPicture,
104    /// Format Range Extensions profile (profile_id=4).
105    FormatRangeExtensions,
106    /// High Throughput profile (profile_id=5).
107    HighThroughput,
108    /// Multiview Main profile (profile_id=6).
109    MultiviewMain,
110    /// Scalable Main profile (profile_id=7).
111    ScalableMain,
112    /// 3D Main profile (profile_id=8).
113    ThreeDMain,
114    /// Screen Content Coding profile (profile_id=9).
115    ScreenContentCoding,
116    /// Screen Content Coding Extensions profile (profile_id=10).
117    ScreenContentCodingExtensions,
118    /// High Throughput Screen Content Coding profile (profile_id=11).
119    HighThroughputScreenContentCoding,
120}
121 
122impl H265Profile {
123    /// Convert from H.265 profile_id value.
124    ///
125    /// See ITU-T H.265 (04/2013) Annex A for profile definitions.
126    fn from_id(profile_id: u8) -> Option<Self> {
127        match profile_id {
128            1 => Some(Self::Main),
129            2 => Some(Self::Main10),
130            3 => Some(Self::MainStillPicture),
131            4 => Some(Self::FormatRangeExtensions),
132            5 => Some(Self::HighThroughput),
133            6 => Some(Self::MultiviewMain),
134            7 => Some(Self::ScalableMain),
135            8 => Some(Self::ThreeDMain),
136            9 => Some(Self::ScreenContentCoding),
137            10 => Some(Self::ScreenContentCodingExtensions),
138            11 => Some(Self::HighThroughputScreenContentCoding),
139            _ => None,
140        }
141    }
142 
143    /// Convert to H.265 profile_id value.
144    pub fn to_id(self) -> u8 {
145        match self {
146            Self::Main => 1,
147            Self::Main10 => 2,
148            Self::MainStillPicture => 3,
149            Self::FormatRangeExtensions => 4,
150            Self::HighThroughput => 5,
151            Self::MultiviewMain => 6,
152            Self::ScalableMain => 7,
153            Self::ThreeDMain => 8,
154            Self::ScreenContentCoding => 9,
155            Self::ScreenContentCodingExtensions => 10,
156            Self::HighThroughputScreenContentCoding => 11,
157        }
158    }
159}
160 
161/// H.265 tier (Main or High).
162#[derive(Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize)]
163pub enum H265Tier {
164    /// Main tier (tier_flag=0).
165    Main,
166    /// High tier (tier_flag=1).
167    High,
168}
169 
170impl H265Tier {
171    /// Convert from H.265 tier_flag value.
172    ///
173    /// 0 = Main tier, 1 = High tier
174    fn from_flag(tier_flag: u8) -> Option<Self> {
175        match tier_flag {
176            0 => Some(Self::Main),
177            1 => Some(Self::High),
178            _ => None,
179        }
180    }
181 
182    /// Convert to H.265 tier_flag value.
183    pub fn to_flag(self) -> u8 {
184        match self {
185            Self::Main => 0,
186            Self::High => 1,
187        }
188    }
189}
190 
191/// H.265 level as defined in ITU-T H.265 Annex A.
192///
193/// Level IDs are 30× the level number (e.g., Level 3.1 = 93).
194#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
195#[repr(u8)]
196#[rustfmt::skip]
197pub enum H265Level {
198    /// Level 1.0 (level_id=30).
199    Level1   = 30_u8,
200    /// Level 2.0 (level_id=60).
201    Level2   = 60_u8,
202    /// Level 2.1 (level_id=63).
203    Level2_1 = 63_u8,
204    /// Level 3.0 (level_id=90).
205    Level3   = 90_u8,
206    /// Level 3.1 (level_id=93).
207    Level3_1 = 93_u8,
208    /// Level 4.0 (level_id=120).
209    Level4   = 120_u8,
210    /// Level 4.1 (level_id=123).
211    Level4_1 = 123_u8,
212    /// Level 5.0 (level_id=150).
213    Level5   = 150_u8,
214    /// Level 5.1 (level_id=153).
215    Level5_1 = 153_u8,
216    /// Level 5.2 (level_id=156).
217    Level5_2 = 156_u8,
218    /// Level 6.0 (level_id=180).
219    Level6   = 180_u8,
220    /// Level 6.1 (level_id=183).
221    Level6_1 = 183_u8,
222    /// Level 6.2 (level_id=186).
223    Level6_2 = 186_u8,
224}
225 
226#[cfg(feature = "drv")]
227crate::drv_identity_copy!(H265ProfileTierLevel, H265Profile, H265Tier, H265Level);
228 
229impl H265Level {
230    /// Returns the ordinal position (0-12) representing capability order.
231    pub fn ordinal(self) -> usize {
232        match self {
233            Self::Level1 => 0,
234            Self::Level2 => 1,
235            Self::Level2_1 => 2,
236            Self::Level3 => 3,
237            Self::Level3_1 => 4,
238            Self::Level4 => 5,
239            Self::Level4_1 => 6,
240            Self::Level5 => 7,
241            Self::Level5_1 => 8,
242            Self::Level5_2 => 9,
243            Self::Level6 => 10,
244            Self::Level6_1 => 11,
245            Self::Level6_2 => 12,
246        }
247    }
248 
249    /// Convert from H.265 level_id value.
250    fn from_id(level_id: u8) -> Option<Self> {
251        use H265Level::*;
252        match level_id {
253            x if (Level1 as u8) == x => Some(Level1),
254            x if (Level2 as u8) == x => Some(Level2),
255            x if (Level2_1 as u8) == x => Some(Level2_1),
256            x if (Level3 as u8) == x => Some(Level3),
257            x if (Level3_1 as u8) == x => Some(Level3_1),
258            x if (Level4 as u8) == x => Some(Level4),
259            x if (Level4_1 as u8) == x => Some(Level4_1),
260            x if (Level5 as u8) == x => Some(Level5),
261            x if (Level5_1 as u8) == x => Some(Level5_1),
262            x if (Level5_2 as u8) == x => Some(Level5_2),
263            x if (Level6 as u8) == x => Some(Level6),
264            x if (Level6_1 as u8) == x => Some(Level6_1),
265            x if (Level6_2 as u8) == x => Some(Level6_2),
266            _ => None,
267        }
268    }
269 
270    /// Convert to H.265 level_id value.
271    pub fn to_id(self) -> u8 {
272        self as u8
273    }
274}
275 
276impl PartialOrd for H265Level {
277    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
278        Some(self.cmp(other))
279    }
280}
281 
282impl Ord for H265Level {
283    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
284        self.ordinal().cmp(&other.ordinal())
285    }
286}
287 
288#[cfg(test)]
289mod test {
290    use super::*;
291 
292    #[test]
293    fn test_h265_profile_tier_level_new() {
294        // Valid combination
295        let ptl = H265ProfileTierLevel::new(1, 0, 93);
296        assert!(ptl.is_some());
297        let ptl = ptl.unwrap();
298        assert_eq!(ptl.profile(), H265Profile::Main);
299        assert_eq!(ptl.tier(), H265Tier::Main);
300        assert_eq!(ptl.level(), H265Level::Level3_1);
301 
302        // Invalid profile_id
303        let ptl = H265ProfileTierLevel::new(99, 0, 93);
304        assert!(ptl.is_none());
305 
306        // Invalid tier_flag
307        let ptl = H265ProfileTierLevel::new(1, 5, 93);
308        assert!(ptl.is_none());
309 
310        // Invalid level_id
311        let ptl = H265ProfileTierLevel::new(1, 0, 255);
312        assert!(ptl.is_none());
313    }
314 
315    #[test]
316    fn test_h265_profile_from_id() {
317        assert_eq!(H265Profile::from_id(1), Some(H265Profile::Main));
318        assert_eq!(H265Profile::from_id(2), Some(H265Profile::Main10));
319        assert_eq!(H265Profile::from_id(99), None);
320    }
321 
322    #[test]
323    fn test_h265_tier_from_flag() {
324        assert_eq!(H265Tier::from_flag(0), Some(H265Tier::Main));
325        assert_eq!(H265Tier::from_flag(1), Some(H265Tier::High));
326        assert_eq!(H265Tier::from_flag(2), None);
327    }
328 
329    #[test]
330    fn test_h265_level_from_id() {
331        assert_eq!(H265Level::from_id(30), Some(H265Level::Level1));
332        assert_eq!(H265Level::from_id(93), Some(H265Level::Level3_1));
333        assert_eq!(H265Level::from_id(186), Some(H265Level::Level6_2));
334        assert_eq!(H265Level::from_id(255), None);
335    }
336 
337    #[test]
338    fn test_h265_level_ordering() {
339        assert!(H265Level::Level1 < H265Level::Level2);
340        assert!(H265Level::Level3_1 < H265Level::Level4);
341        assert!(H265Level::Level6_1 < H265Level::Level6_2);
342        assert_eq!(H265Level::Level3_1.ordinal(), 4);
343    }
344 
345    #[test]
346    fn test_h265_profile_tier_level_from_fmtp() {
347        let mut params = HashMap::new();
348        params.insert("profile-id".to_string(), "1".to_string());
349        params.insert("tier-flag".to_string(), "0".to_string());
350        params.insert("level-id".to_string(), "93".to_string());
351 
352        let ptl = H265ProfileTierLevel::from_fmtp(&params);
353        assert!(ptl.is_some());
354        let ptl = ptl.unwrap();
355        assert_eq!(ptl.profile(), H265Profile::Main);
356        assert_eq!(ptl.tier(), H265Tier::Main);
357        assert_eq!(ptl.level(), H265Level::Level3_1);
358 
359        // Missing parameter
360        let mut params = HashMap::new();
361        params.insert("profile-id".to_string(), "1".to_string());
362        params.insert("tier-flag".to_string(), "0".to_string());
363        let ptl = H265ProfileTierLevel::from_fmtp(&params);
364        assert!(ptl.is_none());
365    }
366 
367    #[test]
368    fn test_fallback_values() {
369        let fallback = H265ProfileTierLevel::FALLBACK;
370        assert_eq!(fallback.profile(), H265Profile::Main);
371        assert_eq!(fallback.tier(), H265Tier::Main);
372        assert_eq!(fallback.level(), H265Level::Level3_1);
373    }
374}