Merge pull request #528 from kamorris/add_color_maps

Add Sprite 4 bit color depth option with a defined palette of 16 colors. Add new Sprite examples.

Extensions/Sprite.h

@@ -32,11 +32,20 @@ class TFT_eSprite : public TFT_eSPI {
            // Returns a pointer to the Sprite frame buffer
   void*    frameBuffer(int8_t f);
   
-           // Set or get the colour depth to 8 or 16 bits. Can be used to change depth an existing
+           // Set or get the colour depth to 4, 8 or 16 bits. Can be used to change depth an existing
            // sprite, but clears it to black, returns a new pointer if sprite is re-created.
   void*    setColorDepth(int8_t b);
   int8_t   getColorDepth(void);
 
+           // Set the palette for a 4 bit depth sprite.  Only the first 16 colours in the map are used.
+  void     createPalette(uint16_t *palette, int colors = 16);
+
+            // Set a single palette index to the given color
+  void     setPaletteColor(uint8_t index, uint16_t color);
+
+            // Get the color at the given palette index
+  uint16_t getPaletteColor(uint8_t index);
+
            // Set foreground and background colours for 1 bit per pixel Sprite
   void     setBitmapColor(uint16_t fg, uint16_t bg);
 
@@ -100,7 +109,10 @@ class TFT_eSprite : public TFT_eSPI {
            // Read the colour of a pixel at x,y and return value in 565 format 
   uint16_t readPixel(int32_t x0, int32_t y0);
 
-           // Write an image (colour bitmap) to the sprite
+           // return the color map index of the pixel at x,y (used when scrolling)
+  uint8_t  readPixelValue(int32_t x, int32_t y);
+
+           // Write an image (colour bitmap) to the sprite.  Not implemented for _bpp == 4.
   void     pushImage(int32_t x0, int32_t y0, int32_t w, int32_t h, uint16_t *data);
   void     pushImage(int32_t x0, int32_t y0, int32_t w, int32_t h, const uint16_t *data);
 
@@ -141,9 +153,12 @@ class TFT_eSprite : public TFT_eSPI {
   uint8_t  _bpp;     // bits per pixel (1, 8 or 16)
   uint16_t *_img;    // pointer to 16 bit sprite
   uint8_t  *_img8;   // pointer to  8 bit sprite
+  uint8_t  *_img4;   // pointer to 4 bit sprite (uses color map)
   uint8_t  *_img8_1; // pointer to  frame 1
   uint8_t  *_img8_2; // pointer to  frame 2
 
+  uint16_t *_colorMap; // color map: 16 entries, used with 4 bit color map.
+
   int16_t _xpivot;   // x pivot point coordinate
   int16_t _ypivot;   // y pivot point coordinate
 

TFT_eSPI.h

@@ -399,13 +399,14 @@ class TFT_eSPI : public Print {
   void     pushImage(int32_t x0, int32_t y0, int32_t w, int32_t h, uint16_t *data);
   void     pushImage(int32_t x0, int32_t y0, int32_t w, int32_t h, uint16_t *data, uint16_t transparent);
 
+
            // These are used to render images stored in FLASH (PROGMEM)
   void     pushImage(int32_t x0, int32_t y0, int32_t w, int32_t h, const uint16_t *data, uint16_t transparent);
   void     pushImage(int32_t x0, int32_t y0, int32_t w, int32_t h, const uint16_t *data);
 
-           // These are used by pushSprite for 1 and 8 bit colours
-  void     pushImage(int32_t x0, int32_t y0, int32_t w, int32_t h, uint8_t  *data, bool bpp8 = true);
-  void     pushImage(int32_t x0, int32_t y0, int32_t w, int32_t h, uint8_t  *data, uint8_t  transparent, bool bpp8 = true);
+           // These are used by pushSprite for 1, 4 and 8 bit colours (color map needed for 4 bit)
+  void     pushImage(int32_t x0, int32_t y0, int32_t w, int32_t h, uint8_t  *data, bool bpp8 = true, uint16_t *cmap = nullptr);
+  void     pushImage(int32_t x0, int32_t y0, int32_t w, int32_t h, uint8_t  *data, uint8_t  transparent, bool bpp8 = true, uint16_t *cmap = nullptr);
 
            // Write a solid block of a single colour
   void     pushBlock(uint16_t color, uint32_t len);

examples/Sprite/Sprite_colorMap/Sprite_colorMap.ino

+/*
+
+  Sketch to show how a Sprite is created, how to draw pixels
+  and text within the Sprite and then push the Sprite onto
+  the display screen.
+
+  Example for library:
+  https://github.com/Bodmer/TFT_eSPI
+
+  A Sprite is notionally an invisible graphics screen that is
+  kept in the processors RAM. Graphics can be drawn into the
+  Sprite just as it can be drawn directly to the screen. Once
+  the Sprite is completed it can be plotted onto the screen in
+  any position. If there is sufficient RAM then the Sprite can
+  be the same size as the screen and used as a frame buffer.
+
+  A 16 bit Sprite occupies (2 * width * height) bytes in RAM.
+
+  On a ESP8266 Sprite sizes up to 126 x 160 can be accomodated,
+  this size requires 40kBytes of RAM for a 16 bit color depth.
+  
+  When 8 bit color depth sprites are created they occupy
+  (width * height) bytes in RAM, so larger sprites can be
+  created, or the RAM required is halved.
+
+*/
+
+// Set delay after plotting the sprite
+#define DELAY 1000
+
+// Width and height of sprite
+#define WIDTH  128
+#define HEIGHT 128
+
+#include <TFT_eSPI.h>                 // Include the graphics library (this includes the sprite functions)
+
+TFT_eSPI    tft = TFT_eSPI();         // Declare object "tft"
+
+TFT_eSprite spr = TFT_eSprite(&tft);  // Declare Sprite object "spr" with pointer to "tft" object
+
+
+void setup()
+{
+  Serial.begin(250000);
+  Serial.println();
+
+  delay(500);
+
+  // Initialise the TFT registers
+  tft.init();
+  
+  spr.setColorDepth(4);
+
+  // Create a sprite of defined size
+  spr.createSprite(WIDTH, HEIGHT);
+
+  // Clear the TFT screen to blue
+  tft.fillScreen(TFT_BLUE);
+}
+
+void loop(void)
+{
+  // Fill the whole sprite with color 5 (Sprite is in memory so not visible yet)
+  spr.fillSprite(10);
+
+   // create a color map with known colors
+  uint16_t cmap[16];
+
+
+  cmap[0] = TFT_BLACK;
+  cmap[1] = TFT_NAVY;
+  cmap[2] = TFT_DARKGREEN;
+  cmap[3] = TFT_DARKCYAN;
+  cmap[4] = TFT_MAROON;
+  cmap[5] = TFT_PURPLE;
+  cmap[6] = TFT_OLIVE;
+  cmap[7] = TFT_LIGHTGREY;
+  cmap[8] = TFT_DARKGREY;
+  cmap[9] = TFT_BLUE;
+  cmap[10] = TFT_GREEN;
+  cmap[11] = TFT_CYAN;
+  cmap[12] = TFT_RED;
+  cmap[13] = TFT_MAGENTA;
+  cmap[14] = TFT_YELLOW;
+  cmap[15] = TFT_WHITE;
+
+  spr.createPalette(cmap, 16);
+ 
+  spr.pushSprite(-40, -40);
+  spr.pushSprite(tft.width() / 2 - WIDTH / 2, tft.height() / 2 - HEIGHT / 2, 10);
+  spr.pushSprite(tft.width() - WIDTH + 40, tft.height() - HEIGHT + 40);
+
+  // Number of pixels to draw
+  uint16_t n = 100;
+  // Draw 100 random color pixels at random positions in sprite
+  while (n--)
+  {
+    uint16_t color = random(0x10); // Returns color 0 - 0x0F
+    int16_t x = random(WIDTH);        // Random x coordinate
+    int16_t y = random(HEIGHT);       // Random y coordinate
+    spr.drawPixel( x, y, color);      // Draw pixel in sprite
+  }
+
+  spr.pushSprite(-40, -40);
+  spr.pushSprite(tft.width() / 2 - WIDTH / 2, tft.height() / 2 - HEIGHT / 2);
+  spr.pushSprite(tft.width() - WIDTH + 40, tft.height() - HEIGHT + 40);
+
+  delay(DELAY);
+
+  // Draw some lines
+  spr.drawLine(1, 0, WIDTH, HEIGHT-1, 6);
+  spr.drawLine(0, 0, WIDTH, HEIGHT, 6);
+  spr.drawLine(0, 1, WIDTH-1, HEIGHT, 2);
+  spr.drawLine(0, HEIGHT-1, WIDTH-1, 0, 2);
+  spr.drawLine(0, HEIGHT, WIDTH, 0, 3);
+  spr.drawLine(1, HEIGHT, WIDTH, 1, 3);
+  spr.drawLine(4, 0, 4, HEIGHT-1, 11);
+  spr.drawLine(0, 16, WIDTH-1, 16, 13);
+
+  // draw some circles with random colors.
+  spr.drawCircle(20, 60, 10, 6);
+  spr.drawCircle(80, 60, 15, 7);
+  spr.drawCircle(50, 108, 5, 9);
+  spr.drawCircle(45, 86, 3, 8);
+  spr.fillCircle(102, 56, 4, 11);
+
+  spr.fillRect(28, 32, 40, 4, 5);
+  //spr.fillRect(27, 42, 40, 14, 6);
+  //spr.fillRect(33, 55, 3, 4, 7);
+  //spr.fillRect(34, 32, 7, 4, 8);
+
+ // Draw some text with Middle Centre datum
+  spr.setTextDatum(MC_DATUM);
+  spr.drawString("Sprite", WIDTH / 2, HEIGHT / 2, 1);
+
+  // Now push the sprite to the TFT at position 0,0 on screen
+  spr.pushSprite(-40, -40);
+  spr.pushSprite(tft.width() / 2 - WIDTH / 2, tft.height() / 2 - HEIGHT / 2);
+  spr.pushSprite(tft.width() - WIDTH + 40, tft.height() - HEIGHT + 40);
+
+  delay(DELAY * 4);
+
+  // create a new color map and use it instead
+
+  for (auto i = 0; i < 16; i++)
+  {
+    cmap[i] = random(0x10000);
+  }
+
+  spr.createPalette(cmap, 16);
+  // Now push the sprite to the TFT at position 0,0 on screen
+
+  spr.pushSprite(-40, -40);
+  spr.pushSprite(tft.width() / 2 - WIDTH / 2, tft.height() / 2 - HEIGHT / 2);
+  spr.pushSprite(tft.width() - WIDTH + 40, tft.height() - HEIGHT + 40);
+
+  delay(DELAY);
+
+    // Fill TFT screen with blue
+  tft.fillScreen(TFT_BLUE);
+
+  // Draw a blue rectangle in sprite so when we move it 1 pixel it does not leave a trail
+  // on the blue screen background
+  cmap[14] = TFT_BLUE;
+  spr.createPalette(cmap, 16);
+
+  spr.drawRect(0, 0, WIDTH, HEIGHT, 14);
+
+  int x = tft.width() / 2  -  WIDTH / 2;
+  int y = tft.height() / 2 - HEIGHT / 2;
+
+  uint32_t updateTime = 0;       // time for next update
+
+  while (true)
+  {
+    // Random movement direction
+    int dx = 1; if (random(2)) dx = -1;
+    int dy = 1; if (random(2)) dy = -1;
+
+    // Pull it back onto screen if it wanders off
+    if (x < -WIDTH/2) dx = 1;
+    if (x >= tft.width()-WIDTH/2) dx = -1;
+    if (y < -HEIGHT/2) dy = 1;
+    if (y >= tft.height()-HEIGHT/2) dy = -1;
+
+    // Draw it 50 time, moving in random direct or staying still
+    n = 50;
+    int wait = random (50);
+    while (n)
+    {
+      if (updateTime <= millis())
+      {
+        // Use time delay so sprite does not move fast when not all on screen
+        updateTime = millis() + wait;
+
+        // Push the sprite to the TFT screen
+          spr.pushSprite(x, y);
+
+        // Change coord for next loop
+        x += dx;
+        y += dy;
+        n--;
+        yield(); // Stop watchdog reset
+      }
+    }
+  } // Infinite while, will not exit!
+}
+

examples/Sprite/Sprite_scroll_cmap/Sprite_scroll_cmap.ino

+/*
+  Sketch to show scrolling of the graphics in sprites.
+  Scrolling in this way moves the pixels in a defined rectangle
+  within the Sprite. By defalt the whole sprite is scrolled.
+  The gap left by scrolling is filled with a defined colour.
+
+  Example for library:
+  https://github.com/Bodmer/TFT_eSPI
+
+  A Sprite is notionally an invisible graphics screen that is
+  kept in the processors RAM. Graphics can be drawn into the
+  Sprite just as it can be drawn directly to the screen. Once
+  the Sprite is completed it can be plotted onto the screen in
+  any position. If there is sufficient RAM then the Sprite can
+  be the same size as the screen and used as a frame buffer.
+
+  A 16 bit Sprite occupies (2 * width * height) bytes in RAM.
+
+  An 8 bit Sprite occupies (width * height) bytes in RAM.
+
+*/
+
+#include <TFT_eSPI.h>
+
+TFT_eSPI tft = TFT_eSPI();
+
+TFT_eSprite graph1 = TFT_eSprite(&tft); // Sprite object graph1
+
+TFT_eSprite stext1 = TFT_eSprite(&tft); // Sprite object stext1
+
+TFT_eSprite stext2 = TFT_eSprite(&tft); // Sprite object stext2
+
+int graphVal = 1;
+int delta = 1;
+int grid = 0;
+int tcount = 0;
+
+uint16_t cmap[16];
+
+//==========================================================================================
+void setup() {
+  Serial.begin(250000);
+  tft.init();
+  tft.fillScreen(TFT_BLACK);
+
+  cmap[0] = TFT_BLACK;
+  cmap[1] = TFT_ORANGE;
+  cmap[2] = TFT_DARKGREEN;
+  cmap[3] = TFT_DARKCYAN;
+  cmap[4] = TFT_MAROON;
+  cmap[5] = TFT_PURPLE;
+  cmap[6] = TFT_OLIVE;
+  cmap[7] = TFT_DARKGREY;
+  cmap[8] = TFT_ORANGE;
+  cmap[9] = TFT_BLUE;
+  cmap[10] = TFT_GREEN;
+  cmap[11] = TFT_CYAN;
+  cmap[12] = TFT_RED;
+  cmap[13] = TFT_NAVY;
+  cmap[14] = TFT_YELLOW;
+  cmap[15] = TFT_WHITE; 
+
+  // Create a sprite for the graph
+  graph1.setColorDepth(4);
+  graph1.createSprite(128, 61);
+  graph1.createPalette(cmap, 16);
+  graph1.fillSprite(9); // Note: Sprite is filled with black when created
+
+  // The scroll area is set to the full sprite size upon creation of the sprite
+  // but we can change that by defining a smaller area using "setScrollRect()"if needed
+  // parameters are x,y,w,h,color as in drawRect(), the color fills the gap left by scrolling
+  //graph1.setScrollRect(64, 0, 64, 61, TFT_DARKGREY);  // Try this line to change the graph scroll area
+
+  // Create a sprite for the scrolling numbers
+  stext1.setColorDepth(4);
+  stext1.createSprite(32, 64);
+  stext1.createPalette(cmap, 16);
+  stext1.fillSprite(9); // Fill sprite with blue
+  stext1.setScrollRect(0, 0, 32, 64, 9);     // here we set scroll gap fill color to blue
+  stext1.setTextColor(15); // White text, no background
+  stext1.setTextDatum(BR_DATUM);  // Bottom right coordinate datum
+
+  // Create a sprite for Hello World
+  stext2.setColorDepth(4);
+  stext2.createSprite(80, 16);
+  stext2.createPalette(cmap, 16);
+  stext2.fillSprite(7);
+  stext2.setScrollRect(0, 0, 40, 16, 7); // Scroll the "Hello" in the first 40 pixels
+  stext2.setTextColor(15); // White text, no background
+}
+
+//==========================================================================================
+void loop() {
+  // Draw point in graph1 sprite at far right edge (this will scroll left later)
+  graph1.drawFastVLine(127,60-graphVal,2,14); // draw 2 pixel point on graph
+
+  // Draw number in stext1 sprite at 31,63 (bottom right datum set)
+  stext1.drawNumber(graphVal, 31, 63, 2); // plot value in font 2
+
+  // Push the sprites onto the TFT at specied coordinates
+  graph1.pushSprite(0, 0);
+  stext1.pushSprite(0, 64);
+  stext2.pushSprite(40, 70);
+
+  // Change the value to plot
+  graphVal+=delta;
+
+  // If the value reaches a limit, then change delta of value
+  if (graphVal >= 60)     delta = -1;  // ramp down value
+  else if (graphVal <= 1) delta = +1;  // ramp up value
+
+  delay(50); // wait so things do not scroll too fast
+
+  // Now scroll the sprites scroll(dt, dy) where:
+  // dx is pixels to scroll, left = negative value, right = positive value
+  // dy is pixels to scroll, up = negative value, down = positive value
+  graph1.scroll(-1, 0); // scroll graph 1 pixel left, 0 up/down
+  stext1.scroll(0,-16); // scroll stext 0 pixels left/right, 16 up
+  stext2.scroll(1);     // scroll stext 1 pixel right, up/down default is 0
+
+  // Draw the grid on far right edge of sprite as graph has now moved 1 pixel left
+  grid++;
+  if (grid >= 10)
+  { // Draw a vertical line if we have scrolled 10 times (10 pixels)
+    grid = 0;
+    graph1.drawFastVLine(127, 0, 61, 13); // draw line on graph
+  }
+  else
+  { // Otherwise draw points spaced 10 pixels for the horizontal grid lines
+    for (int p = 0; p <= 60; p += 10) graph1.drawPixel(127, p, 13);
+  }
+
+  tcount--;
+  if (tcount <=0)
+  { // If we have scrolled 40 pixels the redraw text
+    tcount = 40;
+    stext2.drawString("Hello World", 6, 0, 2); // draw at 6,0 in sprite, font 2
+  }
+
+} // Loop back and do it all again
+//==========================================================================================

examples/Sprite/Transparent_Sprite_Demo_Colormap/Transparent_Sprite_Demo_Colormap.ino

+/*
+  Sketch to show creation of a sprite with a transparent
+  background, then plot it on the TFT.
+
+  Example for library:
+  https://github.com/Bodmer/TFT_eSPI
+
+  A Sprite is notionally an invisible graphics screen that is
+  kept in the processors RAM. Graphics can be drawn into the
+  Sprite just as it can be drawn directly to the screen. Once
+  the Sprite is completed it can be plotted onto the screen in
+  any position. If there is sufficient RAM then the Sprite can
+  be the same size as the screen and used as a frame buffer.
+
+  A 16 bit Sprite occupies (2 * width * height) bytes in RAM.
+
+  On a ESP8266 Sprite sizes up to 126 x 160 can be accomodated,
+  this size requires 40kBytes of RAM for a 16 bit colour depth.
+  
+  When 8 bit colour depth sprites are created they occupy
+  (width * height) bytes in RAM, so larger sprites can be
+  created, or the RAM required is halved.
+*/
+
+#include <TFT_eSPI.h>                 // Include the graphics library (this includes the sprite functions)
+
+TFT_eSPI    tft = TFT_eSPI();         // Create object "tft"
+
+TFT_eSprite img = TFT_eSprite(&tft);  // Create Sprite object "img" with pointer to "tft" object
+                                      // the pointer is used by pushSprite() to push it onto the TFT
+
+TFT_eSprite img2 = TFT_eSprite(&tft);
+
+void setup(void) {
+  Serial.begin(250000);
+
+  tft.init();
+
+  tft.setRotation(0);
+}
+
+void loop() {
+
+  tft.fillScreen(TFT_NAVY);
+
+  img.setColorDepth(4);
+
+  // Draw 10 sprites containing a "transparent" colour
+  for (int i = 0; i < 10; i++)
+  {
+    int x = random(240-70);
+    int y = random(320-80);
+    int c = random(0x0F); // Random colour (4 bit index into color map).  Leave 15 for transparent.
+    drawStar(x, y, c);  // note: not random; should be c
+  }
+  
+  delay(2000);
+
+  uint32_t dt = millis();
+
+  // Now go bananas and draw 500 nore
+  for (int i = 0; i < 500; i++)
+  {
+    int x = random(240-70);
+    int y = random(320-80);
+    int c = random(0x10); // Random colour
+    drawStar(x, y, c);
+    yield(); // Stop watchdog reset
+  }
+
+  // Show time in milliseconds to draw and then push 1 sprite to TFT screen
+  numberBox( 10, 10, (millis()-dt)/500.0 );
+  delay(2000);
+
+}
+
+// #########################################################################
+// Create sprite, plot graphics in it, plot to screen, then delete sprite
+// #########################################################################
+void drawStar(int x, int y, int star_color)
+{
+  // Create an 8 bit sprite 70x 80 pixels (uses 5600 bytes of RAM)
+  img.setColorDepth(4);
+  img.createSprite(70, 80);
+
+  uint16_t cmap[16];
+
+  cmap[0] = TFT_BLACK;
+  cmap[1] = TFT_ORANGE;
+  cmap[2] = TFT_DARKGREEN;
+  cmap[3] = TFT_DARKCYAN;
+  cmap[4] = TFT_MAROON;
+  cmap[5] = TFT_PURPLE;
+  cmap[6] = TFT_OLIVE;
+  cmap[7] = TFT_LIGHTGREY;
+  cmap[8] = TFT_DARKGREY;
+  cmap[9] = TFT_BLUE;
+  cmap[10] = TFT_GREEN;
+  cmap[11] = TFT_CYAN;
+  cmap[12] = TFT_RED;
+  cmap[13] = TFT_MAGENTA;
+  cmap[14] = TFT_YELLOW;
+  cmap[15] = TFT_WHITE; // this one will be transparent.
+
+  img.createPalette(cmap, 16);
+
+  // Fill Sprite with a "transparent" colour
+  // TFT_TRANSPARENT is already defined for convenience
+  // We could also fill with any colour as "transparent" and later specify that
+  // same colour when we push the Sprite onto the screen.
+  img.fillSprite(15);
+
+  // Draw 2 triangles to create a filled in star
+  img.fillTriangle(35, 0, 0,59, 69,59, star_color);
+  img.fillTriangle(35,79, 0,20, 69,20, star_color);
+
+  // Punch a star shaped hole in the middle with a smaller transparent star
+  // this one damages on pixel in the second triangle
+  img.fillTriangle(35, 7, 6,56, 63,56, 15);
+  img.fillTriangle(35,73, 6,24, 63,24, 15);
+
+  // Push sprite to TFT screen at coordinate x,y (top left corner)
+  // Specify what colour from the map is to be treated as transparent.
+  img.pushSprite(x, y, 15);
+
+  // Delete it to free memory
+  img.deleteSprite();
+}
+
+// #########################################################################
+// Draw a number in a rounded rectangle with some transparent pixels
+// #########################################################################
+void numberBox(int x, int y, float num )
+{
+
+  // Size of sprite
+  #define IWIDTH  80
+  #define IHEIGHT 35
+
+  // Create a 8 bit sprite 80 pixels wide, 35 high (2800 bytes of RAM needed)
+  img.setColorDepth(8);
+  img.createSprite(IWIDTH, IHEIGHT);
+
+  // Fill it with black (this will be the transparent colour this time)
+  img.fillSprite(TFT_BLACK);
+
+  // Draw a background for the numbers
+  img.fillRoundRect(  0, 0,  80, 35, 15, TFT_RED);
+  img.drawRoundRect(  0, 0,  80, 35, 15, TFT_WHITE);
+
+  // Set the font parameters
+  img.setTextSize(1);           // Font size scaling is x1
+  img.setTextColor(TFT_WHITE);  // White text, no background colour
+
+  // Set text coordinate datum to middle right
+  img.setTextDatum(MR_DATUM);
+
+  // Draw the number to 3 decimal places at 70,20 in font 4
+  img.drawFloat(num, 3, 70, 20, 4);
+
+  // Push sprite to TFT screen CGRAM at coordinate x,y (top left corner)
+  // All black pixels will not be drawn hence will show as "transparent"
+  img.pushSprite(x, y, TFT_BLACK);
+
+  // Delete sprite to free up the RAM
+  img.deleteSprite();
+}
+