.. _display_overview:

========
Overview
========

What is a Display?
******************

In LVGL, an *lv_display_t* (not to be confused with a :ref:`Screen <screens>`) is a
data type that represents a single display panel --- the hardware that displays
LVGL-rendered pixels on your device.



.. _multiple_displays:

How Many Displays Can LVGL Use?
*******************************

LVGL can use any number of displays.  It is only limited by available RAM and MCU time.

Why would you want multi-display support? Here are some examples:

- Have a "normal" TFT display with local UI and create "virtual" screens on VNC
  on demand. (You need to add your VNC driver.)
- Have a large TFT display and a small monochrome display.
- Have some smaller and simple displays in a large instrument or technology.
- Have two large TFT displays: one for a customer and one for the shop assistant.

If you set up LVGL to use more than one display, be aware that some functions use the
:ref:`default_display` during their execution, such as creating :ref:`screens`.



.. _display_attributes:

Attributes
**********

Once created, a Display object remembers the characteristics of the display hardware
it is representing, as well as other things relevant to its lifetime:

- Resolution (width and height in pixels)
- Color Depth (bits per pixel)
- Color Format (how colors in pixels are laid out)
- DPI (default is configured :c:macro:`LV_DPI_DEF` in ``lv_conf.h``, but can be
  modified with :cpp:expr:`lv_display_set_dpi(disp, new_dpi)`).
- 4 :ref:`display_screen_layers` automatically created with each display
- All :ref:`screens` created in association with this display (and not yet deleted---only
  one is displayed at any given time)
- The :ref:`draw_buffers` assigned to it
- The :ref:`flush_callback` function that moves pixels from :ref:`draw_buffers` to Display hardware
- What areas of the display have been updated (made "dirty") so rendering logic can
  compute what to render during a display refresh
- Optional custom pointer as :ref:`display_user_data`



.. _display_user_data:

User Data
*********

With :cpp:expr:`lv_display_set_user_data(display1, p)` a custom pointer can be stored
with ``lv_display_t`` object.  This pointer can be used later, e.g. in
:ref:`display_events`.   See code example for how to do this in :ref:`display_events`.



API
***

.. API equals:
    lv_display_set_dpi
    lv_display_set_user_data
