1.. _snapshot:
2
3========
4Snapshot
5========
6
7Snapshot provides API to take snapshot image for LVGL Widget together
8with its children. The image will look exactly like the Widget on display.
9
10.. _snapshot_usage:
11
12Usage
13-----
14
15Simply call API :cpp:func:`lv_snapshot_take` to generate the image descriptor
16which can be set as image Widget src using :cpp:func:`lv_image_set_src`.
17
18Note, only following color formats are supported for now:
19
20- :cpp:enumerator:`LV_COLOR_FORMAT_RGB565`
21- :cpp:enumerator:`LV_COLOR_FORMAT_RGB888`
22- :cpp:enumerator:`LV_COLOR_FORMAT_XRGB8888`
23- :cpp:enumerator:`LV_COLOR_FORMAT_ARGB8888`
24
25Free the Image
26~~~~~~~~~~~~~~
27
28The memory :cpp:func:`lv_snapshot_take` uses are dynamically allocated using
29:cpp:func:`lv_draw_buf_create`. Use API :cpp:func:`lv_draw_buf_destroy` to free the memory it
30takes. This will firstly free memory the image data takes, then the
31image descriptor.
32
33The snapshot image which is the draw buffer returned by :cpp:func:`lv_snapshot_take`
34normally won't be added to cache because it can be drawn directly. So you don't need
35to invalidate cache by :cpp:func:`lv_image_cache_drop` before destroy the draw buffer.
36
37Below code snippet explains usage of this API.
38
39.. code-block:: c
40
41   void update_snapshot(lv_obj_t * widget, lv_obj_t * img_snapshot)
42   {
43       lv_draw_buf_t* snapshot = (void*)lv_image_get_src(img_snapshot);
44       if(snapshot) {
45           lv_draw_buf_destroy(snapshot);
46       }
47       snapshot = lv_snapshot_take(widget, LV_COLOR_FORMAT_ARGB8888);
48       lv_image_set_src(img_snapshot, snapshot);
49   }
50
51Use Existing Buffer
52~~~~~~~~~~~~~~~~~~~
53
54If the snapshot needs update now and then, or simply caller provides memory, use API
55``lv_result_t lv_snapshot_take_to_draw_buf(lv_obj_t * widget, lv_color_format_t cf, lv_draw_buf_t * draw_buf);``
56for this case. It's caller's responsibility to create and destroy the draw buffer.
57
58If snapshot is generated successfully, the image descriptor is updated
59and image data will be stored to provided ``buf``.
60
61Note that snapshot may fail if provided buffer is not enough, which may
62happen when Widget size changes. It's recommended to use API
63:cpp:func:`lv_snapshot_reshape_draw_buf` to prepare the buffer firstly and if it
64fails, destroy the existing draw buffer and call `lv_snapshot_take` directly.
65
66.. _snapshot_example:
67
68Example
69-------
70
71.. include:: ../../examples/others/snapshot/index.rst
72
73.. _snapshot_api:
74
75API
76---
77
78