Frame Buffer Drivers

A framebuffer is a memory-mapped buffer that represents all the pixels necessary to drive a video display.

The Frame Buffer driver is intended to be used in the following scenarios:

  1. Whenever it is necessary to hold all the pixels that would be used to drive a video display. This includes:

    1. Graphics libraries that directly access the underlying framebuffer;

    2. Advanced UIs (e.g. alpha blending) that need to read back the image data;

  2. Applications that expect the framebuffer to exist;

Binding

LCD and frame buffer drivers usually are not directly accessed by user code, but are usually bound to another, higher-level device driver. In general, the binding sequence is:

  1. Get an instance of struct fb_vtable_s from the hardware-specific frame buffer device driver, and

  2. Provide that instance to the initialization method of the higher-level device driver.

Generic LCD Frame Buffer

This example will walk through the path from userspace to hardware-specific details on how an LCD screen is bound to a framebuffer.

  1. include/nuttx/video/fb.h provides all structures and APIs needed to work with frame buffer drivers:

    1. drivers/video/fb.c is the higher-level device driver. An instance of struct fb_vtable_s will be provided to it;

    2. fb_register registers the framebuffer character device at /dev/fbN where N is the display number;

    3. It also provides the prototype of up_fbinitialize, which may be defined by:

      1. An specific device into arch/<arch>/src/<chip> directory;

      2. By the LCD framebuffer adapter in drivers/lcd/lcd_framebuffer.c, which provides an intermediary interface between the Frame Buffer Driver and the LCD screen drivers;

  2. Let’s consider we are using the LCD framebuffer (CONFIG_LCD_FRAMEBUFFER = y):

    1. This interface implements the up_fbinitialize which:

      1. Provides the instance of struct fb_vtable_s (a member of struct lcdfb_dev_s);

      2. Calls board_lcd_initialize and board_lcd_getdev LCD-specific functions. These functions are defined in boards/<arch>/<chip>/<board>/src and prototyped in include/nuttx/board.h;

  3. Finally, the LCD screen drivers are usually available at drivers/lcd/ and implement the callbacks defined at include/nuttx/lcd/lcd.h:

    1. include/nuttx/lcd/lcd.h provides structures and APIs needed to work with LCD screens, whereas using the framebuffer adapter or the LCD Character Drivers;

VSYNC

Vertical synchronization (VSync) synchronizes the frame rate of an application’s graphics with the refresh rate of the display, helping to establish stability. If not synchronized, it may cause screen tearing, which is the effect of the image appearing to have horizontal jagged edges or ghosting across the entire screen.

VSYNC Offset

During the VSYNC event, the screen starts displaying frame N while the renderer begins compositing window for frame N+1. The application processes waiting input and generates frame N+2. When the renderer has a short rendering time, it can cause a delay of almost two frames from the end of rendering to the completion of screen display. To solve this problem, FBIOSET_VSYNCOFFSET can be used to set the VSYNC offset time (in microseconds) and reduce the delay from input device to screen using the VSYNC offset.

Examples

Examples apply to specific cases of the Generic LCD Frame Buffer:

TTGO T-Display ESP32 board

This board contains an ST7789 TFT Display (135x240). By selecting the ttgo_t_display_esp32:lvgl_fb config, the lvgldemo example will be built with the framebuffer interface.

  • boards/xtensa/esp32/ttgo_t_display_esp32/src/esp32_bringup.c registers the framebuffer driver:

#ifdef CONFIG_VIDEO_FB
  ret = fb_register(0, 0);
  if (ret < 0)
    {
      syslog(LOG_ERR, "ERROR: Failed to initialize Frame Buffer Driver.\n");
    }
#endif

  • up_fbinitialize from the frame buffer adapter will then be called as CONFIG_LCD_FRAMEBUFFER = y:

    • board_lcd_initialize and board_lcd_getdev are defined at boards/xtensa/esp32/common/src/esp32_st7789.c:

      • board_lcd_initialize initializes the LCD hardware on the board by defining the SPI interface which is connected to the display controller;

      • board_lcd_getdev calls the st7789_lcdinitialize and returns a reference to the LCD object for the specified LCD;

      • st7789_lcdinitialize is part of the LCD screen driver at drivers/lcd/st7789.c;

  • The LVGL demo application (lvgldemo) makes use of the ioctl system call to trigger a FBIO_UPDATE request to the higher-level device driver to refresh the LCD screen with framebuffer data:

ioctl(state.fd, FBIO_UPDATE, (unsigned long)((uintptr_t)&fb_area));

NuttX Simulator

NuttX Simulator provides a X11-based framebuffer driver to simulate the framebuffer usage into a X11-compatible host.

By selecting the sim:lvgl_fb config, the lvgldemo example will be built with the framebuffer driver.

  • boards/sim/sim/sim/src/sim_bringup.c registers the framebuffer driver the same way TTGO T-Display ESP32 board;

  • arch/sim/src/sim/up_framebuffer.c and arch/sim/src/sim/up_x11framebuffer.c will be built as CONFIG_SIM_FRAMEBUFFER = y and CONFIG_SIM_X11FB = y are set, respectively;

    • up_framebuffer.c provides up_fbinitialize and,

    • calls up_x11initialize from up_x11framebuffer.c that initializes a X11-based window as a framebuffer. This is the underlying “driver”.

  • The LVGL demo application (lvgldemo) makes use of the ioctl system call to trigger a FBIO_UPDATE request to the higher-level device driver in order to refresh the LCD screen with framebuffer data as usual;

Warning

One must consider that framebuffer requires that the entire display’s pixels to be represented. Considering a 320x480 @RGB565 LCD screen, that would be 300KiB, which it’d be too much for a memory-constrained device.

However, when memory is not a constraint, framebuffer may offer applications a faster way to update display contents once writing to the RAM-mapped buffer is faster than doing multiple SPI transfers.

For memory-constrained devices, consider using LCD Character Drivers.