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)
@@ -128,7 +130,7 @@ struct Point
  *
  * \code
  * #include <Arduboy2.h>
- * 
+ *
  * Arduboy2 arduboy;
  *
  * // Arduboy2Audio functions can be called as follows:
@@ -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.
    *
@@ -386,7 +412,7 @@ class Arduboy2Base : public Arduboy2Core
    * \param color The triangle's color (optional; defaults to WHITE).
    *
    * \details
-   * A triangle is drawn by specifying each of the three corner locations. 
+   * A triangle is drawn by specifying each of the three corner locations.
    * The corners can be at any position with respect to the others.
    */
   void drawTriangle(int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t color = WHITE);
@@ -399,7 +425,7 @@ class Arduboy2Base : public Arduboy2Core
    * \param color The triangle's color (optional; defaults to WHITE).
    *
    * \details
-   * A triangle is drawn by specifying each of the three corner locations. 
+   * A triangle is drawn by specifying each of the three corner locations.
    * The corners can be at any position with respect to the others.
    */
   void fillTriangle (int16_t x0, int16_t y0, int16_t x1, int16_t y1, int16_t x2, int16_t y2, uint8_t color = WHITE);
@@ -553,10 +579,9 @@ class Arduboy2Base : public Arduboy2Core
    */
   bool nextFrame();
 
-  
   /** \brief
    * Indicate if the specified number of frames has elapsed.
-   * 
+   *
    * \param frames The desired number of elapsed frames.
    *
    * \return `true` if the specified number of frames has elapsed.

src/Arduboy2Audio.h

@@ -30,7 +30,7 @@
  *
  * \code
  * #include <Arduboy2.h>
- * 
+ *
  * Arduboy2 arduboy;
  *
  * // Arduboy2Audio functions can be called as follows:

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,7 +267,14 @@ 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
-    c = image[i++];
+    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

@@ -208,7 +208,7 @@ class Arduboy2Core
      *
      * \note
      * In most cases, the defined value `WIDTH` would be better to use instead
-     * of this function. 
+     * of this function.
      */
     uint8_t static width();
 
@@ -219,7 +219,7 @@ class Arduboy2Core
      *
      * \note
      * In most cases, the defined value `HEIGHT` would be better to use instead
-     * of this function. 
+     * of this function.
      */
     uint8_t static height();
 
@@ -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.