1//! This module provides useful traits that were deprecated in rust
2
3// Note copied from the stdlib under MIT license
4
5use num_traits::{Bounded, Num, NumCast};
6use std::ops::AddAssign;
7
8use crate::color::{Luma, LumaA, Rgb, Rgba};
9use crate::ExtendedColorType;
10
11/// Types which are safe to treat as an immutable byte slice in a pixel layout
12/// for image encoding.
13pub trait EncodableLayout: seals::EncodableLayout {
14 /// Get the bytes of this value.
15 fn as_bytes(&self) -> &[u8];
16}
17
18impl EncodableLayout for [u8] {
19 fn as_bytes(&self) -> &[u8] {
20 bytemuck::cast_slice(self)
21 }
22}
23
24impl EncodableLayout for [u16] {
25 fn as_bytes(&self) -> &[u8] {
26 bytemuck::cast_slice(self)
27 }
28}
29
30impl EncodableLayout for [f32] {
31 fn as_bytes(&self) -> &[u8] {
32 bytemuck::cast_slice(self)
33 }
34}
35
36/// The type of each channel in a pixel. For example, this can be `u8`, `u16`, `f32`.
37// TODO rename to `PixelComponent`? Split up into separate traits? Seal?
38pub trait Primitive: Copy + NumCast + Num + PartialOrd<Self> + Clone + Bounded {
39 /// The maximum value for this type of primitive within the context of color.
40 /// For floats, the maximum is `1.0`, whereas the integer types inherit their usual maximum values.
41 const DEFAULT_MAX_VALUE: Self;
42
43 /// The minimum value for this type of primitive within the context of color.
44 /// For floats, the minimum is `0.0`, whereas the integer types inherit their usual minimum values.
45 const DEFAULT_MIN_VALUE: Self;
46}
47
48macro_rules! declare_primitive {
49 ($base:ty: ($from:expr)..$to:expr) => {
50 impl Primitive for $base {
51 const DEFAULT_MAX_VALUE: Self = $to;
52 const DEFAULT_MIN_VALUE: Self = $from;
53 }
54 };
55}
56
57declare_primitive!(usize: (0)..Self::MAX);
58declare_primitive!(u8: (0)..Self::MAX);
59declare_primitive!(u16: (0)..Self::MAX);
60declare_primitive!(u32: (0)..Self::MAX);
61declare_primitive!(u64: (0)..Self::MAX);
62
63declare_primitive!(isize: (Self::MIN)..Self::MAX);
64declare_primitive!(i8: (Self::MIN)..Self::MAX);
65declare_primitive!(i16: (Self::MIN)..Self::MAX);
66declare_primitive!(i32: (Self::MIN)..Self::MAX);
67declare_primitive!(i64: (Self::MIN)..Self::MAX);
68declare_primitive!(f32: (0.0)..1.0);
69declare_primitive!(f64: (0.0)..1.0);
70
71/// An `Enlargable::Larger` value should be enough to calculate
72/// the sum (average) of a few hundred or thousand Enlargeable values.
73pub trait Enlargeable: Sized + Bounded + NumCast {
74 type Larger: Copy + NumCast + Num + PartialOrd<Self::Larger> + Clone + Bounded + AddAssign;
75
76 fn clamp_from(n: Self::Larger) -> Self {
77 if n > Self::max_value().to_larger() {
78 Self::max_value()
79 } else if n < Self::min_value().to_larger() {
80 Self::min_value()
81 } else {
82 NumCast::from(n).unwrap()
83 }
84 }
85
86 fn to_larger(self) -> Self::Larger {
87 NumCast::from(self).unwrap()
88 }
89}
90
91impl Enlargeable for u8 {
92 type Larger = u32;
93}
94impl Enlargeable for u16 {
95 type Larger = u32;
96}
97impl Enlargeable for u32 {
98 type Larger = u64;
99}
100impl Enlargeable for u64 {
101 type Larger = u128;
102}
103impl Enlargeable for usize {
104 // Note: On 32-bit architectures, u64 should be enough here.
105 type Larger = u128;
106}
107impl Enlargeable for i8 {
108 type Larger = i32;
109}
110impl Enlargeable for i16 {
111 type Larger = i32;
112}
113impl Enlargeable for i32 {
114 type Larger = i64;
115}
116impl Enlargeable for i64 {
117 type Larger = i128;
118}
119impl Enlargeable for isize {
120 // Note: On 32-bit architectures, i64 should be enough here.
121 type Larger = i128;
122}
123impl Enlargeable for f32 {
124 type Larger = f64;
125}
126impl Enlargeable for f64 {
127 type Larger = f64;
128}
129
130/// Linear interpolation without involving floating numbers.
131pub trait Lerp: Bounded + NumCast {
132 type Ratio: Primitive;
133
134 fn lerp(a: Self, b: Self, ratio: Self::Ratio) -> Self {
135 let a: ::Ratio = <Self::Ratio as NumCast>::from(a).unwrap();
136 let b: ::Ratio = <Self::Ratio as NumCast>::from(b).unwrap();
137
138 let res: ::Ratio = a + (b - a) * ratio;
139
140 if res > NumCast::from(Self::max_value()).unwrap() {
141 Self::max_value()
142 } else if res < NumCast::from(0).unwrap() {
143 NumCast::from(0).unwrap()
144 } else {
145 NumCast::from(res).unwrap()
146 }
147 }
148}
149
150impl Lerp for u8 {
151 type Ratio = f32;
152}
153
154impl Lerp for u16 {
155 type Ratio = f32;
156}
157
158impl Lerp for u32 {
159 type Ratio = f64;
160}
161
162impl Lerp for f32 {
163 type Ratio = f32;
164
165 fn lerp(a: Self, b: Self, ratio: Self::Ratio) -> Self {
166 a + (b - a) * ratio
167 }
168}
169
170/// The pixel with an associated `ColorType`.
171/// Not all possible pixels represent one of the predefined `ColorType`s.
172pub trait PixelWithColorType: Pixel + private::SealedPixelWithColorType {
173 /// This pixel has the format of one of the predefined `ColorType`s,
174 /// such as `Rgb8`, `La16` or `Rgba32F`.
175 /// This is needed for automatically detecting
176 /// a color format when saving an image as a file.
177 const COLOR_TYPE: ExtendedColorType;
178}
179
180impl PixelWithColorType for Rgb<u8> {
181 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgb8;
182}
183impl PixelWithColorType for Rgb<u16> {
184 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgb16;
185}
186impl PixelWithColorType for Rgb<f32> {
187 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgb32F;
188}
189
190impl PixelWithColorType for Rgba<u8> {
191 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgba8;
192}
193impl PixelWithColorType for Rgba<u16> {
194 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgba16;
195}
196impl PixelWithColorType for Rgba<f32> {
197 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgba32F;
198}
199
200impl PixelWithColorType for Luma<u8> {
201 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::L8;
202}
203impl PixelWithColorType for Luma<u16> {
204 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::L16;
205}
206impl PixelWithColorType for LumaA<u8> {
207 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::La8;
208}
209impl PixelWithColorType for LumaA<u16> {
210 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::La16;
211}
212
213/// Prevents down-stream users from implementing the `Primitive` trait
214mod private {
215 use crate::color::*;
216
217 pub trait SealedPixelWithColorType {}
218 impl SealedPixelWithColorType for Rgb<u8> {}
219 impl SealedPixelWithColorType for Rgb<u16> {}
220 impl SealedPixelWithColorType for Rgb<f32> {}
221
222 impl SealedPixelWithColorType for Rgba<u8> {}
223 impl SealedPixelWithColorType for Rgba<u16> {}
224 impl SealedPixelWithColorType for Rgba<f32> {}
225
226 impl SealedPixelWithColorType for Luma<u8> {}
227 impl SealedPixelWithColorType for LumaA<u8> {}
228
229 impl SealedPixelWithColorType for Luma<u16> {}
230 impl SealedPixelWithColorType for LumaA<u16> {}
231}
232
233/// A generalized pixel.
234///
235/// A pixel object is usually not used standalone but as a view into an image buffer.
236pub trait Pixel: Copy + Clone {
237 /// The scalar type that is used to store each channel in this pixel.
238 type Subpixel: Primitive;
239
240 /// The number of channels of this pixel type.
241 const CHANNEL_COUNT: u8;
242
243 /// Returns the components as a slice.
244 fn channels(&self) -> &[Self::Subpixel];
245
246 /// Returns the components as a mutable slice
247 fn channels_mut(&mut self) -> &mut [Self::Subpixel];
248
249 /// A string that can help to interpret the meaning each channel
250 /// See [gimp babl](http://gegl.org/babl/).
251 const COLOR_MODEL: &'static str;
252
253 /// Returns the channels of this pixel as a 4 tuple. If the pixel
254 /// has less than 4 channels the remainder is filled with the maximum value
255 #[deprecated(since = "0.24.0", note = "Use `channels()` or `channels_mut()`")]
256 fn channels4(
257 &self,
258 ) -> (
259 Self::Subpixel,
260 Self::Subpixel,
261 Self::Subpixel,
262 Self::Subpixel,
263 );
264
265 /// Construct a pixel from the 4 channels a, b, c and d.
266 /// If the pixel does not contain 4 channels the extra are ignored.
267 #[deprecated(
268 since = "0.24.0",
269 note = "Use the constructor of the pixel, for example `Rgba([r,g,b,a])` or `Pixel::from_slice`"
270 )]
271 fn from_channels(
272 a: Self::Subpixel,
273 b: Self::Subpixel,
274 c: Self::Subpixel,
275 d: Self::Subpixel,
276 ) -> Self;
277
278 /// Returns a view into a slice.
279 ///
280 /// Note: The slice length is not checked on creation. Thus the caller has to ensure
281 /// that the slice is long enough to prevent panics if the pixel is used later on.
282 fn from_slice(slice: &[Self::Subpixel]) -> &Self;
283
284 /// Returns mutable view into a mutable slice.
285 ///
286 /// Note: The slice length is not checked on creation. Thus the caller has to ensure
287 /// that the slice is long enough to prevent panics if the pixel is used later on.
288 fn from_slice_mut(slice: &mut [Self::Subpixel]) -> &mut Self;
289
290 /// Convert this pixel to RGB
291 fn to_rgb(&self) -> Rgb<Self::Subpixel>;
292
293 /// Convert this pixel to RGB with an alpha channel
294 fn to_rgba(&self) -> Rgba<Self::Subpixel>;
295
296 /// Convert this pixel to luma
297 fn to_luma(&self) -> Luma<Self::Subpixel>;
298
299 /// Convert this pixel to luma with an alpha channel
300 fn to_luma_alpha(&self) -> LumaA<Self::Subpixel>;
301
302 /// Apply the function ```f``` to each channel of this pixel.
303 fn map<F>(&self, f: F) -> Self
304 where
305 F: FnMut(Self::Subpixel) -> Self::Subpixel;
306
307 /// Apply the function ```f``` to each channel of this pixel.
308 fn apply<F>(&mut self, f: F)
309 where
310 F: FnMut(Self::Subpixel) -> Self::Subpixel;
311
312 /// Apply the function ```f``` to each channel except the alpha channel.
313 /// Apply the function ```g``` to the alpha channel.
314 fn map_with_alpha<F, G>(&self, f: F, g: G) -> Self
315 where
316 F: FnMut(Self::Subpixel) -> Self::Subpixel,
317 G: FnMut(Self::Subpixel) -> Self::Subpixel;
318
319 /// Apply the function ```f``` to each channel except the alpha channel.
320 /// Apply the function ```g``` to the alpha channel. Works in-place.
321 fn apply_with_alpha<F, G>(&mut self, f: F, g: G)
322 where
323 F: FnMut(Self::Subpixel) -> Self::Subpixel,
324 G: FnMut(Self::Subpixel) -> Self::Subpixel;
325
326 /// Apply the function ```f``` to each channel except the alpha channel.
327 fn map_without_alpha<F>(&self, f: F) -> Self
328 where
329 F: FnMut(Self::Subpixel) -> Self::Subpixel,
330 {
331 let mut this = *self;
332 this.apply_with_alpha(f, |x| x);
333 this
334 }
335
336 /// Apply the function ```f``` to each channel except the alpha channel.
337 /// Works in place.
338 fn apply_without_alpha<F>(&mut self, f: F)
339 where
340 F: FnMut(Self::Subpixel) -> Self::Subpixel,
341 {
342 self.apply_with_alpha(f, |x| x);
343 }
344
345 /// Apply the function ```f``` to each channel of this pixel and
346 /// ```other``` pairwise.
347 fn map2<F>(&self, other: &Self, f: F) -> Self
348 where
349 F: FnMut(Self::Subpixel, Self::Subpixel) -> Self::Subpixel;
350
351 /// Apply the function ```f``` to each channel of this pixel and
352 /// ```other``` pairwise. Works in-place.
353 fn apply2<F>(&mut self, other: &Self, f: F)
354 where
355 F: FnMut(Self::Subpixel, Self::Subpixel) -> Self::Subpixel;
356
357 /// Invert this pixel
358 fn invert(&mut self);
359
360 /// Blend the color of a given pixel into ourself, taking into account alpha channels
361 fn blend(&mut self, other: &Self);
362}
363
364/// Private module for supertraits of sealed traits.
365mod seals {
366 pub trait EncodableLayout {}
367
368 impl EncodableLayout for [u8] {}
369 impl EncodableLayout for [u16] {}
370 impl EncodableLayout for [f32] {}
371}
372