1//! Image drawable.
2
3use crate::{
4 draw_target::DrawTarget,
5 geometry::{OriginDimensions, Point},
6 pixelcolor::PixelColor,
7 primitives::Rectangle,
8};
9
10/// Image drawable.
11///
12/// `ImageDrawable` is implemented for types that contains image information, which makes them
13/// usable with the [`Image`] object.
14///
15/// The methods in this trait shouldn't be called directly by user code. Instead the object
16/// that implements `ImageDrawable` should be wrapped in an [`Image`] object.
17///
18/// # Implementing `ImageDrawable`
19///
20/// All image drawables are positioned at the origin and need to implement [`OriginDimensions`], in
21/// addition to this trait, to define their dimensions.
22///
23/// [`Image`]: https://docs.rs/embedded-graphics/latest/embedded_graphics/image/struct.Image.html
24/// [`OriginDimensions`]: crate::geometry::OriginDimensions
25pub trait ImageDrawable: OriginDimensions {
26 /// The color type.
27 type Color: PixelColor;
28
29 /// Draws the entire image to the target.
30 ///
31 /// This method shouldn't be called directly by user code. Use an [`Image`] object instead.
32 ///
33 /// # Implementation notes
34 ///
35 /// The implementation of this method must draw the image inside the bounding box defined by
36 /// the [`OriginDimensions`] trait implementation. This means that the top left corner is at the
37 /// origin and no drawing operations outside the bounding box are allowed.
38 ///
39 /// [`Image`]: https://docs.rs/embedded-graphics/latest/embedded_graphics/image/struct.Image.html
40 /// [`OriginDimensions`]: crate::geometry::OriginDimensions
41 fn draw<D>(&self, target: &mut D) -> Result<(), D::Error>
42 where
43 D: DrawTarget<Color = Self::Color>;
44
45 /// Draws a part of the image to the target.
46 ///
47 /// This method shouldn't be called directly by user code. Use a [`SubImage`] object instead.
48 ///
49 /// # Implementation notes
50 ///
51 /// The implementation of this method must draw the image inside the given `area`.
52 /// It must be ensured that no drawing operation outside this [`Rectangle`] occur.
53 ///
54 /// [`SubImage`]: https://docs.rs/embedded-graphics/latest/embedded_graphics/image/struct.SubImage.html
55 /// [`Rectangle`]: crate::primitives::rectangle::Rectangle
56 fn draw_sub_image<D>(&self, target: &mut D, area: &Rectangle) -> Result<(), D::Error>
57 where
58 D: DrawTarget<Color = Self::Color>;
59}
60
61/// Pixel getter.
62pub trait GetPixel {
63 /// The color type.
64 type Color: PixelColor;
65
66 /// Gets the color of a pixel.
67 ///
68 /// Returns `None` if `p` is outside the bounding box.
69 fn pixel(&self, p: Point) -> Option<Self::Color>;
70}
71