.. include:: /include/external_links.txt

.. _image_sources:

=============
Image Sources
=============

The images module supports images in any of 3 forms:

.. container:: tighter-table-3

    +------------+------------------------------------------------------------------+
    | Form       | Source                                                           |
    +============+==================================================================+
    | Variables_ | :cpp:type:`lv_image_dsc_t` object + data in ROM or RAM           |
    +------------+------------------------------------------------------------------+
    | Files_     | :ref:`file_system` path to file (e.g. JPG, PNG, BMP etc.)        |
    +------------+------------------------------------------------------------------+
    | Symbols_   | C strings starting with Unicode characters (e.g. icons) in UTF-8 |
    +------------+------------------------------------------------------------------+

Image sources are set by calling one of the ``..._set_src()`` functions.  See code
examples below.



.. _image_sources_variables:

Variables
*********

In this context, a "variable" is a C symbol that is used in C code to refer to an
object in either RAM or ROM.

Images stored as variables are comprised of an :cpp:struct:`lv_image_dsc_t` struct
plus its data.  The struct contains the following fields:

:header:

    :magic:       Magic number (must be LV_IMAGE_HEADER_MAGIC)
    :cf:          Color format. See :ref:`images_color_formats`.
    :flags:       Image flags (any of the ``LV_IMAGE_FLAGS_...`` enumeration values).
    :w:           Width in pixels (<= 2048)
    :h:           Height in pixels (<= 2048)
    :stride:      Number of bytes between the beginning of one row of pixels and the beginning of the next row
    :reserved_2:  reserved for future use

:data_size:  length of ``data`` in bytes
:data:       pointer to a byte array where the data of the image is stored (pixels
             and sometimes indexed color palettes [for indexed color formats]).
             When ``header.cf`` is one of the ``RAW`` formats, this can also contain
             the contents of a file loaded into RAM at run-time, or embedded in ROM
             (program space).


These are usually stored within a project as a C file generated by one of these two
LVGL image converters:

- `LVGL Online Image Converter`_
- Offline converter in ``./scripts/LVGLImage.py``.

At this writing, the online converter supports these formats:

- RGB565
- RGB565A8
- RGB888
- XRGB8888
- ARGB8888

The offline converter can convert an image into the above formats plus all the other
supported color formats.

The generated C files are compiled and linked into the resulting executable like any
other ``const`` data.

See :ref:`adding images to your project` for more details.

Example:

.. code-block:: c

    LV_IMAGE_DECLARE(img_cogwheel_argb);
    lv_obj_t * img = lv_image_create(lv_screen_active());
    lv_image_set_src(img, &img_cogwheel_argb);



.. _image_sources_files:

Files
*****

Files can be used as image sources by passing in the path string to the image file
to the ``lv_<widget>_set_src()`` function as the ``src`` argument.  The string must
begin with a printable ASCII character (range [0x20-0x7F]).  Example:

.. code-block:: c

    lv_image_set_src(icon, "S:my_icon.png");

Images stored as files are normally not linked into the resulting executable, and must
be read into RAM before being drawn.  As a result, they are not as resource-friendly
as images linked at compile time.  However, they are easier to replace without
needing to rebuild the main program.

Exceptions where there is no meaningful extra memory usage:

- JPEG:  Only a few pixels are read and drawn at once.
- BMP:  Pixels are transferred directly from the file to the draw buffer.
- BIN:  Pixels are transferred line-by-line to the draw buffer.

For the images module to deal with files you need to add a *Driver* for the target
storage system to LVGL.  See :ref:`file_system` for details.



.. _image_sources_symbols:

Symbols
*******

Symbols that can be used as an image source are ``char *`` strings beginning with a
Unicode character encoded in UTF-8, which will have a first-byte value >= 0x80.  After
that, these strings can contain any other characters, including additional Unicode
characters.  Such strings are passed as the image source like this:

.. code-block:: c

    lv_image_set_src(icon, LV_SYMBOL_BATTERY_FULL);
    /* or */
    lv_image_set_src(icon, LV_SYMBOL_OK " Accept");

The file ``./src/font/lv_symbol_def.h`` contains a wide variety of Unicode symbols you
can use directly, or you can make your own.  See :ref:`font_adding_a_custom_symbol`
for details.

.. note::

    Symbols are only implemented for :ref:`lv_image` Widgets.



Examples
********

See :ref:`Using Images Examples <using_images_examples>` for a number of examples of
using image sources in these 3 forms.



API
***

.. API equals:  lv_image_set_src

