Add clear option to display() and paintScreen()

Also remove some trailing whitespace

keywords.txt

@@ -96,6 +96,8 @@ BLACK	LITERAL1
 WHITE	LITERAL1
 INVERT	LITERAL1
 
+CLEAR_BUFFER	LITERAL1
+
 A_BUTTON	LITERAL1
 B_BUTTON	LITERAL1
 DOWN_BUTTON	LITERAL1

src/Arduboy2.cpp

@@ -846,6 +846,11 @@ void Arduboy2Base::display()
   paintScreen(sBuffer);
 }
 
+void Arduboy2Base::display(bool clear)
+{
+  paintScreen(sBuffer, clear);
+}
+
 uint8_t* Arduboy2Base::getBuffer()
 {
   return sBuffer;

src/Arduboy2.h

@@ -69,6 +69,8 @@
  */
 #define INVERT 2
 
+#define CLEAR_BUFFER true /**< Value to be passed to `display()` to clear the screen buffer. */
+
 // compare Vcc to 1.1 bandgap
 #define ADC_VOLTAGE (_BV(REFS0) | _BV(MUX4) | _BV(MUX3) | _BV(MUX2) | _BV(MUX1))
 // compare temperature to 2.5 internal reference and _BV(MUX5)
@@ -226,6 +228,8 @@ class Arduboy2Base : public Arduboy2Core
    *
    * \details
    * The entire contents of the screen buffer are cleared to BLACK.
+   *
+   * \see display(bool)
    */
   void clear();
 
@@ -235,9 +239,31 @@ class Arduboy2Base : public Arduboy2Core
    * \details
    * The contents of the display buffer in RAM are copied to the display and
    * will appear on the screen.
+   *
+   * \see display(bool)
    */
   void display();
 
+  /** \brief
+   * Copy the contents of the display buffer to the display. The display buffer
+   * can optionally be cleared.
+   *
+   * \param clear If `true` the display buffer will be cleared to zero.
+   * The defined value `CLEAR_BUFFER` should be used instead of `true` to make
+   * it more meaningful.
+   *
+   * \details
+   * Operation is the same as calling `display()` without parameters except
+   * additionally the display buffer will be cleared if the parameter evaluates
+   * to `true`. (The defined value `CLEAR_BUFFER` can be used for this)
+   *
+   * Using `display(CLEAR_BUFFER)` is faster and produces less code than
+   * calling `display()` followed by `clear()`.
+   *
+   * \see display() clear()
+   */
+  void display(bool clear);
+
   /** \brief
    * Set a single pixel in the display buffer to the specified color.
    *
@@ -553,7 +579,6 @@ class Arduboy2Base : public Arduboy2Core
    */
   bool nextFrame();
 
-  
   /** \brief
    * Indicate if the specified number of frames has elapsed.
    *

src/Arduboy2Core.cpp

@@ -248,12 +248,18 @@ void Arduboy2Core::paintScreen(const uint8_t *image)
 
 // paint from a memory buffer, this should be FAST as it's likely what
 // will be used by any buffer based subclass
-void Arduboy2Core::paintScreen(uint8_t image[])
+void Arduboy2Core::paintScreen(uint8_t image[], bool clear)
 {
   uint8_t c;
   int i = 0;
 
-  SPDR = image[i++]; // set the first SPI data byte to get things started
+  if (clear)
+  {
+    SPDR = image[i]; // set the first SPI data byte to get things started
+    image[i++] = 0;  // clear the first image byte
+  }
+  else
+    SPDR = image[i++];
 
   // the code to iterate the loop and get the next byte from the buffer is
   // executed while the previous byte is being sent out by the SPI controller
@@ -261,6 +267,13 @@ void Arduboy2Core::paintScreen(uint8_t image[])
   {
     // get the next byte. It's put in a local variable so it can be sent as
     // as soon as possible after the sending of the previous byte has completed
+    if (clear)
+    {
+      c = image[i];
+      // clear the byte in the image buffer
+      image[i++] = 0;
+    }
+    else
       c = image[i++];
 
     while (!(SPSR & _BV(SPIF))) { } // wait for the previous byte to be sent

src/Arduboy2Core.h

@@ -293,6 +293,9 @@ class Arduboy2Core
      *
      * \param image A byte array in RAM representing the entire contents of
      * the display.
+     * \param clear If `true` the array in RAM will be cleared to zeros upon
+     * return from this function. If `false` the RAM buffer will remain
+     * unchanged. (optional; defaults to `false`)
      *
      * \details
      * The contents of the specified array in RAM is written to the display.
@@ -302,9 +305,12 @@ class Arduboy2Core
      * each row, to the bottom right. The size of the array must exactly
      * match the number of pixels in the entire display.
      *
+     * If parameter `clear` is set to `true` the RAM array will be cleared to
+     * zeros after its contents are written to the display.
+     *
      * \see paint8Pixels()
      */
-    void static paintScreen(uint8_t image[]);
+    void static paintScreen(uint8_t image[], bool clear = false);
 
     /** \brief
      * Blank the display screen by setting all pixels off.