1#![allow(non_camel_case_types)]
2#![warn(clippy::cargo)]
3#![cfg_attr(not(feature = "std"), no_std)]
4
5//! [`DrmFourcc`] is an enum representing every pixel format supported by DRM
6//! (as of kernel version 5.10.0).
7//!
8//! A [fourcc][fourcc_wiki] is four bytes of ascii representing some data format. This enum contains
9//! every fourcc representing a pixel format supported by [DRM][drm_wiki], the Linux Direct
10//! Rendering Manager. The names of pixel formats generally provide clues as to
11//! how they work, for more information you may find
12//! [this guide][drm_format_guide] helpful.
13//!
14//! To get the bytes of the fourcc representing the format, cast to `u32`.
15//!
16//! ```
17//! # use drm_fourcc::DrmFourcc;
18//! assert_eq!(DrmFourcc::Xrgb8888 as u32, 875713112);
19//! ```
20//!
21//! To get the string form of the fourcc, use [`ToString::to_string`].
22//!
23//! ```
24//! # use drm_fourcc::DrmFourcc;
25//! assert_eq!(DrmFourcc::Xrgb8888.to_string(), "XR24");
26//! ```
27//!
28//!
29//! We also provide a type for representing a fourcc/modifier pair
30//!
31//! ```
32//! # use drm_fourcc::{DrmFormat, DrmFourcc, DrmModifier};
33//! let format = DrmFormat {
34//! code: DrmFourcc::Xrgb8888,
35//! modifier: DrmModifier::Linear,
36//! };
37//! ```
38//!
39//! The enums are autogenerated from the [canonical list][canonical] in the Linux source code.
40//!
41//! ## Features
42//! - `serde` - Derive Serialize/Deserialize where it makes sense
43//! - `build_bindings` - Re-generate autogenerated code. Useful if you need varients added in a
44//! more recent kernel version.
45//!
46//! [fourcc_wiki]: https://en.wikipedia.org/wiki/FourCC
47//! [drm_wiki]: https://en.wikipedia.org/wiki/Direct_Rendering_Managerz
48//! [canonical]: https://github.com/torvalds/linux/blame/master/include/uapi/drm/drm_fourcc.h
49//! [drm_format_guide]: https://afrantzis.com/pixel-format-guide/drm.html
50use core::convert::TryFrom;
51use core::fmt;
52use core::fmt::{Debug, Display, Formatter};
53use core::hash::{Hash, Hasher};
54
55#[cfg(feature = "std")]
56use std::string::{String, ToString};
57
58#[cfg(feature = "std")]
59use std::error::Error;
60
61pub use as_enum::{DrmFourcc, DrmModifier, DrmVendor};
62
63mod as_enum;
64mod consts;
65
66#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
67#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
68pub struct DrmFormat {
69 pub code: DrmFourcc,
70 pub modifier: DrmModifier,
71}
72
73impl DrmFourcc {
74 /// Get the string representation of the format's fourcc.
75 #[cfg(feature = "std")]
76 #[deprecated(since = "2.2.0", note = "Use `ToString::to_string` instead")]
77 pub fn string_form(&self) -> String {
78 self.display_form().to_string()
79 }
80
81 // Internal helper to clarify it always has Display.
82 fn display_form(&self) -> impl Display + Debug {
83 fourcc_display_form(*self as u32).expect(msg:"Must be valid fourcc")
84 }
85}
86
87impl Debug for DrmFourcc {
88 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
89 f&mut DebugTuple<'_, '_>.debug_tuple(name:"DrmFourcc")
90 .field(&self.display_form())
91 .finish()
92 }
93}
94
95impl Display for DrmFourcc {
96 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
97 Display::fmt(&self.display_form(), f)
98 }
99}
100
101impl TryFrom<u32> for DrmFourcc {
102 type Error = UnrecognizedFourcc;
103
104 /// Convert from an u32
105 ///
106 #[cfg_attr(feature = "std", doc = "```")]
107 #[cfg_attr(not(feature = "std"), doc = "```ignore")]
108 /// # use drm_fourcc::DrmFourcc;
109 /// # use std::convert::TryFrom;
110 /// assert_eq!(DrmFourcc::try_from(875710274).unwrap(), DrmFourcc::Bgr888);
111 ///
112 /// assert!(DrmFourcc::try_from(0).is_err());
113 ///
114 /// // If the u32 is in the valid format to be a fourcc, you can see its string form
115 /// assert_eq!(DrmFourcc::try_from(828601953).unwrap_err().string_form(), Some("avc1".to_string()));
116 /// ```
117 fn try_from(value: u32) -> Result<Self, Self::Error> {
118 Self::from_u32(value).ok_or(err:UnrecognizedFourcc(value))
119 }
120}
121
122/// Wraps some u32 that isn't a DRM fourcc we recognize
123///
124#[cfg_attr(feature = "std", doc = "```")]
125#[cfg_attr(not(feature = "std"), doc = "```ignore")]
126/// # use drm_fourcc::{DrmFourcc, UnrecognizedFourcc};
127/// # use std::convert::TryFrom;
128/// // Get the u32
129/// assert_eq!(UnrecognizedFourcc(42).0, 42);
130///
131/// // Get the string form
132/// assert_eq!(UnrecognizedFourcc(828601953).string_form(), Some("avc1".to_string()));
133/// assert_eq!(UnrecognizedFourcc(0).string_form(), None);
134/// ```
135#[derive(Copy, Clone, Eq, PartialEq)]
136#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
137pub struct UnrecognizedFourcc(pub u32);
138
139impl UnrecognizedFourcc {
140 /// If the u32 is in a valid format to be a fourcc, get its string form.
141 ///
142 /// Note that this requires the `std` feature to be enabled. The [`display`] method is an
143 /// alternative that does not require this dependency.
144 #[cfg(feature = "std")]
145 pub fn string_form(&self) -> Option<String> {
146 fourcc_string_form(self.0)
147 }
148
149 /// If the u32 is in a valid format to be a fourcc, get an opaque type to display it.
150 ///
151 /// This can be treated as a slightly generalized form of [`string_form`] that is also
152 /// available when the crate does not depend on the standard or `alloc` crate.
153 ///
154 /// ```
155 /// # use drm_fourcc::UnrecognizedFourcc;
156 /// assert!(UnrecognizedFourcc(828601953).display().is_some());
157 /// assert!(UnrecognizedFourcc(0).display().is_none());
158 /// ```
159 pub fn display(&self) -> Option<impl Display> {
160 fourcc_display_form(self.0)
161 }
162}
163
164impl Debug for UnrecognizedFourcc {
165 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
166 let mut debug: &mut DebugTuple<'_, '_> = &mut f.debug_tuple(name:"UnrecognizedFourcc");
167
168 if let Some(string_form: impl Display + Debug) = fourcc_display_form(self.0) {
169 debug = debug.field(&string_form);
170 }
171
172 debug.field(&self.0).finish()
173 }
174}
175
176impl Display for UnrecognizedFourcc {
177 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
178 Debug::fmt(&self, f)
179 }
180}
181
182#[cfg(feature = "std")]
183impl Error for UnrecognizedFourcc {}
184
185#[cfg(feature = "std")]
186fn fourcc_string_form(fourcc: u32) -> Option<String> {
187 fourcc_display_form(fourcc).map(|val: impl Display + Debug| val.to_string())
188}
189
190fn fourcc_display_form(fourcc: u32) -> Option<impl Display + Debug> {
191 let raw_bytes = fourcc.to_le_bytes();
192 let mut chars = ::core::str::from_utf8(&raw_bytes).ok()?.chars();
193
194 let first = chars.next().unwrap();
195 let second = chars.next().unwrap();
196
197 // first two bytes must be characters
198 for char in [first, second].iter().copied() {
199 if !char.is_ascii_alphanumeric() {
200 return None;
201 }
202 }
203
204 let mut bytes = raw_bytes;
205 // Bytes in tail are allowed to be NUL
206 for byte in &mut bytes[4 - chars.as_str().len()..] {
207 if *byte == b'\0' {
208 *byte = b' ';
209 }
210 }
211
212 /// A pre-formatted string representing a valid FourCC format.
213 ///
214 /// This differs from the byte representation only in that NUL-characters beyond the leading
215 /// two have been replaced by spaces.
216 struct FormatFourccRaw {
217 bytes: [u8; 4],
218 }
219
220 impl Display for FormatFourccRaw {
221 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
222 let chars = ::core::str::from_utf8(&self.bytes[..]).expect("validated previously");
223 f.write_str(chars)
224 }
225 }
226
227 impl Debug for FormatFourccRaw {
228 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
229 Display::fmt(self, f)
230 }
231 }
232
233 Some(FormatFourccRaw { bytes })
234}
235
236impl TryFrom<u8> for DrmVendor {
237 type Error = UnrecognizedVendor;
238
239 /// Convert from an u8
240 ///
241 /// ```
242 /// # use drm_fourcc::DrmVendor;
243 /// # use std::convert::TryFrom;
244 /// assert_eq!(DrmVendor::try_from(2).unwrap(), DrmVendor::Amd);
245 ///
246 /// assert!(DrmVendor::try_from(0).is_err());
247 /// ```
248 fn try_from(value: u8) -> Result<Self, Self::Error> {
249 Self::from_u8(value).ok_or(err:UnrecognizedVendor(value))
250 }
251}
252
253/// Wraps some u8 that isn't a DRM vendor we recognize
254///
255/// ```
256/// # use drm_fourcc::{DrmVendor, UnrecognizedVendor};
257/// # use std::convert::TryFrom;
258/// // Get the u8
259/// assert_eq!(UnrecognizedVendor(42).0, 42);
260/// ```
261#[derive(Debug, Copy, Clone, Eq, PartialEq)]
262#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
263pub struct UnrecognizedVendor(pub u8);
264
265impl Display for UnrecognizedVendor {
266 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
267 Debug::fmt(&self, f)
268 }
269}
270
271#[cfg(feature = "std")]
272impl Error for UnrecognizedVendor {}
273
274impl From<u64> for DrmModifier {
275 /// Convert from an u64
276 ///
277 /// ```
278 /// # use drm_fourcc::DrmModifier;
279 /// assert_eq!(DrmModifier::from(0), DrmModifier::Linear);
280 /// ```
281 fn from(value: u64) -> Self {
282 Self::from_u64(value)
283 }
284}
285
286/// Wraps some u64 that isn't a DRM modifier we recognize
287///
288/// ```
289/// # use drm_fourcc::{DrmModifier, UnrecognizedModifier};
290/// # use std::convert::TryFrom;
291/// // Get the u64
292/// assert_eq!(UnrecognizedModifier(42).0, 42);
293/// ```
294#[derive(Debug, Copy, Clone, Eq, PartialEq)]
295#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
296pub struct UnrecognizedModifier(pub u64);
297
298impl Display for UnrecognizedModifier {
299 fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
300 Debug::fmt(&self, f)
301 }
302}
303
304#[cfg(feature = "std")]
305impl Error for UnrecognizedModifier {}
306
307impl UnrecognizedModifier {
308 /// Get the vendor of the unrecognized modifier, if any
309 ///
310 /// ```
311 /// # use drm_fourcc::{DrmModifier, DrmVendor, UnrecognizedModifier, UnrecognizedVendor};
312 /// assert_eq!(UnrecognizedModifier(216172782113783827).vendor(), Ok(Some(DrmVendor::Nvidia)));
313 /// assert_eq!(UnrecognizedModifier(2).vendor(), Ok(None));
314 /// assert_eq!(UnrecognizedModifier(8646911284551352320).vendor(), Err(UnrecognizedVendor(120)));
315 /// ```
316 pub fn vendor(&self) -> Result<Option<DrmVendor>, UnrecognizedVendor> {
317 let vendor: u8 = (self.0 >> 56) as u8;
318 if vendor == 0 {
319 Ok(None)
320 } else {
321 DrmVendor::try_from(vendor).map(op:Some)
322 }
323 }
324}
325
326impl From<DrmModifier> for u64 {
327 /// Convert to an u64
328 ///
329 /// ```
330 /// # use drm_fourcc::DrmModifier;
331 /// assert_eq!(0u64, DrmModifier::Linear.into());
332 /// ```
333 fn from(val: DrmModifier) -> u64 {
334 val.into_u64()
335 }
336}
337
338impl PartialEq for DrmModifier {
339 fn eq(&self, other: &Self) -> bool {
340 self.into_u64() == other.into_u64()
341 }
342}
343impl Eq for DrmModifier {}
344
345impl PartialEq<u64> for DrmModifier {
346 fn eq(&self, other: &u64) -> bool {
347 &self.into_u64() == other
348 }
349}
350
351impl Hash for DrmModifier {
352 fn hash<H: Hasher>(&self, state: &mut H) {
353 self.into_u64().hash(state);
354 }
355}
356
357impl DrmModifier {
358 /// Get the vendor of the modifier, if any
359 ///
360 /// ```
361 /// # use drm_fourcc::{DrmModifier, DrmVendor, UnrecognizedVendor};
362 /// assert_eq!(DrmModifier::I915_x_tiled.vendor(), Ok(Some(DrmVendor::Intel)));
363 /// assert_eq!(DrmModifier::Linear.vendor(), Ok(None));
364 /// assert_eq!(DrmModifier::Unrecognized(8646911284551352320).vendor(), Err(UnrecognizedVendor(120)));
365 /// ```
366 pub fn vendor(&self) -> Result<Option<DrmVendor>, UnrecognizedVendor> {
367 let vendor: u8 = (self.into_u64() >> 56) as u8;
368 if vendor == 0 {
369 Ok(None)
370 } else {
371 DrmVendor::try_from(vendor).map(op:Some)
372 }
373 }
374}
375
376// Bindgen will always insert `use` statements for these types even though we seriously never use
377// them in normal compilation. Instead, we only use fixed-size types that translate to pure Rust
378// types.
379#[allow(dead_code)]
380pub(crate) mod _fake_ctypes {
381 pub struct c_uchar;
382 pub struct c_uint;
383 pub struct c_ulong;
384}
385
386#[cfg(test)]
387pub mod tests {
388 use super::*;
389
390 #[test]
391 fn a_specific_var_has_correct_value() {
392 assert_eq!(consts::DRM_FOURCC_AYUV, 1448433985);
393 }
394
395 #[test]
396 fn enum_member_casts_to_const() {
397 assert_eq!(
398 DrmFourcc::Xrgb8888 as u32,
399 consts::DRM_FOURCC_XRGB8888 as u32
400 );
401 }
402
403 #[test]
404 #[cfg(feature = "std")]
405 fn enum_member_has_correct_string_format() {
406 assert_eq!(DrmFourcc::Xrgb8888.to_string(), "XR24");
407 }
408
409 #[test]
410 #[cfg(feature = "std")]
411 fn fourcc_string_form_handles_valid() {
412 assert_eq!(fourcc_string_form(875713112).unwrap(), "XR24");
413 assert_eq!(fourcc_string_form(828601953).unwrap(), "avc1");
414 assert_eq!(fourcc_string_form(0x316376).unwrap(), "vc1 ");
415 }
416
417 #[test]
418 #[cfg(feature = "std")]
419 fn unrecognized_handles_valid_fourcc() {
420 assert_eq!(
421 UnrecognizedFourcc(828601953).to_string(),
422 "UnrecognizedFourcc(avc1, 828601953)"
423 );
424 }
425
426 #[test]
427 #[cfg(feature = "std")]
428 fn unrecognized_handles_invalid_fourcc() {
429 assert_eq!(UnrecognizedFourcc(0).to_string(), "UnrecognizedFourcc(0)");
430 }
431
432 #[test]
433 fn can_clone_result() {
434 let a = DrmFourcc::try_from(0);
435 let b = a;
436 assert_eq!(a, b);
437 }
438}
439