.. include:: /include/substitutions.txt
.. _gif:

============
GIF (lv_gif)
============

The GIF Widget internally uses the
`AnimatedGIF <https://github.com/bitbank2/AnimatedGIF/tree/master>`__
GIF Decoder library, enabling you to use GIF images in your LVGL UI.



Parts and Styles
****************

- :cpp:enumerator:`LV_PART_MAIN` A background rectangle that uses the :ref:`typical
  background style properties <typical bg props>`.



Usage
*****

Once enabled in ``lv_conf.h`` by setting :c:macro:`LV_USE_GIF` to ``1``,
:cpp:expr:`lv_gif_create(parent)` can be used to create a GIF Widget.

Set the color format of the GIF framebuffer with :cpp:expr:`lv_gif_set_color_format(widget, color_format)`.
Use :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888` for gifs with transparency.
It is set to :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888` by default.
Significant RAM can be saved by using a smaller color format.
A color format conversion can be saved during rendering if the color format matches the display
color format.
This function can be called before :cpp:func:`lv_gif_set_src` to prevent the initial default ARGB8888
framebuffer from being allocated.

The supported color formats are:

- :cpp:enumerator:`LV_COLOR_FORMAT_RGB565`
- :cpp:enumerator:`LV_COLOR_FORMAT_RGB565_SWAPPED`
- :cpp:enumerator:`LV_COLOR_FORMAT_RGB888`
- :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888`

:cpp:expr:`lv_gif_set_src(widget, src)` works very similarly to :cpp:func:`lv_image_set_src`.
As source, it also accepts images as variables (:cpp:struct:`lv_image_dsc_t`) or files.


Converting GIF Files to C Arrays
--------------------------------

Converting GIF files to an array of bytes is not supported in the online image
converter since LVGL v9.0.  However, there is still a way to do it through the
``./scripts/LVGLImage.py`` Python script.  This command line:

.. code-block:: bash

    python  ./scripts/LVGLImage.py  --cf RAW  --ofmt C  -o .  --name my_gif_image_array  input.gif

will produce all the bytes from the ``input.gif`` in unaltered form in a C array,
ready to use in this code:

.. code-block:: c

    LV_IMAGE_DECLARE(my_gif_image_array);
    lv_obj_t * img;

    img = lv_gif_create(lv_screen_active());
    lv_gif_set_color_format(img, LV_COLOR_FORMAT_ARGB8888);
    lv_gif_set_src(img, &my_gif_image_array);


Using GIF Images from Files
---------------------------

Example:

.. code-block:: c

    lv_gif_set_src(widget, "S:path/to/example.gif");

Note that, a file system driver needs to be registered to open images
from files.  To do so, follow the instructions in :ref:`file_system`.



Memory Requirements
*******************

To decode and display a GIF animation ~25 kB of RAM is needed plus
(color format pixel size + 1) |times| image width |times| image height.
RGB565 has a pixel size of 2, RGB888 has a pixel size of 3, and
ARGB8888 has a pixel size of 4.



Events
******

- :cpp:enumerator:`LV_EVENT_READY` is emitted when the GIF animation has completed
  rendering its last frame.

.. admonition::  Further Reading

    Learn more about :ref:`lv_obj_events` emitted by all Widgets.

    Learn more about :ref:`events`.



.. _gif_example:

Example
*******

.. include:: /examples/libs/gif/index.rst



.. _gif_api:

API
***

.. API startswith:  lv_gif_

