Add viewport feature

2 new example sketches added for viewport demonstration

Extensions/Sprite.cpp

@@ -843,9 +843,9 @@ bool TFT_eSprite::pushSprite(int32_t tx, int32_t ty, int32_t sx, int32_t sy, int
       _tft->pushImage(tx, ty, sw, sh, _img4 + (_iwidth>>1) * _ys, false, _colorMap );
     else // Render line by line
     {
-      uint32_t ds = _xs&1; // Odd x start pixel
+      int32_t ds = _xs&1; // Odd x start pixel
 
-      uint32_t de = 0;     // Odd x end pixel
+      int32_t de = 0;     // Odd x end pixel
       if ((sw > ds) && (_xe&1)) de = 1;
 
       uint32_t dm = 0;     // Midsection pixel count
@@ -877,7 +877,7 @@ bool TFT_eSprite::pushSprite(int32_t tx, int32_t ty, int32_t sx, int32_t sy, int
       _tft->setWindow(tx, ty, tx+sw-1, ty+sh-1);
       while (sh--)
       {
-        for (uint32_t dx = _xs; dx < _xs + sw; dx++) _tft->pushColor(readPixel(dx, _ys));
+        for (int32_t dx = _xs; dx < _xs + sw; dx++) _tft->pushColor(readPixel(dx, _ys));
         ty++;
         _ys++;
       }

TFT_eSPI.h

@@ -16,7 +16,7 @@
 #ifndef _TFT_eSPIH_
 #define _TFT_eSPIH_
 
-#define TFT_ESPI_VERSION "2.2.23"
+#define TFT_ESPI_VERSION "2.3.0"
 
 /***************************************************************************************
 **                         Section 1: Load required header files
@@ -390,6 +390,13 @@ class TFT_eSPI : public Print {
   void     setAddrWindow(int32_t xs, int32_t ys, int32_t w, int32_t h), // Note: start coordinates + width and height
            setWindow(int32_t xs, int32_t ys, int32_t xe, int32_t ye);   // Note: start + end coordinates
 
+  // Viewport commands, see "Viewport_Demo" sketch
+  void     setViewport(int32_t x, int32_t y, int32_t w, int32_t h, bool vpDatum = true);
+  int32_t  getViewportWidth(void);
+  int32_t  getViewportHeight(void);
+  void     frameViewport(uint16_t color, int32_t w);
+  void     resetViewport(void);
+
   // Push (aka write pixel) colours to the TFT (use setAddrWindow() first)
   void     pushColor(uint16_t color),
            pushColor(uint16_t color, uint32_t len),  // Deprecated, use pushBlock()
@@ -728,6 +735,12 @@ class TFT_eSPI : public Print {
   int32_t  _width, _height;           // Display w/h as modified by current rotation
   int32_t  addr_row, addr_col;        // Window position - used to minimise window commands
 
+  // Viewport variables
+  int32_t  _vpX, _vpY, _vpW, _vpH;
+  int32_t  _xDatum;
+  int32_t  _yDatum;
+  bool     _vpDatum;
+
   uint32_t fontsloaded;               // Bit field of fonts loaded
 
   uint8_t  glyph_ab,   // Smooth font glyph delta Y (height) above baseline

User_Setups/Setup50_SSD1963_Parallel.h

@@ -20,7 +20,10 @@
 //#define SSD1963_480_DRIVER    // 272 x 480 display
 //#define SSD1963_800_DRIVER    // 480 x 800 display
 //#define SSD1963_800ALT_DRIVER // Alternative 480 x 800 display
-#define SSD1963_800BD_DRIVER    // 480 x 800 displau sourced from https://www.buydisplay.com/7-tft-screen-touch-lcd-display-module-w-ssd1963-controller-board-mcu
+#define SSD1963_800BD_DRIVER    // 480 x 800 display sourced from https://www.buydisplay.com/7-tft-screen-touch-lcd-display-module-w-ssd1963-controller-board-mcu
+
+//#define TFT_RGB_ORDER TFT_RGB  // Colour order Red-Green-Blue
+#define TFT_RGB_ORDER TFT_BGR  // Colour order Blue-Green-Red
 
 // ##################################################################################
 //

examples/320 x 240/TFT_Starfield/TFT_Starfield.ino

@@ -20,7 +20,7 @@ uint8_t __attribute__((always_inline)) rng()
   zx++;
   za = (za^zc^zx);
   zb = (zb+za);
-  zc = (zc+(zb>>1)^za);
+  zc = ((zc+(zb>>1))^za);
   return zc;
 }
 

examples/Viewport_Demo/Viewport_Demo.ino

+// Viewport Demo
+
+// See viewport_commands tab
+
+// This example uses the viewport commands to create a "virtual TFT" within the
+// normal TFT display area. This allows a sketch written for a smaller screen to
+// be run in a viewport window. By default, the graphics 0,0 datum is set to the
+// top left corner of the viewport, but optionally the datum can be kept at the
+// corner of the TFT.
+
+// Viewports have a number of potential uses:
+// -  create a "virtual" TFT screen smaller than the actual TFT screen
+//  - render GUI items (menus etc) in a viewport, erase GUI item by redrawing whole screen,
+//    this will be fast because only the viewport will be refreshed (e.g. clearing menu)
+//  - limit screen refresh to a particular area, e.g. changing numbers, icons or graph plotting
+//  - showing a small portion of a larger image or sprite, this allows panning and scrolling
+
+// A viewport can have the coordinate datum (position 0,0) either at the top left corner of
+// the viewport or at the normal top left corner of the TFT.
+// Putting the coordinate datum at the viewport corner means that functions that draw graphics
+// in a fixed position can be relocated anywhere on the screen. (see plotShapes() below). This
+// makes it easier to reposition groupd of graphical ojects (for example GUI buttons) that have
+// fixed relative positions.
+
+// The viewport position x, and y coordinates and viewport bounds must be constrained by the
+// user sketch to be within the screen boundaries.
+
+#include <SPI.h>
+#include <TFT_eSPI.h>
+
+TFT_eSPI tft = TFT_eSPI();
+
+void setup() {
+  Serial.begin(115200);
+
+  tft.init();
+  tft.setRotation(1);
+  tft.fillScreen(TFT_BLACK);
+
+
+/*
+  tft.setViewport(VP_X, VP_Y, VP_W, VP_H); // By default the 0,0 coordinate datum is 
+                                           // moved to top left corner of viewport
+                                           // Note: tft.width() and tft.height() now return viewport size
+  // Other command options:
+  //tft.setViewport(VP_X, VP_Y, VP_W, VP_H, true); // Explicitly set datum to viewport corner
+
+  //tft.setViewport(VP_X, VP_Y, VP_W, VP_H, false); // Create viewport but datum stays at TFT corner
+                                                    // Note: tft.width() and tft.height() now return TFT size
+
+  w = tft.getViewportWidth();  // Always returns width of viewport
+  h = tft.getViewportHeight(); // Always returns height of viewport
+
+  tft.frameViewport(TFT_GREEN, -2); // Draw a rectangle of width 2 outside (negative width) viewport
+  tft.frameViewport(TFT_RED,   10); // Draw a rectangle of width 10 inside (positive width) viewport
+
+  // tft.resetViewport(); // Command to reset viewport to "normal" full TFT screen
+                          // Graphics will not be drawn to the TFT outside a viewport until
+                          // this command is used!
+
+  // tft.setRotation(2);  // Using setRotation rotates the whole TFT screen it does not just
+                          // rotate the viewport (this is a possible future enhancement).
+                          // Redraw all graphics after a rotation since some TFT's do not
+                          // re-map the TFT graphics RAM to the screen pixels as expected.
+  delay(1000);
+  */
+}
+
+void loop()
+{
+  // Normal Screen
+  drawX();
+
+  delay(2000);
+
+  // Viewport screen
+  tft.setViewport(10, 10, 140, 100);
+  tft.frameViewport(TFT_NAVY, -2);
+  tft.fillScreen(TFT_BLACK);
+  drawX();
+  tft.resetViewport();
+
+  delay(2000);
+
+  //Normal screen
+  tft.fillScreen(TFT_BLACK);
+  drawX();
+
+  delay(2000);
+
+  tft.fillScreen(TFT_BLACK);
+
+  // Viewport as a clipping window (false parameter means coordinate datum stays at TFT top left)
+  tft.setViewport(10, 10, tft.width()/2 - 10, tft.height() - 20, false);
+  //tft.frameViewport(TFT_NAVY,  2); // Add 2 pixel border inside viewport
+  //tft.frameViewport(TFT_NAVY, -2); // Add 2 pixel border outside viewport
+  drawX();
+
+  delay(2000);
+
+  while(1)
+  {
+    tft.resetViewport(); // Reset viewport so width() and height() return TFT size
+
+    uint16_t w = 40;
+    uint16_t h = 40;
+    uint16_t x = random(tft.width()  - w);
+    uint16_t y = random(tft.height() - h);
+
+    tft.setViewport(x, y, w, h);
+
+    plotBox();
+  }
+}
+
+void drawX(void)
+{
+  tft.fillScreen(tft.color565(25,25,25)); // Grey
+
+  // Draw circle
+  tft.drawCircle(tft.width()/2, tft.height()/2, tft.width()/4, TFT_RED);
+
+  // Draw diagonal lines
+  tft.drawLine(0 ,                0, tft.width()-1, tft.height()-1, TFT_GREEN);
+  tft.drawLine(0 , tft.height()-1, tft.width()-1,                0, TFT_BLUE);
+
+  tft.setTextDatum(MC_DATUM);
+  tft.setTextColor(TFT_WHITE, tft.color565(25,25,25));
+  tft.drawString("Hello World!", tft.width()/2, tft.height()/2, 4); // Font 4
+}
+
+void plotBox(void)
+{
+  // These are always plotted at a fixed position but they can 
+  // be plotted into a viewport anywhere on the screen because
+  // a viewport can move the screen datum
+  tft.fillScreen(TFT_BLACK); // When a viewport is set, this just fills the viewport
+  tft.drawRect(0,0, 40,40, TFT_BLUE);
+  tft.setTextDatum(MC_DATUM);
+  tft.setTextColor(TFT_WHITE);
+  tft.drawNumber( random(100), 20, 23, 4);
+}

examples/Viewport_Demo/Viewport_commands.ino

+/*  
+
+  // Create a viewport at TFT screen coordinated X,y of width W and height H
+  tft.setViewport(X, Y, W, H); // By default the 0,0 coordinate datum is moved to top left
+                               // corner of viewport
+                               // Note: tft.width() and tft.height() now return viewport size!
+  // The above command is identical to:
+  tft.setViewport(VP_X, VP_Y, VP_W, VP_H, true); // true parameter is optional
+
+  // To create a viewport that keeps the coordinate datum at top left of TFT, use false parameter
+  tft.setViewport(VP_X, VP_Y, VP_W, VP_H, false); // Note: tft.width() and tft.height() return TFT size!
+
+  // To get width of viewport
+  uint16_t w = tft.getViewportWidth();  // Always returns width of viewport
+
+  // To get height of viewport
+  uint16_t h = tft.getViewportHeight(); // Always returns height of viewport
+
+  // To draw a rectangular frame outside viewport of width W (when W is negative)
+  tft.frameViewport(TFT_RED, -W); // Note setting the width to a large negative value will clear the screen
+                                  // outside the viewport
+
+  // To draw a rectangular frame inside viewport of width W (when W is positive)
+  tft.frameViewport(TFT_RED,  W); // Note setting the width to a large positive value will clear the screen
+                                  // inside the viewport
+
+  // To reset the viewport to the normal TFT full screen
+  tft.resetViewport();  // Note: Graphics will NOT be drawn to the TFT outside a viewport until
+                        // this command is used! ( The exception is using the frameViewport command
+                        // detailed above with a negative width.)
+
+
+*/

keywords.txt

@@ -17,6 +17,11 @@ getRotation	KEYWORD2
 invertDisplay	KEYWORD2
 setAddrWindow	KEYWORD2
 setWindow	KEYWORD2
+setViewport	KEYWORD2
+resetViewport	KEYWORD2
+getViewportWidth	KEYWORD2
+getViewportHeight	KEYWORD2
+frameViewport	KEYWORD2
 pushColor	KEYWORD2
 pushColors	KEYWORD2
 pushBlock	KEYWORD2

library.json

 {
   "name": "TFT_eSPI",
-  "version": "2.2.23",
+  "version": "2.3.0",
   "keywords": "Arduino, tft, ePaper, display, STM32, ESP8266, NodeMCU, ESP32, M5Stack, ILI9341, ST7735, ILI9163, S6D02A1, ILI9486, ST7789, RM68140",
   "description": "A TFT and ePaper SPI graphics library with optimisation for ESP8266, ESP32 and STM32",
   "repository":

library.properties

 name=TFT_eSPI
-version=2.2.23
+version=2.3.0
 author=Bodmer
 maintainer=Bodmer
 sentence=TFT graphics library for Arduino processors with performance optimisation for STM32, ESP8266 and ESP32