1//! Embedded-graphics is a 2D graphics library that is focused on memory constrained embedded devices.
2//!
3//! A core goal of embedded-graphics is to draw graphics without using any buffers; the crate is
4//! `no_std` compatible and works without a dynamic memory allocator, and without pre-allocating
5//! large chunks of memory. To achieve this, it takes an `Iterator` based approach, where pixel
6//! colors and positions are calculated on the fly, with the minimum of saved state. This allows the
7//! consuming application to use far less RAM at little to no performance penalty.
8//!
9//! It contains built in items that make it easy to draw 2D graphics primitives:
10//!
11//! * [Raw data images]
12//! * [Primitives]
13//! * [Lines]
14//! * [Rectangles (and squares)]
15//! * [Circles]
16//! * [Ellipses]
17//! * [Arcs]
18//! * [Sectors]
19//! * [Triangles]
20//! * [Polylines]
21//! * [Rounded rectangles]
22//! * [Text]
23//! * [Monospaced fonts]
24//!
25//! # Additional functions provided by external crates
26//!
27//! Embedded-graphics is designed to be extended by the application or other crates. Examples of
28//! this are adding support for different image formats or implementing custom fonts.
29//!
30//! * [BMP images - `tinybmp`](https://crates.io/crates/tinybmp)
31//! * [TGA images - `tinytga`](https://crates.io/crates/tinytga)
32//! * [QOI images - `tinyqoi`](https://crates.io/crates/tinyqoi)
33//! * [Large collection of fonts - `u8g2-fonts`](https://crates.io/crates/u8g2-fonts)
34//! * [ProFont monospace font - `profont`](https://crates.io/crates/profont)
35//! * [Picofont Pico8 font - `embedded-picofont`](https://crates.io/crates/embedded_picofont)
36//! * [IBM437 font - `ibm437`](https://crates.io/crates/ibm437)
37//! * [The fonts shipped with `embedded-graphics` 0.6 - `embedded-vintage-fonts`](https://crates.io/crates/embedded-vintage-fonts)
38//! * [Simple layout/alignment functions - `embedded-layout`](https://crates.io/crates/embedded-layout)
39//! * [TextBox with text alignment options - `embedded-text`](https://crates.io/crates/embedded-text)
40//! * [Heapless plotting library for small embedded targets - `embedded-plots`](https://crates.io/crates/embedded-plots)
41//! * [Virtual seven-segment displays - `eg-seven-segment`](https://crates.io/crates/eg-seven-segment)
42//! * [Canvas for drawing onto before drawing on the display - `embedded-canvas`](https://crates.io/crates/embedded-canvas)
43//! * [Frames Per Second counter for embedded devices - `embedded-fps`](https://crates.io/crates/embedded-fps)
44//! * [Framebuffer with DMA support - `embedded-graphics-framebuf`](https://crates.io/crates/embedded-graphics-framebuf)
45//!
46//! Note that some of these crates may not support the latest version of embedded-graphics.
47//!
48//! If you know of a crate that is not in this list, please [open an
49//! issue](https://github.com/embedded-graphics/embedded-graphics/issues/new) to add it.
50//!
51//! # Display drivers
52//!
53//! To support many different kinds of display, embedded-graphics doesn't include any drivers
54//! directly but provides the [`DrawTarget`] API in [`embedded-graphics-core`] that can be
55//! implemented by external crates. In addition to the drivers for real displays, the
56//! [simulator](https://docs.rs/embedded-graphics-simulator/) can be used to test code during
57//! development.
58//!
59//! ![Photographs showing embedded-graphics running on physical display hardware.](https://raw.githubusercontent.com/embedded-graphics/embedded-graphics/4c680418cc4c37b8f7ed92d8b26edfde880d4c96/assets/banner-photo.jpg)
60//!
61//! These are just some of the displays the community has added embedded-graphics support to. This
62//! list is taken from the [dependent crates
63//! list](https://crates.io/crates/embedded-graphics/reverse_dependencies) on crates.io so might be
64//! missing some unpublished entries. Please [open an
65//! issue](https://github.com/embedded-graphics/embedded-graphics/issues/new) if there's a display driver
66//! that should be added to this list.
67//!
68//! Note that some drivers may not support the latest version of embedded-graphics.
69//!
70//! * [embedded-graphics-web-simulator](https://crates.io/crates/embedded-graphics-web-simulator): Simulated display in your browser via Webassembly
71//! * [epd-waveshare](https://crates.io/crates/epd-waveshare) Driver for various ePaper displays (EPD) from Waveshare
72//! * [hub75](https://crates.io/crates/hub75): A rust driver for hub75 rgb matrix displays
73//! * [ili9341](https://crates.io/crates/ili9341): A platform agnostic driver to interface with the ILI9341 (and ILI9340C) TFT LCD display
74//! * [ls010b7dh01](https://crates.io/crates/ls010b7dh01): A platform agnostic driver for the LS010B7DH01 memory LCD display
75//! * [push2_display](https://crates.io/crates/push2_display): Ableton Push2 embedded-graphics display driver
76//! * [sh1106](https://crates.io/crates/sh1106): I2C driver for the SH1106 OLED display
77//! * [smart-leds-matrix](https://github.com/smart-leds-rs/smart-leds-matrix): Driver for smart LED (like ws2812) based LED matrixes.
78//! * [ssd1306](https://crates.io/crates/ssd1306): I2C and SPI (4 wire) driver for the SSD1306 OLED display
79//! * [ssd1309](https://crates.io/crates/ssd1309): I2C/SPI driver for the SSD1309 OLED display written in 100% Rust.
80//! * [ssd1322](https://crates.io/crates/ssd1322): Pure Rust driver for the SSD1322 OLED display chip
81//! * [ssd1331](https://crates.io/crates/ssd1331): SPI (4 wire) driver for the SSD1331 OLED display
82//! * [ssd1351](https://crates.io/crates/ssd1351): SSD1351 driver
83//! * [ssd1675](https://crates.io/crates/ssd1675): Rust driver for the Solomon Systech SSD1675 e-Paper display (EPD) controller
84//! * [st7565](https://crates.io/crates/st7565): SPI driver for ST7565 based displays
85//! * [st7735-lcd](https://crates.io/crates/st7735-lcd): Rust library for displays using the ST7735 driver
86//! * [st7789](https://crates.io/crates/st7789): A Rust driver library for ST7789 displays
87//! * [st7920](https://crates.io/crates/st7920): ST7920 LCD driver in Rust
88//! * [gc9a01-rs](https://crates.io/crates/gc9a01-rs): SPI 4-wire driver for the Gc9a01 display driver
89//!
90//! # Simulator
91//!
92//! Embedded graphics comes with a [simulator]! The simulator can be used to test and debug
93//! embedded graphics code, or produce examples and interactive demos to show off embedded graphics
94//! features.
95//!
96//! ![A screenshot of embedded-graphics running in its simulator.](https://raw.githubusercontent.com/embedded-graphics/embedded-graphics/4c680418cc4c37b8f7ed92d8b26edfde880d4c96/assets/simulator-demo.png)
97//!
98//! Take a look at the [examples repository](https://github.com/embedded-graphics/examples) to see what
99//! embedded-graphics can do, and how it might look on a display. You can run the examples like
100//! this:
101//!
102//! ```bash
103//! git clone https://github.com/embedded-graphics/examples.git
104//! cd examples/eg-0.7
105//!
106//! cargo run --example hello-world
107//! ```
108//!
109//! # Crate features
110//!
111//! Additional features can be enabled by adding the following features to your `Cargo.toml`.
112//!
113//! * `nalgebra_support` - use the [Nalgebra](https://crates.io/crates/nalgebra) crate with `no_std`
114//! support to enable conversions from `nalgebra::Vector2` to [`Point`] and [`Size`].
115//!
116//! * `fixed_point` - use fixed point arithmetic instead of floating point for all trigonometric
117//! calculation.
118//!
119//! * `defmt` - provide implementations of `defmt::Format` for all types where possible. [`defmt`]
120//! is a library for logging that moves as much work as possible over to a separate logging
121//! machine, making it especially suited to low-resource MCUs. Note that `defmt` might not work with
122//! older versions of rustc that are otherwise supported by embedded-graphics.
123//!
124//! # Migrating from older versions
125//!
126//! * [Migration guide from 0.5 to 0.6](https://github.com/embedded-graphics/embedded-graphics/blob/master/MIGRATING-0.5-0.6.md).
127//! * [Migration guide from 0.6 to 0.7](https://github.com/embedded-graphics/embedded-graphics/blob/master/MIGRATING-0.6-0.7.md).
128//!
129//! # Implementing `embedded_graphics` support for a display driver
130//!
131//! To add support for embedded-graphics to a display driver, [`DrawTarget`] from
132//! [`embedded-graphics-core`] must be implemented. This allows all embedded-graphics items to be
133//! rendered by the display. See the [`DrawTarget`] documentation for implementation details.
134//!
135//! # Examples
136//!
137//! ## Drawing examples
138//!
139//! [![A grid of screenshots showing primitives, text and other items that can be drawn using embedded-graphics.](https://raw.githubusercontent.com/embedded-graphics/embedded-graphics/4c680418cc4c37b8f7ed92d8b26edfde880d4c96/doc/assets/all_drawing_ops.png)][examples]
140//!
141//! Example usage of drawing primitives, text and images with embedded-graphics can be found [here][examples].
142//!
143//! ## Shapes and text
144//!
145//! The following example draws some shapes and text to a [`MockDisplay`] in place of target
146//! hardware. The [simulator](https://docs.rs/embedded-graphics-simulator/) can also be used for
147//! debugging, development or if hardware is not available.
148//!
149//! ```rust,no_run
150//! use embedded_graphics::{
151//! mono_font::{ascii::FONT_6X10, MonoTextStyle},
152//! pixelcolor::BinaryColor,
153//! prelude::*,
154//! primitives::{
155//! Circle, PrimitiveStyle, PrimitiveStyleBuilder, Rectangle, StrokeAlignment, Triangle,
156//! },
157//! text::{Alignment, Text},
158//! mock_display::MockDisplay,
159//! };
160//!
161//! fn main() -> Result<(), std::convert::Infallible> {
162//! // Create a new mock display
163//! let mut display: MockDisplay<BinaryColor> = MockDisplay::new();
164//! # display.set_allow_overdraw(true);
165//!
166//! // Create styles used by the drawing operations.
167//! let thin_stroke = PrimitiveStyle::with_stroke(BinaryColor::On, 1);
168//! let thick_stroke = PrimitiveStyle::with_stroke(BinaryColor::On, 3);
169//! let border_stroke = PrimitiveStyleBuilder::new()
170//! .stroke_color(BinaryColor::On)
171//! .stroke_width(3)
172//! .stroke_alignment(StrokeAlignment::Inside)
173//! .build();
174//! let fill = PrimitiveStyle::with_fill(BinaryColor::On);
175//! let character_style = MonoTextStyle::new(&FONT_6X10, BinaryColor::On);
176//!
177//! let yoffset = 10;
178//!
179//! // Draw a 3px wide outline around the display.
180//! display
181//! .bounding_box()
182//! .into_styled(border_stroke)
183//! .draw(&mut display)?;
184//!
185//! // Draw a triangle.
186//! Triangle::new(
187//! Point::new(16, 16 + yoffset),
188//! Point::new(16 + 16, 16 + yoffset),
189//! Point::new(16 + 8, yoffset),
190//! )
191//! .into_styled(thin_stroke)
192//! .draw(&mut display)?;
193//!
194//! // Draw a filled square
195//! Rectangle::new(Point::new(52, yoffset), Size::new(16, 16))
196//! .into_styled(fill)
197//! .draw(&mut display)?;
198//!
199//! // Draw a circle with a 3px wide stroke.
200//! Circle::new(Point::new(88, yoffset), 17)
201//! .into_styled(thick_stroke)
202//! .draw(&mut display)?;
203//!
204//! // Draw centered text.
205//! let text = "embedded-graphics";
206//! Text::with_alignment(
207//! text,
208//! display.bounding_box().center() + Point::new(0, 15),
209//! character_style,
210//! Alignment::Center,
211//! )
212//! .draw(&mut display)?;
213//!
214//! Ok(())
215//! }
216//! ```
217//!
218//! This example is also included in the [examples](https://github.com/embedded-graphics/examples) repository and
219//! can be run using `cargo run --example hello-world`. It produces this output:
220//!
221//! ![Embedded Graphics Simulator example screenshot](https://raw.githubusercontent.com/embedded-graphics/embedded-graphics/4c680418cc4c37b8f7ed92d8b26edfde880d4c96/assets/hello-world-simulator.png)
222//!
223//! Additional examples can be found in the [examples](https://github.com/embedded-graphics/examples) repository.
224//!
225//! <!-- README-LINKS
226//! [`Circle`]: https://docs.rs/embedded-graphics/latest/embedded_graphics/primitives/circle/struct.Circle.html
227//! [`MockDisplay`]: https://docs.rs/embedded-graphics/latest/embedded_graphics/mock_display/struct.MockDisplay.html
228//! [`Point`]: https://docs.rs/embedded-graphics/latest/embedded_graphics/geometry/struct.Point.html
229//! [`Size`]: https://docs.rs/embedded-graphics/latest/embedded_graphics/geometry/struct.Size.html
230//! [Raw data images]: https://docs.rs/embedded-graphics/latest/embedded_graphics/image/struct.ImageRaw.html
231//! [Primitives]: https://docs.rs/embedded-graphics/latest/embedded_graphics/primitives/index.html
232//! [Lines]: https://docs.rs/embedded-graphics/latest/embedded_graphics/primitives/line/struct.Line.html
233//! [Rectangles (and squares)]: https://docs.rs/embedded-graphics/latest/embedded_graphics/primitives/rectangle/struct.Rectangle.html
234//! [Circles]: https://docs.rs/embedded-graphics/latest/embedded_graphics/primitives/circle/struct.Circle.html
235//! [Ellipses]: https://docs.rs/embedded-graphics/latest/embedded_graphics/primitives/ellipse/struct.Ellipse.html
236//! [Arcs]: https://docs.rs/embedded-graphics/latest/embedded_graphics/primitives/arc/struct.Arc.html
237//! [Sectors]: https://docs.rs/embedded-graphics/latest/embedded_graphics/primitives/sector/struct.Sector.html
238//! [Triangles]: https://docs.rs/embedded-graphics/latest/embedded_graphics/primitives/triangle/struct.Triangle.html
239//! [Polylines]: https://docs.rs/embedded-graphics/latest/embedded_graphics/primitives/polyline/struct.Polyline.html
240//! [Rounded rectangles]: https://docs.rs/embedded-graphics/latest/embedded_graphics/primitives/rounded_rectangle/struct.RoundedRectangle.html
241//! [Text]: https://docs.rs/embedded-graphics/latest/embedded_graphics/text/index.html
242//! [Monospaced fonts]: https://docs.rs/embedded-graphics/latest/embedded_graphics/mono_font/index.html
243//! [examples]: https://docs.rs/embedded-graphics/latest/embedded_graphics/examples/index.html
244//! README-LINKS -->
245//!
246//! [`Circle`]: primitives::circle::Circle
247//! [`MockDisplay`]: mock_display::MockDisplay
248//! [`Point`]: geometry::Point
249//! [`Size`]: geometry::Size
250//! [Raw data images]: image::ImageRaw
251//! [Primitives]: primitives
252//! [Lines]: primitives::line::Line
253//! [Rectangles (and squares)]: primitives::rectangle::Rectangle
254//! [Circles]: primitives::circle::Circle
255//! [Ellipses]: primitives::ellipse::Ellipse
256//! [Arcs]: primitives::arc::Arc
257//! [Sectors]: primitives::sector::Sector
258//! [Triangles]: primitives::triangle::Triangle
259//! [Polylines]: primitives::polyline::Polyline
260//! [Rounded rectangles]: primitives::rounded_rectangle::RoundedRectangle
261//! [Text]: text
262//! [Monospaced fonts]: mono_font
263//! [`Drawable`]: drawable::Drawable
264//! [`DrawTarget`]: https://docs.rs/embedded-graphics-core/latest/embedded_graphics_core/draw_target/trait.DrawTarget.html
265//! [`embedded-graphics-core`]: https://docs.rs/embedded-graphics-core/
266//! [simulator]: https://github.com/embedded-graphics/simulator
267//! [simulator examples]: https://github.com/embedded-graphics/simulator/tree/master/examples
268//! [`defmt`]: https://defmt.ferrous-systems.com/
269
270#![doc(
271 html_logo_url = "https://raw.githubusercontent.com/embedded-graphics/embedded-graphics/191fe7f8a0fedc713f9722b9dc59208dacadee7e/assets/logo.svg?sanitize=true"
272)]
273#![no_std]
274#![deny(missing_docs)]
275#![deny(missing_debug_implementations)]
276#![deny(missing_copy_implementations)]
277#![deny(trivial_casts)]
278#![deny(trivial_numeric_casts)]
279#![deny(unsafe_code)]
280#![deny(unstable_features)]
281#![deny(unused_import_braces)]
282#![deny(unused_qualifications)]
283#![deny(rustdoc::broken_intra_doc_links)]
284#![deny(rustdoc::private_intra_doc_links)]
285
286pub mod draw_target;
287pub mod examples;
288pub mod framebuffer;
289pub mod geometry;
290pub mod image;
291pub mod iterator;
292pub mod mock_display;
293pub mod mono_font;
294pub mod prelude;
295pub mod primitives;
296pub mod text;
297pub mod transform;
298
299pub use embedded_graphics_core::{pixelcolor, Drawable, Pixel};
300