Scrolling Text with Sprites example

[stevempotter]

I hammered away at the example in this library until I understood what it was doing. I paste below a new parameterized example with better comments and variable names that might be included in future versions?

I would guess that there are other ways to scroll text smoothly. Please point me to those if you know of them. This approach runs out of memory pretty easily.
And if you have any improvements to the code below, please post a reply!

// Example to show how to use the TFT_eSPI library to create banners of horizontally scrolling text.
// Steve M. Potter stevempotter.tech 11 May 2022
// Many thanks to Bodmer! https://github.com/Bodmer/TFT_eSPI
// The Sprite stuff can be found in the Extensions folder. It uses all the same functions.
// Don't forget to edit User_Setup.h in the TFT_eSPI library folder to suit your display.
// If you just get blackness, that probably means either you got the parameters wrong for your board, or
// perhaps you have another copy of TFT_eSPI on your computer that the Arduino IDE was using during compilation.
// Have a careful look at the compile log to see which library it used and edit User_Setup.h in THAT one.

#include <TFT_eSPI.h>

TFT_eSPI tft = TFT_eSPI(); // create an instance of class TFT_eSPI called tft. You may call it whatever you wish.
TFT_eSprite ScrollTextSprite = TFT_eSprite(&tft); // Create a Sprite object called ScrollTextSprite
// A Sprite is a 'virtual screen' on which to write words (or shapes or images or whatever) using the same functions you would use for the real screen.
// It gets created in memory ahead of time and then appears on the real screen with a pushSprite() command.

#include "Free_Fonts.h" // The header file attached to this sketch has font nicknames and whatnot.

int VerticalPosition = 50; // Upper edge of scrolling banner.
int ScrollStepCounter = 0;
int ScrollStep = -3; // Must be negative for scrolling from right to left. Use a more neg. number for faster scrolling, but jumpier.
int16_t MsgPixWidth; // The width of your entire message to be scrolled, in pixels.
String MessageToScroll = "You are AWESOME! Here is a longer message: 1234567890. The quick brown fox jumps over the lazy dog.";
int SpaceBetweenRepeats = 50; // in pixels.
int TopPadding = 10; // to keep the letters from touching the top edge of banner.
////////////////////////////////////////////////////////////
void setup() {
  tft.init();
  tft.fillScreen(TFT_PURPLE);
  tft.setRotation(1); // for my TTGO (240x135) T-display this makes it landscape mode with the USB port to the right.
  // 0: portrait, USB at bottom
  // 1: Landscape, USB at right
  // 2: portrait, USB at top
  // 3: Landscape, USB at left
  tft.setSwapBytes(true); // Color bytes are swapped when writing to RAM, this introduces a small overhead but
                          // there is a net performance gain by using swapped bytes.
  ScrollTextSprite.setFreeFont(FSSB18);  // ESP32 runs out of memory if the font is too big or the message is too long, and just flashes lamely.
  tft.setFreeFont(FSSB18); // In case you want to write non-scrolling text.
  MsgPixWidth = tft.textWidth(MessageToScroll);
  tft.drawString(String(MsgPixWidth), 0,TopPadding, GFXFF); // to see how many pixels wide your message is.
  ScrollTextSprite.setColorDepth(8); // How big a sprite you can use and how fast it moves is greatly influenced by the color depth.
  ScrollTextSprite.createSprite(MsgPixWidth + tft.width(), (tft.fontHeight() + TopPadding)); // Sprite width is display plus the space to allow text to scroll from the right.
  ScrollTextSprite.setTextColor(TFT_YELLOW, TFT_BLACK); // Yellow text, black background
  
  delay(1000);
  // Draw it for the first time:
  ScrollTextSprite.drawString(MessageToScroll, tft.width(),TopPadding, GFXFF); // 
  ScrollStepCounter = (MsgPixWidth / abs(ScrollStep)) + SpaceBetweenRepeats;
}

////////////////////////////////////////////////////////////
void loop() {
  ScrollStepCounter--; 
  if (ScrollStepCounter <= 0)
  { // Redraw the text to the right, just off the screen.
    tft.fillScreen(TFT_GREEN); // to signal the moment it begins the message again.
    delay(200);
    ScrollStepCounter = (MsgPixWidth / abs(ScrollStep))+ SpaceBetweenRepeats;
    ScrollTextSprite.drawString(MessageToScroll, tft.width(),TopPadding, GFXFF);
    tft.fillScreen(TFT_PURPLE);
  }
  ScrollTextSprite.scroll(ScrollStep);    // Shift the Sprite over by ScrollStep pixels.
  ScrollTextSprite.pushSprite(0, VerticalPosition); // Upper left corner of sprite

} // end main loop
```
[Free_Fonts.h.txt](https://github.com/Bodmer/TFT_eSPI/files/8682061/Free_Fonts.h.txt)

[Bodmer]

You have done well to understand this complex task and implement it.

The comments below are intended to be constructive:

1. The Sprite height includes the top padding so that occupies RAM but is always blank. You could just blank the section on the TFT above the sprite position and use a reduced height sprite.
2. The sprite is the string length in pixels, it could be just the TFT width as a maximum. After scrolling the sprite the missing section would have to be filled in by replotting text with the x position moving left. The area of replotting text could be set as a sprite viewport, the library then only draws pixels in the sprite in that viewport zone.

An alternative to using the sprite scroll feature is to draw text in sprite, plot sprite to screen, clear sprite, redraw text in sprite with x position moved left, plot sprite to screen. Repeat as required. You may find this seemingly inefficient but simple approach is surprisingly fast.

[stevempotter]

Great suggestions, Bodmer. I will try them out. They should allow me to use a bigger font.

[mrdude2478]

Here's an example I made that doesn't have any delay blocking code, also it uses less memory because it only draws in the sprite area which is the size of the font+screen width - not the entire length of the text.

#include"TFT_eSPI.h"

//Define LCD pins
#define TFT_CS_PIN     4 // Chip select control pin
#define TFT_SDA_PIN    3 // Serial Data pin
#define TFT_SCL_PIN    5 // Serial Clock pin
#define TFT_DC_PIN     2 // Data Command control pin
#define TFT_RES_PIN    1 // LCD Reset pin
#define TFT_LEDA_PIN   38 // LCD Backlight - set 0 for on and 1 for off

//Define LCD Screen Size
#define TFT_W 160 //set tft screen width
#define TFT_H 80 //set tft screen height

//Create some variables
String lcdscroller;
uint16_t array_pos = 0; //Start text for scroller
uint8_t changecol = 0;
unsigned long nowMillis;
unsigned long startMillis;  //global for scrolling text
uint8_t scrolldelay = 20;  //the value is a number of milliseconds
int tcount;
String blank;
int8_t swap_routine = 0;
const uint8_t fontwidth = (16);

TFT_eSPI tft = TFT_eSPI();
TFT_eSprite stext = TFT_eSprite(&tft); // Sprite object stext2
int routine = 0; //set the switch in the main loop

void setup(void) {
  tft.init();
  tft.setRotation(1);
  tft.setSwapBytes(true);
  stext.setTextWrap(false);  // Don't wrap text to next line
  stext.setTextSize(3);  // larger letters
  tft.fillScreen(TFT_BLACK);
  startMillis = millis();
}

void loop() {
  nowMillis = millis();  //get the current "time" (actually the number of milliseconds since the program started)
  switch (routine) {
      case 0:
        blank = " ---";
        lcdscroller = "Test" + blank;
        scrolltext();
        break;
      case 1:
        blank = " ***";
        lcdscroller = "Test2" + blank;
        scrolltext2();
        break;
  }
}

void scrolltext(){
  uint16_t arraysize = lcdscroller.length()+1; //added extra character for null at end of string
  char string_array[arraysize]; // Prepare the character array (the buffer) 
  lcdscroller.toCharArray(string_array, arraysize); // Copy it over 
  
  if (array_pos >= arraysize){
    array_pos = 0;
  }
  if (changecol >= arraysize){
    changecol = 0;
    stext.setTextColor(random(0x4000, 0xFFFF), 0x0000); //random colour min/max - background black
    swap_routine++;
    if (swap_routine >= 3){
      swap_routine = 0; //reset swap routine
      routine = 1; //jump to scrolltext2
    }
  }
  stext.createSprite(TFT_W+fontwidth, 32); // Screen width + width of the font
      
  if (nowMillis - startMillis >= scrolldelay)
  {
    stext.pushSprite(0, 34); //location to draw the sprite
    stext.scroll(-1); // scroll stext 1 pixel left, up/down default is 0
  
    tcount--;
    if (tcount <=0)
    {
      char x = string_array[array_pos];
      tcount = fontwidth; //once this pixel count is reached redraw the text
      stext.drawString(String(x), TFT_W, 0, 1); // draw string into sprite at location.
      array_pos++;
      changecol++;
    }
    startMillis = nowMillis;
  }
}

void scrolltext2(){
  uint16_t arraysize = lcdscroller.length()+1;
  char string_array[arraysize]; // Prepare the character array (the buffer) 
  lcdscroller.toCharArray(string_array, arraysize); // Copy it over 
  
  if (array_pos >= arraysize){
    array_pos = 0;
  }
  if (changecol >= arraysize){
    changecol = 0;
    stext.setTextColor(TFT_GOLD, 0x0000);
    swap_routine++;
    if (swap_routine >= 3){
      swap_routine = 0; //reset swap routine
      routine = 0; //jump to scrolltext
    }
  }
      
  if (nowMillis - startMillis >= scrolldelay)
  {
    stext.pushSprite(0, 34); //location to put the scrolling text
    stext.scroll(-1); // scroll stext 1 pixel left, up/down default is 0
  
    tcount--;
    if (tcount <=0)
    {
      char x = string_array[array_pos];
      tcount = fontwidth; //once this pixel count is reached redraw the text
      stext.drawString(String(x), TFT_W, 0, 1); // draw sprite at location.
      array_pos++;
      changecol++;
    }
    startMillis = nowMillis;
  }
}

[autodiag]

@mrdude2478

the code works very well
I just couldn't change the text dynamically on the fly, which is essential for me
it always ended up restarting ESP
Is there a workaround ?

Thank you