STM32: using the LTDC display controller

The STM32 LTDC has a peripheral called LTDC LCD TFT Display Controller which provides a digital parallel interface (DPI) for a variety of LCD and TFT panels. It sends RGB data in parallel to the display and generates signals for horizontal and vertical synchronization (HSYNC, VSYNC), as well as pixel clock (PCLK) and not data enable (DE) signals:

figure 1: LTDC RGB interface signals

RGB interface synchronization signals

LTDC synchronous timing parameters are configurable: a synchronous timing generator block inside the LTDC generates the horizontal and vertical synchronization signals, the pixel clock and not data enable signals. The configurable timing parameters are:

  • LTDC_SSCR Synchronization Size Configuration Register, configured by programming the values HSYNC width – 1  and VSYNC width – 1
  • LTDC_BPCR Back Porch Configuration Register, configured by programming the accumulated values HSYNC width + horizontal back porch – 1 and VSYNC width + vertical back porch – 1
  • LTDC_AWCR Active Width Configuration Register, configured by programming the accumulated values  HSYNC width + horizontal back porch + active width – 1 and VSYNC width + vertical back porch + active height – 1
  • LTDC_TWCR Total Width Configuration Register, configured by programming the accumulated values  HSYNC width + horizontal back porch + active width + horizontal front porch – 1 and VSYNC width + vertical back porch + active height + vertical front porch – 1 

figure 2: RGB interface timing and horizontal/vertical synchronization, pixel clock and data enable signals

Horizontal timing signal widths are in units of pixel clocks, while vertical timing signal widths are in units of horizontal scan lines. The HSYNC, VSYNC, pixel clock and not data enable signal polarities can be configured to active high or active low in the LTDC_GCR Global Control Register (not data enable signal must be configured inverted with respect to the data enable signal in the display datasheet). The datasheet of the panel generally provides the timing parameters for the display:

figure 3: RGB panel timing signals

Configuring the timing signals is the first thing to do to initialize the LTDC controller. The function HAL_LTDC_MspInit() initializes the low level details of the LTDC peripheral (clock and GPIOs):

A constant background color can be configured in LTDC_BCCR Background Color Configuration Register (eight bits per channel are used in this register to select a solid RGB color):

The background color is used for blending with the bottom layer.

Layer configuration

The LTDC has two layers which can be configured, enabled and disabled independently, each with its own FIFO buffer. Layer order is fixed and layer2 is alway on top of layer1. Layer can be enabled writing the LEN Layer Enable bit in the LTDC_LxCR Layer x Control Register. Each layer gets its data from a framebuffer in memory and the start address is written in LTDC_LxCFBAR  Layer x Color Frame Buffer Address Register. The frame buffer contains the display frame data in one of eight configurable pixel format: LTDC_LxPFCR Layer x Pixel Format Configuration Register is configured to choose the pixel format used to store data into the frame buffer. The available pixel formats are:

  • ARGB8888
  • RGB888
  • RGB565
  • ARGB1555
  • ARGB4444
  • L8 (8 bit luminance)
  • AL44 (4 bit alpha, 4 bit luminance)
  • AL88 (8 bit alpha, 8 bit luminance)

The pixel data are read from the frame buffer and converted to the LTDC internal 32-bit pixel format ARGB8888:

figure 4: whatever the framebuffer pixel format the LTDC converts the data into the internal 32 bit ARGB8888 pixel format

Each layer can be positioned and resized inside the active area indicating the start and stop position of the visible window in the LTDC_LxWHPCR Layer x Window Horizontal Position Configuration Register and LTDC_LxWVPCR Layer x Window Vertical Position Configuration Register. These parameters select the first and last visible pixels of a line and the first and last visible lines in the window. The values must includes the timing signals (HSYNC and VSYNC) width and the back porch width programmed into LTDC_BPCR register. In this case the accumulated horizontal back porch is 30 – 1, so the active area starts at 30 and the image is 240 pixel wide so horizontal window stop position is 30 + 240 – 1 = 269 (same for the vertical start and stop positions):

The frame buffer has a configurable line length (in bytes) in the LTDC_LxCFBLR Layer x Color Frame Buffer Length Register  and a configurable total number of lines in the LTDC_LxCFBLNR Layer x Color Frame Buffer Line Number Register. It also has a configurable line pitch, which indicates the distance in bytes between the start of a line and the beginning of the next line, also configured in the LTDC_LxCFBLR register, and expressed in bytes. These parameters are used by the LTDC to fetch data from the frame buffer to the layer FIFO. If set to less byte than needed, a FIFO underrun interrupt will trigger (if enabled), if set to more bytes than required the rest of the data loaded into the layer’s FIFO is discarded.

Line length parameter is the number of bytes in a line plus three (so the total line length is number of pixels * bits per pixel + 3). These parameters, together with the layer windowing settings, are useful if we want to display part of an image contained in the frame buffer, as I’ll show later.

Each layer can also have a default color, configured into the LTDC_LxDCCR Layer x Default Color Configuration Register, in ARGB8888 format, that is used outside the layer window or when a layer is disabled:

A constant alpha blending value is configured into the LTDC_LxCACR Layer x Constant Alpha Configuration Register, and controls the alpha blending with the underlying layers. In this case the value 255 (which is divided by 255 by hardware to get a value between 0 and 1) indicates a solid color:

Blending order is fixed and if both layers are enabled, first layer 1 is blended with the background and then layer 2 is blended with the result:

figure 5: layer blending

Then the layer is enabled by writing the LEN bit into the LTDC_LxCR LTDC Layer x Control Register:

Shadow configuration registers

Some configuration registers are shadowed, meaning their programmed values are stored into shadow registers (not accessible to the programmer) and reloaded into the actual configuration registers based on the configuration of the LTDC_SRCR Shadow Reload Configuration Register: if this register is written with the IMR Immediate Reload bit the registers are reloaded immediately (as soon as the IMR bit is set the registers are reloaded), if the Vertical Blanking Reload bit is written the registers are reloaded with the new values during the vertical blanking period (at the beginning of the first line after the active display area). These bits are set in software and cleared by hardware when shadow registers are reloaded:

The registers read the old values until they’re reloaded and if a new value is written before they’re reloaded the previous value is overwritten. Most of the layers’ configuration registers are shadowed so they must be reloaded after being configured and before anabling the LTDC. The complete LTDC_init() function looks like this:

Using the LTDC with the ILI9341 display controller

In this example I use the display on the STM32F429-Discovery board, which is driven by the ILI9341 display controller. The ILI9341 can drive a QVGA (Quarter VGA) 240×320 262,144 colors LCD display. The controller can be configured via SPI (or parallel interface, depending on the panel settings) to use a digital parallel 18 bit RGB interface (since only 6 lines per color channel are wired on the board to the LTDC). Since the display pixel format is less than 8 bit per channel (RGB666 in this case), the RGB display data lines are connected to the most significant bits of the LTDC controller RGB data lines:

figure 5: LTDC signal lines. Only MSB are used if the display has less than 8 lines per color channel

Before enabling the LTDC we must configure the clock system. The LTDC uses a specific clock LCD_CLOCK to generate the pixel clock signal and it must be configured and enabled during the system initialization phase:

The HAL_LTDC_MspInit() function, called at the beginning of LTDC_init() enables the LTDC peripheral clock and takes care of the low level hardware initialization:

To display an image we must convert an image file to an array (possibly a const one, so it can be stored in flash memory) of bytes. To do this I used LCD image converter, a simple but powerful application that can convert a file to a variety of different pixel formats:

figure 6: LTDC image converter is used to generate a RGB888 image array

Once the image is converted to a byte array the generated header file is included and the array address can be used as the frame buffer starting address in the LTDC_LxCFBAR register. Layer window parameters are configured according to the image size (240 x 320, I rotated the image to fit the display in portrait mode).

figure 7: a 240 x 320 (rotated) image displayed

The second layer can be enabled as well and its contents drawn on top of layer 1. LTDC can manage transparency using the values in the LTDC_LxCACR Layer x Constant Alpha Configuration Register and LTDC_LxBFCR Layer x Blending Factor Configuration Register: here I used a constant alpha of 255 to obtain a 100% opacity (the value in the constant alpha register is divided by 255 by hardware so for example a value of 128 represents an alpha value of 0.5). Since the layer window is smaller than the display area the default layer background color is set to a transparent black (otherwise the default layer background color is used if the layer window is smaller than the display). The image is 110 x 110 pixels and the pixel format is ARGB8888 (the alpha channel is used to draw transparent pixels). Note that the LTDC_LxCBLR and LTDC_LxCBLNR registers are configured according to the image size: the LTDC always starts fetching data from the address defined in the LTDC_LxCFBAR register. I added the following lines of code to the LTDC_init() function to configure and enable layer 2:


figure 8: the layer window must be inside the active display area. layer2 image is in ARGB8888 format, allowing tranparent pixels to show through

If we want do display portion of an image, we must configure LTDC_LxCBLR and LTDC_LxCBLNR accordingly:

Now I’m just showing 100 x 100 pixels of the layer 1 image so I configured the color buffer line length as 100 and the color buffer number of lines as 100. The line pitch value indicates that a framebuffer line is still 240 * 3 bytes long so the controller knows how to fetch bytes from the frame buffer correctly. I also moved the start of the window adding an offset of 50 pixels and 50 scan lines. The default background color is used where the layer isn’t used (the layer background color is a solid green):

figure 9: layer1 window is resized and repositioned inside active display area

Using two layers and playing with the layer window size and position allows to create simple animations by simply moving the layer window around the frame:

Shadow configuration registers are reloaded each vertical blanking period (after the last line has been drawn) and the code waits for the next frame by polling the VSYNCS flag of the LTDC_CDSR Current Display Status Register, whose bits contain the state of the synchronization signals (high if they’re asserted, no matter the polarity configured). Running the code we get a nice smooth animation:

LTDC interrupts

The LTDC controller has four interrupts logically OR-ed into two interrupt request lines:

  • Register Reload Interrupt, generated as soon as the shadow registers are reloaded
  • Line Interrupt, generated when a line number (programmed into LTDC_LIPCR Line Interrupt Position Control Register) is reached
  • Transfer Error Interrupt, generated when an AHB bus error occurs during a transfer
  • FIFO underrun Interrupt, generated when a pixel is requested from an empty layer FIFO

figure 10: LTDC interrupts and IRQ lines

The Line and Register Reload interrupts are useful to synchronize the code with the controller.

Using double buffering

Double buffer is used when we want the code to write on a frame buffer while another buffer is being read by the LTDC. This avoids corrupting the data being displayed on the screen. The buffers are switched during the vertical blanking period using polling or interrupts.

figure n: while the code writes to the back buffer the LTDC fetches data from the front (active) buffer. Famebuffers are switched during vertical blanking period.

In this example the framebuffers have a RGB888 color depth and for a 240×320 display that makes 225 KiB of memory for each buffer (3 bytes per pixel x 240 x 320 pixels) so they must be stored in external SRAM (the STM32F429I-DISCOVERY has a 64Mbit external SRAM so we’re good). The FMC Flexible Memory Controller has to be initialized and the address of the two frame buffers has to be configured. Drawing on the framebuffer is a matter of writing the right bytes in order to change the color. Once all pixels are drawn (bytes are written) the buffers are switched and the code can draw the next frame:

Now as soon as a frame is done with, calling LTDC_switch_framebuffer() waits for the vertical synchronization period and swaps the buffers. If the code is faster than the display refresh rate (70Hz in our case) it waits for the LTDC to complete drawing the frame.

In the next post I’m going to use the double buffer technique to draw and animate sprites.

source code

LTDC datasheet

Leave a Reply

Your email address will not be published. Required fields are marked *