Debian Codegraph @

.cargo/vendor/image/src/traits.rs

raw
1 //! This module provides useful traits that were deprecated in rust
2
3 // Note copied from the stdlib under MIT license
4
5 use num_traits::{Bounded, Num, NumCast};
6 use std::ops::AddAssign;
7
8 use crate::color::{Luma, LumaA, Rgb, Rgba};
9 use crate::ExtendedColorType;
10
11 /// Types which are safe to treat as an immutable byte slice in a pixel layout
12 /// for image encoding.
13 pub trait EncodableLayout: seals::EncodableLayout {
14 /// Get the bytes of this value.
15 fn as_bytes(&self) -> &[u8];
16 }
17
18 impl EncodableLayout for [u8] {
19 fn as_bytes(&self) -> &[u8] {
20 bytemuck::cast_slice(self)
21 }
22 }
23
24 impl EncodableLayout for [u16] {
25 fn as_bytes(&self) -> &[u8] {
26 bytemuck::cast_slice(self)
27 }
28 }
29
30 impl 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?
38 pub 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
48 macro_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
57 declare_primitive!(usize: (0)..Self::MAX);
58 declare_primitive!(u8: (0)..Self::MAX);
59 declare_primitive!(u16: (0)..Self::MAX);
60 declare_primitive!(u32: (0)..Self::MAX);
61 declare_primitive!(u64: (0)..Self::MAX);
62
63 declare_primitive!(isize: (Self::MIN)..Self::MAX);
64 declare_primitive!(i8: (Self::MIN)..Self::MAX);
65 declare_primitive!(i16: (Self::MIN)..Self::MAX);
66 declare_primitive!(i32: (Self::MIN)..Self::MAX);
67 declare_primitive!(i64: (Self::MIN)..Self::MAX);
68 declare_primitive!(f32: (0.0)..1.0);
69 declare_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.
73 pub 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
91 impl Enlargeable for u8 {
92 type Larger = u32;
93 }
94 impl Enlargeable for u16 {
95 type Larger = u32;
96 }
97 impl Enlargeable for u32 {
98 type Larger = u64;
99 }
100 impl Enlargeable for u64 {
101 type Larger = u128;
102 }
103 impl Enlargeable for usize {
104 // Note: On 32-bit architectures, u64 should be enough here.
105 type Larger = u128;
106 }
107 impl Enlargeable for i8 {
108 type Larger = i32;
109 }
110 impl Enlargeable for i16 {
111 type Larger = i32;
112 }
113 impl Enlargeable for i32 {
114 type Larger = i64;
115 }
116 impl Enlargeable for i64 {
117 type Larger = i128;
118 }
119 impl Enlargeable for isize {
120 // Note: On 32-bit architectures, i64 should be enough here.
121 type Larger = i128;
122 }
123 impl Enlargeable for f32 {
124 type Larger = f64;
125 }
126 impl Enlargeable for f64 {
127 type Larger = f64;
128 }
129
130 /// Linear interpolation without involving floating numbers.
131 pub trait Lerp: Bounded + NumCast {
132 type Ratio: Primitive;
133
134 fn lerp(a: Self, b: Self, ratio: Self::Ratio) -> Self {
135 let a = <Self::Ratio as NumCast>::from(a).unwrap();
136 let b = <Self::Ratio as NumCast>::from(b).unwrap();
137
138 let res = 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
150 impl Lerp for u8 {
151 type Ratio = f32;
152 }
153
154 impl Lerp for u16 {
155 type Ratio = f32;
156 }
157
158 impl Lerp for u32 {
159 type Ratio = f64;
160 }
161
162 impl 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.
172 pub trait PixelWithColorType:
173 Pixel + private::SealedPixelWithColorType<TransformableSubpixel = <Self as Pixel>::Subpixel>
174 {
175 /// This pixel has the format of one of the predefined `ColorType`s,
176 /// such as `Rgb8`, `La16` or `Rgba32F`.
177 /// This is needed for automatically detecting
178 /// a color format when saving an image as a file.
179 const COLOR_TYPE: ExtendedColorType;
180 }
181
182 impl PixelWithColorType for Rgb<u8> {
183 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgb8;
184 }
185 impl PixelWithColorType for Rgb<u16> {
186 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgb16;
187 }
188 impl PixelWithColorType for Rgb<f32> {
189 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgb32F;
190 }
191
192 impl PixelWithColorType for Rgba<u8> {
193 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgba8;
194 }
195 impl PixelWithColorType for Rgba<u16> {
196 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgba16;
197 }
198 impl PixelWithColorType for Rgba<f32> {
199 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::Rgba32F;
200 }
201
202 impl PixelWithColorType for Luma<u8> {
203 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::L8;
204 }
205 impl PixelWithColorType for Luma<u16> {
206 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::L16;
207 }
208 impl PixelWithColorType for LumaA<u8> {
209 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::La8;
210 }
211 impl PixelWithColorType for LumaA<u16> {
212 const COLOR_TYPE: ExtendedColorType = ExtendedColorType::La16;
213 }
214
215 /// Prevents down-stream users from implementing the `Primitive` trait
216 pub(crate) mod private {
217 use crate::color::*;
218 use crate::metadata::cicp::{self, CicpApplicable};
219
220 #[derive(Clone, Copy, Debug)]
221 pub enum LayoutWithColor {
222 Rgb,
223 Rgba,
224 Luma,
225 LumaAlpha,
226 }
227
228 impl From<ColorType> for LayoutWithColor {
229 fn from(color: ColorType) -> LayoutWithColor {
230 match color {
231 ColorType::L8 | ColorType::L16 => LayoutWithColor::Luma,
232 ColorType::La8 | ColorType::La16 => LayoutWithColor::LumaAlpha,
233 ColorType::Rgb8 | ColorType::Rgb16 | ColorType::Rgb32F => LayoutWithColor::Rgb,
234 ColorType::Rgba8 | ColorType::Rgba16 | ColorType::Rgba32F => LayoutWithColor::Rgba,
235 }
236 }
237 }
238
239 impl LayoutWithColor {
240 pub(crate) fn channels(self) -> usize {
241 match self {
242 Self::Rgb => 3,
243 Self::Rgba => 4,
244 Self::Luma => 1,
245 Self::LumaAlpha => 2,
246 }
247 }
248 }
249
250 #[derive(Clone, Copy)]
251 pub struct PrivateToken;
252
253 pub trait SealedPixelWithColorType {
254 #[expect(private_bounds)] // This is a sealed trait.
255 type TransformableSubpixel: HelpDispatchTransform;
256 fn layout(_: PrivateToken) -> LayoutWithColor;
257 }
258
259 impl SealedPixelWithColorType for Rgb<u8> {
260 type TransformableSubpixel = u8;
261 fn layout(_: PrivateToken) -> LayoutWithColor {
262 LayoutWithColor::Rgb
263 }
264 }
265
266 impl SealedPixelWithColorType for Rgb<u16> {
267 type TransformableSubpixel = u16;
268 fn layout(_: PrivateToken) -> LayoutWithColor {
269 LayoutWithColor::Rgb
270 }
271 }
272
273 impl SealedPixelWithColorType for Rgb<f32> {
274 type TransformableSubpixel = f32;
275 fn layout(_: PrivateToken) -> LayoutWithColor {
276 LayoutWithColor::Rgb
277 }
278 }
279
280 impl SealedPixelWithColorType for Rgba<u8> {
281 type TransformableSubpixel = u8;
282 fn layout(_: PrivateToken) -> LayoutWithColor {
283 LayoutWithColor::Rgba
284 }
285 }
286
287 impl SealedPixelWithColorType for Rgba<u16> {
288 type TransformableSubpixel = u16;
289 fn layout(_: PrivateToken) -> LayoutWithColor {
290 LayoutWithColor::Rgba
291 }
292 }
293
294 impl SealedPixelWithColorType for Rgba<f32> {
295 type TransformableSubpixel = f32;
296 fn layout(_: PrivateToken) -> LayoutWithColor {
297 LayoutWithColor::Rgba
298 }
299 }
300
301 impl SealedPixelWithColorType for Luma<u8> {
302 type TransformableSubpixel = u8;
303 fn layout(_: PrivateToken) -> LayoutWithColor {
304 LayoutWithColor::Luma
305 }
306 }
307
308 impl SealedPixelWithColorType for LumaA<u8> {
309 type TransformableSubpixel = u8;
310 fn layout(_: PrivateToken) -> LayoutWithColor {
311 LayoutWithColor::LumaAlpha
312 }
313 }
314
315 impl SealedPixelWithColorType for Luma<u16> {
316 type TransformableSubpixel = u16;
317 fn layout(_: PrivateToken) -> LayoutWithColor {
318 LayoutWithColor::Luma
319 }
320 }
321
322 impl SealedPixelWithColorType for Luma<f32> {
323 type TransformableSubpixel = f32;
324 fn layout(_: PrivateToken) -> LayoutWithColor {
325 LayoutWithColor::Luma
326 }
327 }
328
329 impl SealedPixelWithColorType for LumaA<u16> {
330 type TransformableSubpixel = u16;
331 fn layout(_: PrivateToken) -> LayoutWithColor {
332 LayoutWithColor::LumaAlpha
333 }
334 }
335
336 impl SealedPixelWithColorType for LumaA<f32> {
337 type TransformableSubpixel = f32;
338 fn layout(_: PrivateToken) -> LayoutWithColor {
339 LayoutWithColor::LumaAlpha
340 }
341 }
342
343 // Consider a situation in a function bounded `Self: Pixel + PixelWithColorType`. Then, if we
344 // tried this directly:
345 //
346 // <
347 // <Self as SealedPixelWithColorType>::TransformableSubpixel as HelpDispatchTransform
348 // >::transform_on::<Self>(tr, LayoutWithColor::Rgb);
349 //
350 // the type checker is mightily confused. I think what's going on is as follows: It find the
351 // fact that `Self::Subpixel` is used for `TransformableSubpixel` from the bound on
352 // `PixelWithColorType`, but then there is no existing bound on `Subpixel` that would guarantee
353 // that `HelpDispatchTransform` is fulfilled. That would only be available by substituting
354 // _back_ so that the bound on `TransformableSubpixel` gets applied to the `Subpixel` generic,
355 // too. But now there are no variables here, so unification of bounds takes place we never
356 // never get to see the bound (until next gen, I guess?). It finally find that there is still
357 // an unfulfilled bound and complains.
358 //
359 // Hence we must avoid mentioning the `Pixel` and `PixelWithColorType` bound so that _only_ the
360 // `TransformableSubpixel` is available. Then all substitutions work forwards, and since we
361 // return a `TransformableSubpixel` we get the function back without new variables to solve
362 // for, and that can then be unified just fine. This extra function essentially introduces that
363 // missing unknown which can unify the available impl set. Yay.
364 pub(crate) fn dispatch_transform_from_sealed<P: SealedPixelWithColorType>(
365 transform: &cicp::CicpTransform,
366 into: LayoutWithColor,
367 ) -> &'_ CicpApplicable<'_, P::TransformableSubpixel> {
368 <P::TransformableSubpixel as HelpDispatchTransform>::transform_on::<P>(transform, into)
369 }
370
371 pub(crate) fn double_dispatch_transform_from_sealed<
372 P: SealedPixelWithColorType,
373 Into: SealedPixelWithColorType,
374 >(
375 transform: &cicp::CicpTransform,
376 ) -> &'_ CicpApplicable<'_, P::TransformableSubpixel> {
377 dispatch_transform_from_sealed::<P>(transform, Into::layout(PrivateToken))
378 }
379
380 pub(crate) trait HelpDispatchTransform: Sized + 'static {
381 fn transform_on<O: SealedPixelWithColorType<TransformableSubpixel = Self>>(
382 transform: &cicp::CicpTransform,
383 into: LayoutWithColor,
384 ) -> &'_ (dyn Fn(&[Self], &mut [Self]) + Send + Sync);
385 }
386
387 impl HelpDispatchTransform for u8 {
388 fn transform_on<O: SealedPixelWithColorType<TransformableSubpixel = Self>>(
389 transform: &cicp::CicpTransform,
390 into: LayoutWithColor,
391 ) -> &'_ (dyn Fn(&[Self], &mut [Self]) + Send + Sync) {
392 &**transform.select_transform_u8::<O>(into)
393 }
394 }
395
396 impl HelpDispatchTransform for u16 {
397 fn transform_on<O: SealedPixelWithColorType<TransformableSubpixel = Self>>(
398 transform: &cicp::CicpTransform,
399 into: LayoutWithColor,
400 ) -> &'_ (dyn Fn(&[Self], &mut [Self]) + Send + Sync) {
401 &**transform.select_transform_u16::<O>(into)
402 }
403 }
404
405 impl HelpDispatchTransform for f32 {
406 fn transform_on<O: SealedPixelWithColorType<TransformableSubpixel = Self>>(
407 transform: &cicp::CicpTransform,
408 into: LayoutWithColor,
409 ) -> &'_ (dyn Fn(&[Self], &mut [Self]) + Send + Sync) {
410 &**transform.select_transform_f32::<O>(into)
411 }
412 }
413 }
414
415 /// A generalized pixel.
416 ///
417 /// A pixel object is usually not used standalone but as a view into an image buffer.
418 pub trait Pixel: Copy + Clone {
419 /// The scalar type that is used to store each channel in this pixel.
420 type Subpixel: Primitive;
421
422 /// The number of channels of this pixel type.
423 const CHANNEL_COUNT: u8;
424
425 /// Returns the components as a slice.
426 fn channels(&self) -> &[Self::Subpixel];
427
428 /// Returns the components as a mutable slice
429 fn channels_mut(&mut self) -> &mut [Self::Subpixel];
430
431 /// A string that can help to interpret the meaning each channel
432 /// See [gimp babl](http://gegl.org/babl/).
433 const COLOR_MODEL: &'static str;
434
435 /// Returns true if the alpha channel is contained.
436 const HAS_ALPHA: bool = false;
437
438 /// Retrieve the value of the alpha channel for this pixel.
439 ///
440 /// If there is no alpha channel, returns [Primitive::DEFAULT_MAX_VALUE].
441 ///
442 /// ### Note for Pixel trait implementors
443 ///
444 /// While this is a provided method, it is a good idea to override it for efficiency
445 /// if your pixel type does have an alpha channel.
446 #[inline]
447 fn alpha(&self) -> Self::Subpixel {
448 if Self::HAS_ALPHA {
449 *self.to_luma_alpha().channels().last().unwrap()
450 } else {
451 Self::Subpixel::DEFAULT_MAX_VALUE
452 }
453 }
454
455 /// Returns the channels of this pixel as a 4 tuple. If the pixel
456 /// has less than 4 channels the remainder is filled with the maximum value
457 #[deprecated(since = "0.24.0", note = "Use `channels()` or `channels_mut()`")]
458 fn channels4(
459 &self,
460 ) -> (
461 Self::Subpixel,
462 Self::Subpixel,
463 Self::Subpixel,
464 Self::Subpixel,
465 );
466
467 /// Construct a pixel from the 4 channels a, b, c and d.
468 /// If the pixel does not contain 4 channels the extra are ignored.
469 #[deprecated(
470 since = "0.24.0",
471 note = "Use the constructor of the pixel, for example `Rgba([r,g,b,a])` or `Pixel::from_slice`"
472 )]
473 fn from_channels(
474 a: Self::Subpixel,
475 b: Self::Subpixel,
476 c: Self::Subpixel,
477 d: Self::Subpixel,
478 ) -> Self;
479
480 /// Returns a view into a slice.
481 ///
482 /// Note: The slice length is not checked on creation. Thus the caller has to ensure
483 /// that the slice is long enough to prevent panics if the pixel is used later on.
484 fn from_slice(slice: &[Self::Subpixel]) -> &Self;
485
486 /// Returns mutable view into a mutable slice.
487 ///
488 /// Note: The slice length is not checked on creation. Thus the caller has to ensure
489 /// that the slice is long enough to prevent panics if the pixel is used later on.
490 fn from_slice_mut(slice: &mut [Self::Subpixel]) -> &mut Self;
491
492 /// Convert this pixel to RGB
493 fn to_rgb(&self) -> Rgb<Self::Subpixel>;
494
495 /// Convert this pixel to RGB with an alpha channel
496 fn to_rgba(&self) -> Rgba<Self::Subpixel>;
497
498 /// Convert this pixel to luma
499 fn to_luma(&self) -> Luma<Self::Subpixel>;
500
501 /// Convert this pixel to luma with an alpha channel
502 fn to_luma_alpha(&self) -> LumaA<Self::Subpixel>;
503
504 /// Apply the function ```f``` to each channel of this pixel.
505 fn map<F>(&self, f: F) -> Self
506 where
507 F: FnMut(Self::Subpixel) -> Self::Subpixel;
508
509 /// Apply the function ```f``` to each channel of this pixel.
510 fn apply<F>(&mut self, f: F)
511 where
512 F: FnMut(Self::Subpixel) -> Self::Subpixel;
513
514 /// Apply the function ```f``` to each channel except the alpha channel.
515 /// Apply the function ```g``` to the alpha channel.
516 fn map_with_alpha<F, G>(&self, f: F, g: G) -> Self
517 where
518 F: FnMut(Self::Subpixel) -> Self::Subpixel,
519 G: FnMut(Self::Subpixel) -> Self::Subpixel;
520
521 /// Apply the function ```f``` to each channel except the alpha channel.
522 /// Apply the function ```g``` to the alpha channel. Works in-place.
523 fn apply_with_alpha<F, G>(&mut self, f: F, g: G)
524 where
525 F: FnMut(Self::Subpixel) -> Self::Subpixel,
526 G: FnMut(Self::Subpixel) -> Self::Subpixel;
527
528 /// Apply the function ```f``` to each channel except the alpha channel.
529 fn map_without_alpha<F>(&self, f: F) -> Self
530 where
531 F: FnMut(Self::Subpixel) -> Self::Subpixel,
532 {
533 let mut this = *self;
534 this.apply_with_alpha(f, |x| x);
535 this
536 }
537
538 /// Apply the function ```f``` to each channel except the alpha channel.
539 /// Works in place.
540 fn apply_without_alpha<F>(&mut self, f: F)
541 where
542 F: FnMut(Self::Subpixel) -> Self::Subpixel,
543 {
544 self.apply_with_alpha(f, |x| x);
545 }
546
547 /// Apply the function ```f``` to each channel of this pixel and
548 /// ```other``` pairwise.
549 fn map2<F>(&self, other: &Self, f: F) -> Self
550 where
551 F: FnMut(Self::Subpixel, Self::Subpixel) -> Self::Subpixel;
552
553 /// Apply the function ```f``` to each channel of this pixel and
554 /// ```other``` pairwise. Works in-place.
555 fn apply2<F>(&mut self, other: &Self, f: F)
556 where
557 F: FnMut(Self::Subpixel, Self::Subpixel) -> Self::Subpixel;
558
559 /// Invert this pixel
560 fn invert(&mut self);
561
562 /// Blend the color of a given pixel into ourself, taking into account alpha channels
563 fn blend(&mut self, other: &Self);
564 }
565
566 /// Private module for supertraits of sealed traits.
567 mod seals {
568 pub trait EncodableLayout {}
569
570 impl EncodableLayout for [u8] {}
571 impl EncodableLayout for [u16] {}
572 impl EncodableLayout for [f32] {}
573 }