Skip to main content

oiio/
pixel_format.rs

1use crate::sys::{self, typedesc::BaseType};
2
3/// The scalar type of one channel value.
4///
5/// This describes what a file stores or what a writer should produce. It is
6/// deliberately wider than the [`Pixel`](crate::Pixel) trait: OpenImageIO can
7/// report formats such as [`PixelFormat::U32`] that the contiguous buffer API
8/// does not read or write.
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
10#[non_exhaustive]
11pub enum PixelFormat {
12    /// Unsigned 8-bit, the usual format for PNG, JPEG and TGA.
13    U8,
14    /// Signed 8-bit.
15    I8,
16    /// Unsigned 16-bit, common in TIFF and PNG.
17    U16,
18    /// Signed 16-bit.
19    I16,
20    /// Unsigned 32-bit.
21    U32,
22    /// Signed 32-bit.
23    I32,
24    /// Unsigned 64-bit.
25    U64,
26    /// Signed 64-bit.
27    I64,
28    /// IEEE 754 binary16, matching [`half::f16`], and what most EXRs hold.
29    F16,
30    /// IEEE 754 binary32.
31    F32,
32    /// IEEE 754 binary64.
33    F64,
34    /// A format this crate does not model, including OpenImageIO's `UNKNOWN`.
35    Other,
36}
37
38impl PixelFormat {
39    /// Size of one channel value in bytes, when the format has a fixed size.
40    pub fn byte_size(self) -> Option<usize> {
41        Some(match self {
42            Self::U8 | Self::I8 => 1,
43            Self::U16 | Self::I16 | Self::F16 => 2,
44            Self::U32 | Self::I32 | Self::F32 => 4,
45            Self::U64 | Self::I64 | Self::F64 => 8,
46            Self::Other => return None,
47        })
48    }
49
50    /// Whether the contiguous [`Pixel`](crate::Pixel) API can read and write
51    /// buffers of this format without conversion.
52    pub fn is_supported_buffer_format(self) -> bool {
53        matches!(self, Self::U8 | Self::U16 | Self::F16 | Self::F32)
54    }
55
56    pub(crate) fn base_type(self) -> BaseType {
57        match self {
58            Self::U8 => BaseType::UInt8,
59            Self::I8 => BaseType::Int8,
60            Self::U16 => BaseType::Uint16,
61            Self::I16 => BaseType::Int16,
62            Self::U32 => BaseType::UInt32,
63            Self::I32 => BaseType::Int32,
64            Self::U64 => BaseType::UInt64,
65            Self::I64 => BaseType::Int64,
66            Self::F16 => BaseType::Float16,
67            Self::F32 => BaseType::Float32,
68            Self::F64 => BaseType::Float64,
69            Self::Other => BaseType::Unknown,
70        }
71    }
72
73    pub(crate) fn to_sys(self) -> sys::typedesc::TypeDesc {
74        sys::typedesc::typedesc_from_basetype_arraylen(self.base_type(), 0)
75    }
76
77    pub(crate) fn from_sys(type_desc: &sys::typedesc::TypeDesc) -> Self {
78        // Aggregates and arrays are never plain pixel formats.
79        if type_desc.arraylen != 0 || type_desc.aggregate != sys::typedesc::Aggregate::Scalar as u8
80        {
81            return Self::Other;
82        }
83        Self::from_base_type(type_desc.basetype)
84    }
85
86    fn from_base_type(basetype: u8) -> Self {
87        match basetype {
88            b if b == BaseType::UInt8 as u8 => Self::U8,
89            b if b == BaseType::Int8 as u8 => Self::I8,
90            b if b == BaseType::Uint16 as u8 => Self::U16,
91            b if b == BaseType::Int16 as u8 => Self::I16,
92            b if b == BaseType::UInt32 as u8 => Self::U32,
93            b if b == BaseType::Int32 as u8 => Self::I32,
94            b if b == BaseType::UInt64 as u8 => Self::U64,
95            b if b == BaseType::Int64 as u8 => Self::I64,
96            b if b == BaseType::Float16 as u8 => Self::F16,
97            b if b == BaseType::Float32 as u8 => Self::F32,
98            b if b == BaseType::Float64 as u8 => Self::F64,
99            _ => Self::Other,
100        }
101    }
102}
103
104#[cfg(test)]
105mod tests {
106    use super::*;
107
108    #[test]
109    fn round_trips_through_openimageio_type_descriptors() {
110        let formats = [
111            PixelFormat::U8,
112            PixelFormat::I8,
113            PixelFormat::U16,
114            PixelFormat::I16,
115            PixelFormat::U32,
116            PixelFormat::I32,
117            PixelFormat::U64,
118            PixelFormat::I64,
119            PixelFormat::F16,
120            PixelFormat::F32,
121            PixelFormat::F64,
122        ];
123        for format in formats {
124            assert_eq!(PixelFormat::from_sys(&format.to_sys()), format);
125        }
126    }
127
128    #[test]
129    fn reports_openimageio_sizes() {
130        for format in [PixelFormat::U8, PixelFormat::F16, PixelFormat::F32] {
131            let expected = sys::typedesc::typedesc_size(&format.to_sys());
132            assert_eq!(format.byte_size(), Some(expected));
133        }
134        assert_eq!(PixelFormat::Other.byte_size(), None);
135    }
136
137    #[test]
138    fn treats_aggregates_and_arrays_as_other() {
139        let matrix = sys::typedesc::typedesc_from_basetype_aggregate_arraylen(
140            BaseType::Float32,
141            sys::typedesc::Aggregate::Matrix44,
142            0,
143        );
144        assert_eq!(PixelFormat::from_sys(&matrix), PixelFormat::Other);
145
146        let array = sys::typedesc::typedesc_from_basetype_arraylen(BaseType::Float32, 4);
147        assert_eq!(PixelFormat::from_sys(&array), PixelFormat::Other);
148    }
149
150    #[test]
151    fn names_match_openimageio() {
152        for format in [
153            PixelFormat::U8,
154            PixelFormat::U16,
155            PixelFormat::F16,
156            PixelFormat::F32,
157            PixelFormat::F64,
158        ] {
159            let type_desc = format.to_sys();
160            assert_eq!(sys::typedesc::typedesc_to_str(&type_desc), format.name());
161        }
162    }
163}
164
165enum_names!("pixel format", PixelFormat {
166    U8 => "uint8",
167    I8 => "int8",
168    U16 => "uint16",
169    I16 => "int16",
170    U32 => "uint32",
171    I32 => "int32",
172    U64 => "uint64",
173    I64 => "int64",
174    F16 => "half",
175    F32 => "float",
176    F64 => "double",
177    Other => "unknown",
178});