Finalise viewport changes

README.md

@@ -2,23 +2,24 @@
 The Sprite class has been updated to remove an inconsistency for the setSwapBytes() function. Although all the examples are unchanged, user sketches may be affected. If the colors of the sprite change when loading this new version 2.2.16 then it may be necessary to change the swap bytes setting, e.g. for a sprite instance "spr" use either: spr.setSwapBytes(true) or spr.setSwapBytes(false) to correct the colour.
 
 # News
-1. A companion library [U8g2_for_TFT_eSPI](https://github.com/Bodmer/U8g2_for_TFT_eSPI) has been created to allow U8g2 library fonts to be used with TFT_eSPI.
+1. The library now provides a "viewport" capability. See "Viewport_Demo" and "Viewport_graphicstest" examples. When a viewport is defined grpahics will only appear within that window.  The coordinate datum by default moves to the top left corner of the viewport, but can optionally remain at top left corner of TFT. The GUIslice library will make use of this feature to spped up the rendering of GUI objects (see #769).
 
-2. The library now supports SPI DMA transfers for both ESP32 and STM32 processors. The DMA Test examples now work on the ESP32 for SPI displays (excluding RPi type and ILI9488).
+2. The library now supports SSD1963 based screen, this has been tested on a [480x800 screen](https://www.buydisplay.com/7-tft-screen-touch-lcd-display-module-w-ssd1963-controller-board-mcu) with an ESP32. The interface is 8 bit parallel only as that controller does not support a SPI interface.
 
-3. A new option has been added for STM32 processors to optimise performance where Port A (or B) pins 0-7 are used for the 8 bit parallel interface data pins 0-7 to the TFT. This gives a dramatic 8 times better rendering performance for the lower clock rate STM32 processors such as the STM32F103 "Blue Pill" or STM411 "Black Pill" since no time consuming data bit manipulation is required. See setup file "User_Setups/Setup35_ILI9341_STM32_Port_Bus.h".
+3. A companion library [U8g2_for_TFT_eSPI](https://github.com/Bodmer/U8g2_for_TFT_eSPI) has been created to allow U8g2 library fonts to be used with TFT_eSPI.
 
-4. A new "Animated_dial" example has been added to show how dials can be created using a rotated Sprite for the needle. To run this example the TFT must support reading from the screen RAM. The dial rim and scale is a jpeg image, created using a paint program.
+4. The library now supports SPI DMA transfers for both ESP32 and STM32 processors. The DMA Test examples now work on the ESP32 for SPI displays (excluding RPi type and ILI9488).
+
+5. A new option has been added for STM32 processors to optimise performance where Port A (or B) pins 0-7 are used for the 8 bit parallel interface data pins 0-7 to the TFT. This gives a dramatic 8 times better rendering performance for the lower clock rate STM32 processors such as the STM32F103 "Blue Pill" or STM411 "Black Pill" since no time consuming data bit manipulation is required. See setup file "User_Setups/Setup35_ILI9341_STM32_Port_Bus.h".
+
+6. A new "Animated_dial" example has been added to show how dials can be created using a rotated Sprite for the needle. To run this example the TFT must support reading from the screen RAM. The dial rim and scale is a jpeg image, created using a paint program.
 
       ![Animated_dial](https://i.imgur.com/S736Rg6.png)
 
-5. Anti-aliased (smooth) fonts can now be stored as arrays in FLASH (program) memory. This means that processors such as STM32 that do not have SPIFFS support can use the fonts. The processor must have sufficient FLASH memory to store the fonts used.
+7. Anti-aliased (smooth) fonts can now be stored as arrays in FLASH (program) memory. This means that processors such as STM32 that do not have SPIFFS support can use the fonts. The processor must have sufficient FLASH memory to store the fonts used.
 
-6. The Sprite class now supports 4 bits per pixel with a 16 color palette. Three new examples have been added.
+8. The Sprite class now supports 4 bits per pixel with a 16 color palette. Three new examples have been added.
 
-7. The library has been upgraded to support STM32 processors when used with SPI or 8 bit parallel displays. DMA capability for SPI displays has been added for STM32F103 (e.g. "Blue Pill") and STM32F2xx/4xx/7xx (e.g. 32/64/144 Nucleo boards). New DMA demo examples have been added (for STM32 only).
-
-8. The ST7796 display controller has been added. The ST7796 RPi MHS-4.0 inch Display-B type display is supported (this is fast for a SPI display as an ESP32 can clock it at 80MHz (ESP8266 at 40MHz)), see setups 27 and 28.
 
 # TFT_eSPI
 

TFT_eSPI.cpp

@@ -170,6 +170,35 @@ void TFT_eSPI::setViewport(int32_t x, int32_t y, int32_t w, int32_t h, bool vpDa
 
 }
 
+/***************************************************************************************
+** Function name:           checkViewport
+** Description:             Check if any part of specified area is visible in viewport
+***************************************************************************************/
+// Note: Setting w and h to 1 will check if coordinate x,y is in area
+bool TFT_eSPI::checkViewport(int32_t x, int32_t y, int32_t w, int32_t h)
+{
+  if (_vpOoB) return false;
+  x+= _xDatum;
+  y+= _yDatum;
+
+  if ((x >= _vpW) || (y >= _vpH)) return false; 
+
+  int32_t dx = 0;
+  int32_t dy = 0;
+  int32_t dw = w;
+  int32_t dh = h;
+
+  if (x < _vpX) { dx = _vpX - x; dw -= dx; x = _vpX; }
+  if (y < _vpY) { dy = _vpY - y; dh -= dy; y = _vpY; }
+
+  if ((x + dw) > _vpW ) dw = _vpW - x;
+  if ((y + dh) > _vpH ) dh = _vpH - y;
+
+  if (dw < 1 || dh < 1) return false;
+
+  return true;
+}
+
 /***************************************************************************************
 ** Function name:           resetViewport
 ** Description:             Reset viewport to whle TFT screen, datum at 0,0
@@ -190,6 +219,24 @@ void TFT_eSPI::resetViewport(void)
   _vpOoB   = false;
 }
 
+/***************************************************************************************
+** Function name:           getViewportX
+** Description:             Get x position of the viewport
+***************************************************************************************/
+int32_t  TFT_eSPI::getViewportX(void)
+{
+  return _xDatum;
+}
+
+/***************************************************************************************
+** Function name:           getViewportY
+** Description:             Get y position of the viewport
+***************************************************************************************/
+int32_t  TFT_eSPI::getViewportY(void)
+{
+  return _yDatum;
+}
+
 /***************************************************************************************
 ** Function name:           getViewportWidth
 ** Description:             Get width of the viewport
@@ -208,6 +255,15 @@ int32_t TFT_eSPI::getViewportHeight(void)
   return _vpH - _vpY;
 }
 
+/***************************************************************************************
+** Function name:           getViewportDatum
+** Description:             Get datum of the viewport (true = viewport corner)
+***************************************************************************************/
+bool  TFT_eSPI::getViewportDatum(void)
+{
+  return _vpDatum;
+}
+
 /***************************************************************************************
 ** Function name:           frameViewport
 ** Description:             Draw a frame inside or outside the viewport of width w

TFT_eSPI.h

@@ -16,7 +16,11 @@
 #ifndef _TFT_eSPIH_
 #define _TFT_eSPIH_
 
-#define TFT_ESPI_VERSION "2.3.1"
+#define TFT_ESPI_VERSION "2.3.2"
+
+// Bit level feature flags
+// Bit 0 set: viewport capability
+#define TFT_ESPI_FEATURES 1
 
 /***************************************************************************************
 **                         Section 1: Load required header files
@@ -392,8 +396,12 @@ class TFT_eSPI : public Print {
 
   // Viewport commands, see "Viewport_Demo" sketch
   void     setViewport(int32_t x, int32_t y, int32_t w, int32_t h, bool vpDatum = true);
+  bool     checkViewport(int32_t x, int32_t y, int32_t w, int32_t h);
+  int32_t  getViewportX(void);
+  int32_t  getViewportY(void);
   int32_t  getViewportWidth(void);
   int32_t  getViewportHeight(void);
+  bool     getViewportDatum(void);
   void     frameViewport(uint16_t color, int32_t w);
   void     resetViewport(void);
 

examples/160 x 128/UTFT_demo_fast/UTFT_demo_fast.ino

@@ -311,7 +311,7 @@ void loop()
   // It takes 30ms to calculate the 30,000 random numbers so this is not a true drawPixel speed test
   for (int i=0; i<10000; i++)
   {
-    myGLCD.drawPixel(2+random(316), 16+random(209),random(0xFFFF));
+    myGLCD.drawPixel(2+random(TFT_W - 3), 16+random(TFT_H - 31),random(0xFFFF));
   }
 #else
   // Draw 10,000 pixels to fill a 100x100 pixel box, better drawPixel speed test

examples/Generic/Viewport_Demo/Viewport_Demo.ino

@@ -1,6 +1,6 @@
 // Viewport Demo
 
-// See viewport_commands tab
+// See viewport_commands tab for details of functions available
 
 // 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
@@ -36,34 +36,6 @@ void setup() {
   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()
@@ -140,5 +112,5 @@ void plotBox(void)
   tft.drawRect(0,0, 40,40, TFT_BLUE);
   tft.setTextDatum(MC_DATUM);
   tft.setTextColor(TFT_WHITE);
-  tft.drawNumber( random(100), 20, 23, 4);
+  tft.drawNumber( random(100), 20, 23, 4); // Number in font 4
 }

examples/Generic/Viewport_Demo/Viewport_commands.ino

@@ -1,6 +1,6 @@
 /*  
 
-  // Create a viewport at TFT screen coordinated X,y of width W and height H
+  // 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!
@@ -10,11 +10,14 @@
   // 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 get viewport x, y coordinates, width, height and datum position flag
+  int32_t x = tft.getViewportX();      // Always returns viewport x coordinate relative to screen left edge
+  int32_t y = tft.getViewportY(void);  // Always returns viewport y coordinate relative to screen top edge
+  int32_t w = tft.getViewportWidth();  // Always returns width of viewport
+  int32_t h = tft.getViewportHeight(); // Always returns height of viewport
+  bool    f = tft.getViewportDatum();  // Datum of the viewport (false = TFT corner, true = viewport corner)
+  // To check if all or part of an area is in the viewport
+  checkViewport(x, y, w, h); // Retruns "true" if all or part of area is in 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
@@ -29,5 +32,9 @@
                         // this command is used! ( The exception is using the frameViewport command
                         // detailed above with a negative width.)
 
-
-*/
+  // Note:
+  // 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.
+*/

examples/Generic/Viewport_graphicstest/Viewport_graphicstest.ino

@@ -1,7 +1,7 @@
 /*
  This sketch demonstrates the Adafruit graphicstest sketch running in a
  viewport (aka window) within the TFT screen area. To do this line 37 has
- been added. Line 38 outlines the viewport.
+ been added. Line 39 draws a frame outside the viewport.
 
  This sketch uses the GLCD font (font 1) only.
 
@@ -35,6 +35,7 @@ void setup() {
 
   // Create a viewport 220 x 300 pixels
   tft.setViewport(10,10,220,300);
+
   tft.frameViewport(TFT_RED, -1); // 1 pixel wide frame around viewport
 
   yield(); Serial.println(F("Benchmark                Time (microseconds)"));

keywords.txt

@@ -17,11 +17,16 @@ getRotation	KEYWORD2
 invertDisplay	KEYWORD2
 setAddrWindow	KEYWORD2
 setWindow	KEYWORD2
+
 setViewport	KEYWORD2
 resetViewport	KEYWORD2
+getViewportX	KEYWORD2
+getViewportY	KEYWORD2
 getViewportWidth	KEYWORD2
 getViewportHeight	KEYWORD2
+getViewportDatum	KEYWORD2
 frameViewport	KEYWORD2
+
 pushColor	KEYWORD2
 pushColors	KEYWORD2
 pushBlock	KEYWORD2

library.json

@@ -1,6 +1,6 @@
 {
   "name": "TFT_eSPI",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "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

@@ -1,5 +1,5 @@
 name=TFT_eSPI
-version=2.3.1
+version=2.3.2
 author=Bodmer
 maintainer=Bodmer
 sentence=TFT graphics library for Arduino processors with performance optimisation for STM32, ESP8266 and ESP32