Sprite & DMA

[Dodo773]

Hi Bodmer, first thank you for an excellent library, it's great job!
My question is: does Sprite support DMA ? Or is a plan to use DMA with the Sprite ?

[Bodmer]

16 bit Sprites can be treated as an image and sent to the screen using DMA. You need to get the pointer to the sprite image, this can be done at creation. See example here .

[Bodmer]

I tested that example on an ESP32 with PSRAM and it worked very well. Smaller sprites would be required if the processor does not have much RAM. The example uses 2 sprites but you could DMA just one.

[Dodo773]

Hi Bodmer, Excellent! I tired to use it in my app and it works. Just one problem still and it is a RAM size. For a test I reduced sprite size to 320 x 120, it works fine, but I need 320 x 160.
I use in my app blackpill with STM32F411 which has only 128k RAM so I use sprite with 8 bit color depth: setColorDepth(8), as I use only simple colors, 8bit is enough.
Is there any way how to setup DMA for 8 bits color deep only ?

[Bodmer]

The 16 bit image constraint is because the display expects 16 bit colours. DMA just moves data and does not transform the 8 bit colour to 16 bit, so this has to be done before DMA is used and this then needs a 16 bit buffer.

The example linked to above uses 2 half sized sprites to draw the screen in 2 stages (top and bottom), but it could also be arranged to use 2 quarter sized sprites and draw in 4 stages (use sprites in order 1,2,1,2 doing down the screen). This would be slower as you probably realised the whole screen sized graphics drawn every time a sprite image is created.

[Bodmer]

This is a modified sketch that decreases the size of the sprite to an 8th of the screen, so each of the 2 sprites would be 19.2 Kbytes for a 240x320 screen. This should run on your processor. Note that increasing the number of "panes" slows down the rendering because the sketch draws the full screen graphics to each small sprite every time, but this gets clipped by the library functions to the sprite area.

You can now change the # define DMA_PANES to a number of your choice, ideally a power of 2 (2, 4 or 8). Bigger numbers = slower rendering but smaller RAM size sprites.

// This sketch uses 2 sprites and DMA to draw screen graphics to
// the TFT as a sequence of "window panes".

// Created by Bodmer 30/04/2021 as an example for:
// https://github.com/Bodmer/TFT_eSPI

// Number of circles to draw
#define CNUMBER 40

// Number of horizontal "panes" that make up the screen
#define DMA_PANES 8

#include <TFT_eSPI.h>

// Library instance
TFT_eSPI    tft = TFT_eSPI();

// Create two sprites for a DMA toggle buffer
TFT_eSprite spr[2] = {TFT_eSprite(&tft), TFT_eSprite(&tft)};

// Pointers to start of Sprites in RAM (these are then "image" pointers)
uint16_t* sprPtr[2];

// Used for fps measuring
uint16_t counter = 0;
int32_t startMillis = millis();
uint16_t interval = 100;
String fps = "xx.xx fps";

// Structure to hold circle plotting parameters
typedef struct circle_t {
  int16_t   cx[CNUMBER] = { 0 }; // x coord of centre
  int16_t   cy[CNUMBER] = { 0 }; // y coord of centre
  int16_t   cr[CNUMBER] = { 0 }; // radius
  uint16_t col[CNUMBER] = { 0 }; // colour
  int16_t   dx[CNUMBER] = { 0 }; // x movment & direction
  int16_t   dy[CNUMBER] = { 0 }; // y movment & direction
} circle_param;

// Create the structure and get a pointer to it
circle_t *circle = new circle_param;

// #########################################################################
// Setup
// #########################################################################
void setup() {
  Serial.begin(115200);

  tft.init();
  tft.initDMA();
  tft.fillScreen(TFT_BLACK);

  // Create the 2 sprites, each one is then used as a partial screen "ping-pong" buffer
  sprPtr[0] = (uint16_t*)spr[0].createSprite(tft.width(), tft.height() / DMA_PANES);
  sprPtr[1] = (uint16_t*)spr[1].createSprite(tft.width(), tft.height() / DMA_PANES);

  // Define text datum for each Sprite
  spr[0].setTextDatum(MC_DATUM);
  spr[1].setTextDatum(MC_DATUM);

  // Seed the random number generator
  randomSeed(analogRead(A0));

  // Initialise circle parameters
  for (uint16_t i = 0; i < CNUMBER; i++) {
    circle->cr[i] = random(12, 24);
    circle->cx[i] = random(circle->cr[i], tft.width() - circle->cr[i]);
    circle->cy[i] = random(circle->cr[i], tft.height() - circle->cr[i]);

    circle->col[i] = rainbow(4 * i);
    circle->dx[i] = random(1, 5);
    if (random(2)) circle->dx[i] = -circle->dx[i];
    circle->dy[i] = random(1, 5);
    if (random(2)) circle->dy[i] = -circle->dy[i];
  }

  tft.startWrite(); // TFT chip select held low permanently

  startMillis = millis();
}

// #########################################################################
// Loop
// #########################################################################
void loop() {
  drawUpdate(); // Update whole screen

  // Calculate the fps every <interval> iterations.
  counter++;
  if (counter % interval == 0) {
    long millisSinceUpdate = millis() - startMillis;
    fps = String((interval * 1000.0 / (millisSinceUpdate))) + " fps";
    Serial.println(fps);
    startMillis = millis();
  }
}

// #########################################################################
// Render circles to sprites sequentially and initiate DMA
// #########################################################################
void drawUpdate (void) {
  for (uint8_t pane = 0; pane < DMA_PANES; pane++) {
    bool sel = pane & 1;
    int16_t py = pane * tft.height() / DMA_PANES;
    spr[sel].fillSprite(TFT_BLACK);

    for (uint16_t i = 0; i < CNUMBER; i++) {
      // Draw
      spr[sel].fillCircle(circle->cx[i], circle->cy[i] - py, circle->cr[i], circle->col[i]);
      spr[sel].drawCircle(circle->cx[i], circle->cy[i] - py, circle->cr[i], TFT_WHITE);
      spr[sel].setTextColor(TFT_BLACK, circle->col[i]);
      spr[sel].drawNumber(i + 1, 1 + circle->cx[i], circle->cy[i] - py, 2);
    }
    tft.pushImageDMA(0, py, tft.width(), tft.height() / DMA_PANES, sprPtr[sel]);
  }

  // Update circle positions
  for (uint16_t i = 0; i < CNUMBER; i++) {
    circle->cx[i] += circle->dx[i];
    circle->cy[i] += circle->dy[i];
    if (circle->cx[i] <= circle->cr[i]) {
      circle->cx[i] = circle->cr[i];
      circle->dx[i] = -circle->dx[i];
    }
    else if (circle->cx[i] + circle->cr[i] >= tft.width() - 1) {
      circle->cx[i] = tft.width() - circle->cr[i] - 1;
      circle->dx[i] = -circle->dx[i];
    }
    if (circle->cy[i] <= circle->cr[i]) {
      circle->cy[i] = circle->cr[i];
      circle->dy[i] = -circle->dy[i];
    }
    else if (circle->cy[i] + circle->cr[i] >= tft.height() - 1) {
      circle->cy[i] = tft.height() - circle->cr[i] - 1;
      circle->dy[i] = -circle->dy[i];
    }
  }
}

// #########################################################################
// Return a 16 bit rainbow colour
// #########################################################################
uint16_t rainbow(byte value)
{
  // If 'value' is in the range 0-159 it is converted to a spectrum colour
  // from 0 = red through to 127 = blue to 159 = violet
  // Extending the range to 0-191 adds a further violet to red band

  value = value % 192;

  byte red   = 0; // Red is the top 5 bits of a 16 bit colour value
  byte green = 0; // Green is the middle 6 bits, but only top 5 bits used here
  byte blue  = 0; // Blue is the bottom 5 bits

  byte sector = value >> 5;
  byte amplit = value & 0x1F;

  switch (sector)
  {
    case 0:
      red   = 0x1F;
      green = amplit; // Green ramps up
      blue  = 0;
      break;
    case 1:
      red   = 0x1F - amplit; // Red ramps down
      green = 0x1F;
      blue  = 0;
      break;
    case 2:
      red   = 0;
      green = 0x1F;
      blue  = amplit; // Blue ramps up
      break;
    case 3:
      red   = 0;
      green = 0x1F - amplit; // Green ramps down
      blue  = 0x1F;
      break;
    case 4:
      red   = amplit; // Red ramps up
      green = 0;
      blue  = 0x1F;
      break;
    case 5:
      red   = 0x1F;
      green = 0;
      blue  = 0x1F - amplit; // Blue ramps down
      break;
  }

  return red << 11 | green << 6 | blue;
}

[Dodo773]

Hi Bodmer,

I thank you again for explanation, I got it. You are right, the display supports only 16bits and DMA only transfer data from RAM.
In this case I decided to change MCU - from STM32F411 to STM32F412 (or 413) which have bigger RAM (256/320K)

Another question: is somehow possible to define HW preferences directly in the sketch ?
Example:
#define TFT_CS PA3 // Chip Address
#define TFT_DC PA2 // Data/Control
#define TFT_RST PA1 // Reset
#define ILI9341_DRIVER
#define SPI_FREQUENCY 48000000
#define SPI_READ_FREQUENCY 50000000
#define SPI_TOUCH_FREQUENCY 2500000

It helps me in multiple projects, because I don't need to update User_Setup.h and User_Setup_Select.h when I switch in the projects. (They are only "Hobby project"...:o))

Jozef

[Bodmer]

Unfortunately the Arduino environment does not give visibility of #defines to the libraries.
In the PlatformIO environment you can have a per project ini file.