dithr 0.3.0

Buffer-first rust dithering and halftoning library.
Documentation 
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
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

pub trait PixelLayout: Copy + Send + Sync + 'static {
    const CHANNELS: usize;
    const COLOR_CHANNELS: usize;
    const HAS_ALPHA: bool;
    const IS_GRAY: bool;
}

pub(crate) fn validate_layout_invariants<L: PixelLayout>() -> crate::Result<()> {
    if L::CHANNELS == 0 {
        return Err(crate::Error::UnsupportedFormat(
            "pixel layout must define at least one channel",
        ));
    }

    if L::COLOR_CHANNELS == 0 {
        return Err(crate::Error::UnsupportedFormat(
            "pixel layout must define at least one color channel",
        ));
    }

    if L::COLOR_CHANNELS > L::CHANNELS {
        return Err(crate::Error::UnsupportedFormat(
            "pixel layout color channels cannot exceed total channels",
        ));
    }

    if L::HAS_ALPHA && L::COLOR_CHANNELS == L::CHANNELS {
        return Err(crate::Error::UnsupportedFormat(
            "alpha pixel layouts must reserve a non-color channel",
        ));
    }

    if L::IS_GRAY {
        if L::COLOR_CHANNELS != 1 {
            return Err(crate::Error::UnsupportedFormat(
                "gray pixel layouts must use exactly one color channel",
            ));
        }
        if L::HAS_ALPHA {
            return Err(crate::Error::UnsupportedFormat(
                "gray pixel layouts with alpha are not supported",
            ));
        }
    } else if L::COLOR_CHANNELS < 3 {
        return Err(crate::Error::UnsupportedFormat(
            "color pixel layouts must define at least three color channels",
        ));
    }

    Ok(())
}

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct Gray;

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct Rgb;

#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct Rgba;

impl PixelLayout for Gray {
    const CHANNELS: usize = 1;
    const COLOR_CHANNELS: usize = 1;
    const HAS_ALPHA: bool = false;
    const IS_GRAY: bool = true;
}

impl PixelLayout for Rgb {
    const CHANNELS: usize = 3;
    const COLOR_CHANNELS: usize = 3;
    const HAS_ALPHA: bool = false;
    const IS_GRAY: bool = false;
}

impl PixelLayout for Rgba {
    const CHANNELS: usize = 4;
    const COLOR_CHANNELS: usize = 3;
    const HAS_ALPHA: bool = true;
    const IS_GRAY: bool = false;
}

#[cfg(test)]
mod tests {
    use super::{validate_layout_invariants, Gray, PixelLayout, Rgb, Rgba};
    use crate::Error;

    #[test]
    fn layout_constants_match_expected() {
        assert_eq!(Gray::CHANNELS, 1);
        assert_eq!(Gray::COLOR_CHANNELS, 1);
        assert!(!std::hint::black_box(Gray::HAS_ALPHA));
        assert!(std::hint::black_box(Gray::IS_GRAY));

        assert_eq!(Rgb::CHANNELS, 3);
        assert_eq!(Rgb::COLOR_CHANNELS, 3);
        assert!(!std::hint::black_box(Rgb::HAS_ALPHA));
        assert!(!std::hint::black_box(Rgb::IS_GRAY));

        assert_eq!(Rgba::CHANNELS, 4);
        assert_eq!(Rgba::COLOR_CHANNELS, 3);
        assert!(std::hint::black_box(Rgba::HAS_ALPHA));
        assert!(!std::hint::black_box(Rgba::IS_GRAY));
    }

    #[derive(Clone, Copy)]
    struct InvalidZeroChannels;

    impl PixelLayout for InvalidZeroChannels {
        const CHANNELS: usize = 0;
        const COLOR_CHANNELS: usize = 1;
        const HAS_ALPHA: bool = false;
        const IS_GRAY: bool = true;
    }

    #[derive(Clone, Copy)]
    struct InvalidColorOverflow;

    impl PixelLayout for InvalidColorOverflow {
        const CHANNELS: usize = 3;
        const COLOR_CHANNELS: usize = 4;
        const HAS_ALPHA: bool = false;
        const IS_GRAY: bool = false;
    }

    #[test]
    fn validate_layout_invariants_accepts_builtin_layouts() {
        assert_eq!(validate_layout_invariants::<Gray>(), Ok(()));
        assert_eq!(validate_layout_invariants::<Rgb>(), Ok(()));
        assert_eq!(validate_layout_invariants::<Rgba>(), Ok(()));
    }

    #[test]
    fn validate_layout_invariants_rejects_zero_channels() {
        assert_eq!(
            validate_layout_invariants::<InvalidZeroChannels>(),
            Err(Error::UnsupportedFormat(
                "pixel layout must define at least one channel"
            ))
        );
    }

    #[test]
    fn validate_layout_invariants_rejects_color_overflow() {
        assert_eq!(
            validate_layout_invariants::<InvalidColorOverflow>(),
            Err(Error::UnsupportedFormat(
                "pixel layout color channels cannot exceed total channels"
            ))
        );
    }
}