Add drawXBitmap() function and example

Example is in Generic folder, draw the Espressif logo on the screen.

TFT_eSPI.cpp

@@ -1764,8 +1764,8 @@ void TFT_eSPI::fillTriangle ( int32_t x0, int32_t y0, int32_t x1, int32_t y1, in
 ** Function name:           drawBitmap
 ** Description:             Draw an image stored in an array on the TFT
 ***************************************************************************************/
-void TFT_eSPI::drawBitmap(int16_t x, int16_t y, const uint8_t *bitmap, int16_t w, int16_t h, uint16_t color) {
-
+void TFT_eSPI::drawBitmap(int16_t x, int16_t y, const uint8_t *bitmap, int16_t w, int16_t h, uint16_t color)
+{
   spi_begin();
   inTransaction = true;
 
@@ -1784,6 +1784,54 @@ void TFT_eSPI::drawBitmap(int16_t x, int16_t y, const uint8_t *bitmap, int16_t w
 }
 
 
+/***************************************************************************************
+** Function name:           drawXBitmap
+** Description:             Draw an image stored in an XBM array onto the TFT
+***************************************************************************************/
+void TFT_eSPI::drawXBitmap(int16_t x, int16_t y, const uint8_t *bitmap, int16_t w, int16_t h, uint16_t color)
+{
+  spi_begin();
+  inTransaction = true;
+
+  int32_t i, j, byteWidth = (w + 7) / 8;
+
+  for (j = 0; j < h; j++) {
+    for (i = 0; i < w; i++ ) {
+      if (pgm_read_byte(bitmap + j * byteWidth + i / 8) & (1 << (i & 7))) {
+        drawPixel(x + i, y + j, color);
+      }
+    }
+  }
+
+  inTransaction = false;
+  spi_end();
+}
+
+
+/***************************************************************************************
+** Function name:           drawXBitmap
+** Description:             Draw an XBM image with foreground and background colors
+***************************************************************************************/
+void TFT_eSPI::drawXBitmap(int16_t x, int16_t y, const uint8_t *bitmap, int16_t w, int16_t h, uint16_t color, uint16_t bgcolor)
+{
+  spi_begin();
+  inTransaction = true;
+
+  int32_t i, j, byteWidth = (w + 7) / 8;
+
+  for (j = 0; j < h; j++) {
+    for (i = 0; i < w; i++ ) {
+      if (pgm_read_byte(bitmap + j * byteWidth + i / 8) & (1 << (i & 7)))
+           drawPixel(x + i, y + j,   color);
+      else drawPixel(x + i, y + j, bgcolor);
+    }
+  }
+
+  inTransaction = false;
+  spi_end();
+}
+
+
 /***************************************************************************************
 ** Function name:           setCursor
 ** Description:             Set the text cursor x,y position

TFT_eSPI.h

@@ -526,6 +526,8 @@ class TFT_eSPI : public Print {
            fillTriangle(int32_t x0, int32_t y0, int32_t x1, int32_t y1, int32_t x2, int32_t y2, uint32_t color),
 
            drawBitmap(int16_t x, int16_t y, const uint8_t *bitmap, int16_t w, int16_t h, uint16_t color),
+           drawXBitmap(int16_t x, int16_t y, const uint8_t *bitmap, int16_t w, int16_t h, uint16_t color),
+           drawXBitmap(int16_t x, int16_t y, const uint8_t *bitmap, int16_t w, int16_t h, uint16_t fgcolor, uint16_t bgcolor),
            setBitmapColor(uint16_t c, uint16_t b), // For 1bpp sprites
 
            setCursor(int16_t x, int16_t y),

examples/Generic/drawXBitmap/drawXBitmap.ino

+// Example sketch to demonstrate the drawing of X BitMap (XBM)
+// format image onto the display.
+
+// Information on the X BitMap (XBM) format can be found here:
+// https://en.wikipedia.org/wiki/X_BitMap
+
+// This example is part of the TFT_eSPI library:
+// https://github.com/Bodmer/TFT_eSPI
+
+// Created by Bodmer 23/14/18
+
+#include "xbm.h"             // Sketch tab header for xbm images
+
+#include <TFT_eSPI.h>        // Hardware-specific library
+
+TFT_eSPI tft = TFT_eSPI();   // Invoke library
+
+
+void setup()
+{
+  tft.begin();               // Initialise the display
+  tft.fillScreen(TFT_BLACK); // Black screen fill
+}
+
+void loop()
+{
+
+  // Example 1
+  // =========
+  // Random x and y coordinates
+  int x = random(tft.width()  - logoWidth);
+  int y = random(tft.height() - logoHeight);
+
+  // Draw bitmap with top left corner at x,y with foreground only color
+  // Bits set to 1 plot as the defined color, bits set to 0 are not plotted
+  //              x  y  xbm   xbm width  xbm height  color
+  tft.drawXBitmap(x, y, logo, logoWidth, logoHeight, TFT_WHITE);
+
+  delay(500);
+
+  // Erase old one by drawing over with background colour
+  tft.drawXBitmap(x, y, logo, logoWidth, logoHeight, TFT_BLACK);
+
+
+  // Example 2
+  // =========
+  // New random x and y coordinates
+  x = random(tft.width()  - logoWidth);
+  y = random(tft.height() - logoHeight);
+
+  // Draw bitmap with top left corner at x,y with foreground and background colors
+  // Bits set to 1 plot as the defined fg color, bits set to 0 are plotted as bg color
+  //              x  y  xbm   xbm width  xbm height  fg color   bg color
+  tft.drawXBitmap(x, y, logo, logoWidth, logoHeight, TFT_WHITE, TFT_RED);
+
+  delay(500);
+
+  // Erase old one by drawing over with background colour
+  tft.drawXBitmap(x, y, logo, logoWidth, logoHeight, TFT_BLACK, TFT_BLACK);
+
+}

examples/Generic/drawXBitmap/xbm.h

+// Images can be converted to XBM format by using the online converter here:
+// https://www.online-utility.org/image/convert/to/XBM
+
+// The output must be pasted in a header file, renamed and adjusted to appear
+// as as a const unsigned char array in PROGMEM (FLASH program memory).
+
+// The xbm format adds padding to pixel rows so they are a whole number of bytes
+// In this example 50 pixel width means 56 bits = 7 bytes
+// the 50 height then means array uses 50 x 7 = 350 bytes of FLASH
+// The library ignores the padding bits when drawing the image on the display.
+
+// Example of the correct format is shown below
+
+#include <pgmspace.h>  // PROGMEM support header
+
+// Espressif logo 50 x 50 pixel array in XBM format
+#define logoWidth  50  // logo width
+#define logoHeight 50  // logo height
+
+// Image is stored in this array
+PROGMEM const unsigned char logo[] = {
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 
+  0x00, 0x00, 0x3F, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0x01, 0x00, 
+  0x00, 0x00, 0x00, 0x07, 0xFC, 0x07, 0x00, 0x00, 0x00, 0x82, 0x7F, 0xF0, 
+  0x1F, 0x00, 0x00, 0x00, 0xC6, 0xFF, 0xC3, 0x3F, 0x00, 0x00, 0x00, 0xE7, 
+  0xFF, 0x8F, 0x7F, 0x00, 0x00, 0x80, 0xE3, 0xFF, 0x1F, 0xFE, 0x00, 0x00, 
+  0x80, 0xE1, 0xFF, 0x7F, 0xFC, 0x01, 0x00, 0xC0, 0x00, 0xFF, 0xFF, 0xF8, 
+  0x03, 0x00, 0xE0, 0x00, 0xE0, 0xFF, 0xF1, 0x03, 0x00, 0x60, 0xF0, 0x81, 
+  0xFF, 0xE3, 0x07, 0x00, 0x60, 0xFC, 0x1F, 0xFE, 0xC7, 0x07, 0x00, 0x30, 
+  0xFE, 0x7F, 0xF8, 0x8F, 0x0F, 0x00, 0x30, 0xFF, 0xFF, 0xF1, 0x9F, 0x0F, 
+  0x00, 0xB0, 0xFF, 0xFF, 0xE3, 0x3F, 0x0F, 0x00, 0xB0, 0xFF, 0xFF, 0xC7, 
+  0x3F, 0x1E, 0x00, 0xB8, 0xFF, 0xFF, 0x8F, 0x7F, 0x1E, 0x00, 0x98, 0x1F, 
+  0xFC, 0x3F, 0xFF, 0x1C, 0x00, 0xB8, 0x3F, 0xE0, 0x3F, 0xFE, 0x1C, 0x00, 
+  0x98, 0xFF, 0xC3, 0x7F, 0xFE, 0x19, 0x00, 0x98, 0xFF, 0x0F, 0xFF, 0xFC, 
+  0x19, 0x00, 0x38, 0xFF, 0x3F, 0xFF, 0xFC, 0x01, 0x00, 0x30, 0xFE, 0x7F, 
+  0xFE, 0xF9, 0x03, 0x00, 0x30, 0xFC, 0xFF, 0xFC, 0xF9, 0x03, 0x00, 0x30, 
+  0xF8, 0xFF, 0xF8, 0xF3, 0x03, 0x00, 0x30, 0x00, 0xFF, 0xF9, 0xF3, 0x03, 
+  0x00, 0x70, 0x00, 0xFC, 0xF9, 0xF3, 0x07, 0x00, 0x60, 0x00, 0xF8, 0xF3, 
+  0xF3, 0x07, 0x00, 0xE0, 0xF8, 0xF8, 0xF3, 0xF7, 0x03, 0x00, 0xC0, 0xF8, 
+  0xF1, 0xF3, 0xE3, 0x03, 0x00, 0xC0, 0xFD, 0xF1, 0xF3, 0xF7, 0x01, 0x00, 
+  0x80, 0xFD, 0xF1, 0xF3, 0xE7, 0x00, 0x00, 0x00, 0xFF, 0xF1, 0xF3, 0x07, 
+  0x00, 0x00, 0x00, 0xFF, 0xF8, 0xF3, 0x07, 0x00, 0x00, 0x00, 0x7E, 0xF8, 
+  0xF3, 0x83, 0x03, 0x00, 0x00, 0x3C, 0xF8, 0xF3, 0xC3, 0x01, 0x00, 0x00, 
+  0x70, 0xF8, 0xF9, 0xE3, 0x00, 0x00, 0x00, 0xE0, 0xE1, 0x41, 0x78, 0x00, 
+  0x00, 0x00, 0xC0, 0x0F, 0x00, 0x1F, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xFD, 
+  0x07, 0x00, 0x00, 0x00, 0x00, 0xF8, 0xFF, 0x01, 0x00, 0x00, 0x00, 0x00, 
+  0x80, 0x16, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 
+  0x00, 0x00, };
+

keywords.txt

@@ -29,6 +29,7 @@ fillEllipse	KEYWORD2
 drawTriangle	KEYWORD2
 fillTriangle	KEYWORD2
 drawBitmap	KEYWORD2
+drawXBitmap	KEYWORD2
 setCursor	KEYWORD2
 getCursorX	KEYWORD2
 getCursorY	KEYWORD2

library.json

 {
   "name": "TFT_eSPI",
-  "version": "0.20.13",
+  "version": "0.20.14",
   "keywords": "tft, ePaper, display, ESP8266, NodeMCU, ESP32, M5Stack, ILI9341, ST7735, ILI9163, S6D02A1, ILI9486",
   "description": "A TFT and ePaper SPI graphics library for ESP8266 and ESP32",
   "repository":

library.properties

 name=TFT_eSPI
-version=0.20.13
+version=0.20.14
 author=Bodmer
 maintainer=Bodmer
 sentence=A fast TFT library for ESP8266 processors and the Arduino IDE