split display implementation by modes via generics

Author: kattouf

Cargo.toml

@@ -18,6 +18,9 @@ embedded-graphics-core = { version = "0.3.3", optional = true }
 display-interface = "0.4.1"
 display-interface-i2c = "0.4.0"
 
+[dev-dependencies]
+embedded-graphics = "0.7.1"
+
 [features]
 default = ["graphics"]
 graphics = ["embedded-graphics-core"]

src/consts.rs

@@ -1,2 +1,3 @@
 pub(crate) const DISPLAY_WIDTH: u8 = 128;
 pub(crate) const DISPLAY_HEIGHT: u8 = 64;
+pub(crate) const BUFFER_SIZE: usize = (DISPLAY_WIDTH as usize) * (DISPLAY_HEIGHT as usize) / 8;

src/display.rs

@@ -3,36 +3,100 @@
 use crate::{command::*, consts::*};
 use display_interface::{DisplayError, WriteOnlyDataCommand};
 
-const BUFFER_SIZE: usize = (DISPLAY_WIDTH as usize) * (DISPLAY_HEIGHT as usize) / 8;
-
-/// ST7565S display driver\
+/// ST7565S display driver
 ///
-/// - Provides two display modes:
-///   - Internal Buffer Mode: This mode allows you to modify an internal buffer by using methods like [`set_pixel`], [`clear`], or by using the [`embedded-graphics`] crate. Once you have made your changes, you can call the [`flush`] method to write the buffer to the display.
-///   - Direct Write Mode: This mode allows you to write directly to the display memory by calling the [`draw`] method.
+///  Works in two modes:
+///  - Direct Write Mode (by default): This mode allows you to write directly to the display memory by calling the [`draw`] method.
+///  - Buffered Mode: This mode allows you to modify an internal buffer by using methods like [`set_pixel`], [`clear`], or by using the [`embedded-graphics`] crate. Once you have made your changes, you can call the [`flush`] method to write the buffer to the display.
 ///
 /// [`embedded-graphics`]: https://docs.rs/embedded-graphics
 /// [`set_pixel`]: crate::display::ST7567S#method.set_pixel
 /// [`clear`]: crate::display::ST7567S#method.clear
 /// [`flush`]: crate::display::ST7567S#method.flush
 /// [`draw`]: crate::display::ST7567S#method.draw
 ///
-pub struct ST7567S<DI> {
-    display_interface: DI,
+pub struct ST7567S<DI, MODE> {
+    pub(crate) mode: MODE,
+    pub(crate) display_interface: DI,
+}
+
+/// Basic mode allowing only direct write to the screen controller memory
+pub struct DirectWriteMode;
+
+/// Buffered mode allowing to collect changes and then flush them
+pub struct BufferedMode {
     buffer: [u8; BUFFER_SIZE],
 }
 
-impl<DI: WriteOnlyDataCommand> ST7567S<DI> {
-    /// Create new instance of ST7565S driver\
+impl BufferedMode {
+    pub(crate) fn new() -> Self {
+        BufferedMode {
+            buffer: [0; BUFFER_SIZE],
+        }
+    }
+}
+
+impl<DI: WriteOnlyDataCommand> ST7567S<DI, DirectWriteMode> {
+    /// Create new instance of ST7565S driver in DirectWriteMode
+    ///
     /// # Arguments
     /// * `display_interface` - The interface abstraction from `display_interface` crate
     pub fn new(display_interface: DI) -> Self {
         ST7567S {
+            mode: DirectWriteMode,
             display_interface,
-            buffer: [0; BUFFER_SIZE],
         }
     }
 
+    /// Move driver to buffered mode
+    pub fn into_buffered_graphics_mode(self) -> ST7567S<DI, BufferedMode> {
+        ST7567S {
+            mode: BufferedMode::new(),
+            display_interface: self.display_interface,
+        }
+    }
+}
+
+impl<DI: WriteOnlyDataCommand> ST7567S<DI, BufferedMode> {
+    /// Clear internal buffer
+    pub fn clear(&mut self) {
+        self.mode.buffer = [0; BUFFER_SIZE];
+    }
+
+    /// Set pixel in internal buffer
+    ///
+    /// Pixel coordinates starts from top left corner and goes to bottom right corner
+    pub fn set_pixel(&mut self, x: u8, y: u8, value: bool) -> Result<(), DisplayError> {
+        if x >= DISPLAY_WIDTH || y >= DISPLAY_HEIGHT {
+            return Err(DisplayError::OutOfBoundsError);
+        }
+
+        let column: usize = x as usize;
+        let page: usize = (y / 8) as usize;
+        let page_bit = y % 8;
+
+        let byte_idx = page * (DISPLAY_WIDTH as usize) + column;
+        let byte = self.mode.buffer[byte_idx];
+        let bit_value: u8 = value.into();
+        let byte = byte & !(1 << page_bit) | (bit_value << page_bit);
+
+        self.mode.buffer[byte_idx] = byte;
+
+        Ok(())
+    }
+
+    /// Send internal buffer to the display
+    pub fn flush(&mut self) -> Result<(), DisplayError> {
+        Self::flush_buffer_chunks(
+            &mut self.display_interface,
+            self.mode.buffer.as_slice(),
+            (0, 0),
+            (DISPLAY_WIDTH - 1, DISPLAY_HEIGHT - 1),
+        )
+    }
+}
+
+impl<DI: WriteOnlyDataCommand, MODE> ST7567S<DI, MODE> {
     /// Send init commands to the display and turn it on
     pub fn init(&mut self) -> Result<(), DisplayError> {
         SetBiasCommand::Bias1_9.write(&mut self.display_interface)?;
@@ -49,47 +113,21 @@ impl<DI: WriteOnlyDataCommand> ST7567S<DI> {
             .unwrap()
             .write(&mut self.display_interface)?;
 
-        self.clear();
-        self.flush()?;
+        self.draw([0; BUFFER_SIZE].as_slice())?;
 
         DisplayOnCommand::On.write(&mut self.display_interface)?;
 
         Ok(())
     }
 
-    /// Reset some display parameters to default values: Start Line, Column Address, Page Address and COM Direction\
+    /// Reset some display parameters to default values: Start Line, Column Address, Page Address and COM Direction.
     /// Usually doesn't need to be called
     pub fn reset(&mut self) -> Result<(), DisplayError> {
         ResetCommand.write(&mut self.display_interface)
     }
 
-    /// Clear the display buffer
-    pub fn clear(&mut self) {
-        self.buffer = [0; BUFFER_SIZE];
-    }
-
-    /// Set pixel in the display buffer\
-    /// Pixel coordinates starts from top left corner and goes to bottom right corner
-    pub fn set_pixel(&mut self, x: u8, y: u8, value: bool) -> Result<(), DisplayError> {
-        if x >= DISPLAY_WIDTH || y >= DISPLAY_HEIGHT {
-            return Err(DisplayError::OutOfBoundsError);
-        }
-
-        let column: usize = x as usize;
-        let page: usize = (y / 8) as usize;
-        let page_bit = y % 8;
-
-        let byte_idx = page * (DISPLAY_WIDTH as usize) + column;
-        let byte = self.buffer[byte_idx];
-        let bit_value: u8 = value.into();
-        let byte = byte & !(1 << page_bit) | (bit_value << page_bit);
-
-        self.buffer[byte_idx] = byte;
-
-        Ok(())
-    }
-
-    /// Send buffer to the display\
+    /// Send buffer to the display
+    ///
     /// Buffer represents by 8 pages of 128 columns where 1 byte represents 8 vertical pixels
     pub fn draw(&mut self, buffer: &[u8]) -> Result<(), DisplayError> {
         if buffer.len() != BUFFER_SIZE {
@@ -104,7 +142,7 @@ impl<DI: WriteOnlyDataCommand> ST7567S<DI> {
         )
     }
 
-    /// Send part of the buffer to the display\
+    /// Send part of the buffer to the display.
     /// Buffer represents by 8 pages of 128 columns where 1 byte represents 8 vertical pixels
     ///
     /// # Arguments
@@ -119,17 +157,7 @@ impl<DI: WriteOnlyDataCommand> ST7567S<DI> {
         Self::flush_buffer_chunks(&mut self.display_interface, buffer, top_left, bottom_right)
     }
 
-    /// Send internal buffer to the display
-    pub fn flush(&mut self) -> Result<(), DisplayError> {
-        Self::flush_buffer_chunks(
-            &mut self.display_interface,
-            self.buffer.as_slice(),
-            (0, 0),
-            (DISPLAY_WIDTH - 1, DISPLAY_HEIGHT - 1),
-        )
-    }
-
-    fn flush_buffer_chunks(
+    pub(crate) fn flush_buffer_chunks(
         display_interface: &mut DI,
         buffer: &[u8],
         top_left: (u8, u8),

src/graphics.rs

@@ -1,21 +1,24 @@
 //! [`embedded-graphics`](https://docs.rs/embedded-graphics) support
 
-use crate::{consts::*, display::ST7567S};
+use crate::{
+    consts::*,
+    display::{BufferedMode, ST7567S},
+};
 use display_interface::{DisplayError, WriteOnlyDataCommand};
 use embedded_graphics_core::{
     draw_target::DrawTarget,
     pixelcolor::BinaryColor,
-    prelude::{OriginDimensions, Size},
+    prelude::{Dimensions, OriginDimensions, Size},
     Pixel,
 };
 
-impl<DI: WriteOnlyDataCommand> OriginDimensions for ST7567S<DI> {
+impl<DI: WriteOnlyDataCommand> OriginDimensions for ST7567S<DI, BufferedMode> {
     fn size(&self) -> Size {
         Size::new(DISPLAY_WIDTH.into(), DISPLAY_HEIGHT.into())
     }
 }
 
-impl<DI: WriteOnlyDataCommand> DrawTarget for ST7567S<DI> {
+impl<DI: WriteOnlyDataCommand> DrawTarget for ST7567S<DI, BufferedMode> {
     type Color = BinaryColor;
 
     type Error = DisplayError;
@@ -24,15 +27,11 @@ impl<DI: WriteOnlyDataCommand> DrawTarget for ST7567S<DI> {
     where
         I: IntoIterator<Item = Pixel<Self::Color>>,
     {
+        let bounding_box = self.bounding_box();
         for Pixel(point, color) in pixels.into_iter() {
-            if point.x < 0 || point.y < 0 {
-                continue;
-            }
-            if point.x >= DISPLAY_WIDTH as i32 || point.y >= DISPLAY_HEIGHT as i32 {
-                continue;
+            if bounding_box.contains(point) {
+                self.set_pixel(point.x as u8, point.y as u8, color.is_on())?;
             }
-
-            self.set_pixel(point.x as u8, point.y as u8, color.is_on())?;
         }
 
         Ok(())

src/lib.rs

@@ -6,17 +6,88 @@
 //!
 //! - Supports I2C and SPI communication protocols via the [`display_interface`](https://docs.rs/display_interface) crate.
 //! - Provides two display modes:
-//!   - Internal Buffer Mode: This mode allows you to modify an internal buffer by using methods like [`set_pixel`], [`clear`], or by using the [`embedded-graphics`] crate. Once you have made your changes, you can call the [`flush`] method to write the buffer to the display.
-//!   - Direct Write Mode: This mode allows you to write directly to the display memory by calling the [`draw`] method.
+//!   - Direct Write Mode (by default): This mode allows you to write directly to the display memory by calling the [`draw`] method.
+//!   - Buffered Mode: This mode allows you to modify an internal buffer by using methods like [`set_pixel`], [`clear`], or by using the [`embedded-graphics`] crate. Once you have made your changes, you can call the [`flush`] method to write the buffer to the display.
 //!
 //! [`embedded-graphics`]: https://docs.rs/embedded-graphics
 //! [`set_pixel`]: crate::display::ST7567S#method.set_pixel
 //! [`clear`]: crate::display::ST7567S#method.clear
 //! [`flush`]: crate::display::ST7567S#method.flush
 //! [`draw`]: crate::display::ST7567S#method.draw
 //!
-//! **Note**: This driver is designed to work with a more generic 128x64 resolution, instead of the original 132x65 resolution of the ST7567S controller.
-//! **Note**: SPI communication is not tested yet.
+//! # Notes
+//! - This driver is designed to work with a more common 128x64 resolution, instead of the original 132x65 resolution of the ST7567S controller.
+//! - SPI communication is not tested yet.
+//!
+//! # Examples
+//!
+//! ### Direct write mode
+//! ```rust
+//! use st7567s::{
+//!     display::{DirectWriteMode, ST7567S},
+//!     interface::{I2CDisplayInterface, I2CInterface},
+//! };
+//! struct I2CStub;
+//! impl embedded_hal::blocking::i2c::Write for I2CStub {
+//!     type Error = ();
+//!     fn write(&mut self, _addr: u8, _buf: &[u8]) -> Result<(), ()> {
+//!         Ok(())
+//!     }
+//! }
+//!
+//! let i2c = I2CStub;
+//! let interface = I2CDisplayInterface::new(i2c);
+//! let mut display = ST7567S::new(interface);
+//! display.init().unwrap();
+//!
+//! // Set all pixels to enabled state
+//! display
+//!     .draw([0xff; 128 * 64 / 8].as_slice())
+//!     .unwrap();
+//!
+//! ```
+//!
+//! ### Buffered mode + embedded_graphics
+//! ```rust
+//! use st7567s::{
+//!     display::{BufferedMode, ST7567S},
+//!     interface::{I2CDisplayInterface, I2CInterface},
+//! };
+//! use embedded_graphics::{
+//!     mono_font::{ascii::FONT_6X10, MonoTextStyleBuilder},
+//!     pixelcolor::BinaryColor,
+//!     prelude::*,
+//!     text::{Baseline, Text},
+//! };
+//! struct I2CStub;
+//! impl embedded_hal::blocking::i2c::Write for I2CStub {
+//!     type Error = ();
+//!     fn write(&mut self, _addr: u8, _buf: &[u8]) -> Result<(), ()> {
+//!         Ok(())
+//!     }
+//! }
+//!
+//! let i2c = I2CStub;
+//! let interface = I2CDisplayInterface::new(i2c);
+//! let mut display = ST7567S::new(interface)
+//!     .into_buffered_graphics_mode();
+//! display.init().unwrap();
+//!
+//! let text_style = MonoTextStyleBuilder::new()
+//!     .font(&FONT_6X10)
+//!     .text_color(BinaryColor::On)
+//!     .build();
+//!
+//! Text::with_baseline("Hello world!", Point::zero(), text_style, Baseline::Top)
+//!     .draw(&mut display)
+//!     .unwrap();
+//!
+//! Text::with_baseline("Hello Rust!", Point::new(0, 16), text_style, Baseline::Top)
+//!     .draw(&mut display)
+//!     .unwrap();
+//!
+//! display.flush().unwrap();
+//! ```
 
 #![no_std]
 
@@ -26,3 +97,4 @@ pub mod display;
 #[cfg(feature = "graphics")]
 pub mod graphics;
 pub mod interface;
+pub mod prelude;