feat(snapshot) add API to take snapshot for object (#2353)

* Fix image zooming causes unexpected object size.

Signed-off-by: Xu Xingliang <xuxingliang@xiaomi.com>

* add lv_snapshot_take API.

* fix(img) invalidate size and layout on zoom and angle change

* fix(img) not self-repeating under some zoom level.

* fix(snapshot) fix to keep the original position

* Move various set_px_cb_xx functions to lv_hal_disp.c

* add snapshot API to store image to provided buffer

* minor fixes and refactoring

* Move snapshot source to extra/others/snapshot.

1. Update parameter buff to buf.
2. Add macro to disable lv_snapshot, enabled by default.

* docs(others) add the others folder with snapshot.md

* docs(snapshot) added doc and example for snapshot.

1. Update doc snapshot.md
2. Add example lv_example_snapshot_1 to folder examples/others/snapshot
3. Update lv_conf_template.h and lv_conf_internal.h
4. Remove lv_snapshot.c from lv_misc.mk
5. Add others to index.md

Signed-off-by: Xu Xingliang <xuxingliang@xiaomi.com>

* add micropython example for snapshot

Co-authored-by: Xu Xingliang <xuxingliang@xiaomi.com>
Co-authored-by: Gabor Kiss-Vamosi <kisvegabor@gmail.com>

docs/index.md

@@ -34,6 +34,7 @@ PDF version: :download:`LVGL.pdf <LVGL.pdf>`
    overview/index
    widgets/index
    layouts/index
+   others/index
    CONTRIBUTING
    CHANGELOG
    ROADMAP

docs/others/index.md

@@ -0,0 +1,16 @@
+```eval_rst
+.. include:: /header.rst 
+:github_url: |github_link_base|/others/index.md
+```
+# Others
+
+
+```eval_rst
+
+.. toctree::
+   :maxdepth: 1
+   
+   snapshot
+   
+```
+

docs/others/snapshot.md

@@ -0,0 +1,67 @@
+```eval_rst
+.. include:: /header.rst 
+:github_url: |github_link_base|/others/snapshot.md
+```
+# Snapshot
+
+Snapshot provides APIs to take snapshot image for LVGL object together with its children. The image will look exactly like the object.
+
+## Usage
+
+Simply call API `lv_snapshot_take` to generate the image descriptor which can be set as image object src using `lv_img_set_src`.
+
+
+Note, only below color formats are supported for now:
+ - LV_IMG_CF_TRUE_COLOR_ALPHA
+ - LV_IMG_CF_ALPHA_1BIT
+ - LV_IMG_CF_ALPHA_2BIT
+ - LV_IMG_CF_ALPHA_4BIT
+ - LV_IMG_CF_ALPHA_8BIT
+
+
+### Free the Image
+The memory `lv_snapshot_take` uses are dynamically allocated using `lv_mem_alloc`. Use API `lv_snapshot_free` to free the memory it takes. This will firstly free memory the image data takes, then the image descriptor.
+
+
+Take caution to free the snapshot but not delete the image object. Before free the memory, be sure to firstly unlink it from image object, using `lv_img_set_src(NULL)` and `lv_img_cache_invalidate_src(src)`.
+
+
+Below code snippet explains usage of this API.
+
+```c
+void update_snapshot(lv_obj_t * obj, lv_obj_t * img_snapshot)
+{
+    lv_img_dsc_t* snapshot = (void*)lv_img_get_src(img_snapshot);
+    if(snapshot) {
+        lv_snapshot_free(snapshot);
+    }
+    snapshot = lv_snapshot_take(obj, LV_IMG_CF_TRUE_COLOR_ALPHA);
+    lv_img_set_src(img_snapshot, snapshot);
+}
+```
+
+### Use Existing Buffer
+If the snapshot needs update now and then, or simply caller provides memory, use API `lv_res_t lv_snapshot_take_to_buf(lv_obj_t * obj, lv_img_cf_t cf, lv_img_dsc_t * dsc, void * buf, uint32_t buff_size);` for this case. It's caller's responsibility to alloc/free the memory.
+
+
+If snapshot is generated successfully, the image descriptor is updated and image data will be stored to provided `buf`.
+
+
+Note that snapshot may fail if provided buffer is not enough, which may happen when object size changes. It's recommended to use API `lv_snapshot_buf_size_needed` to check the needed buffer size in byte firstly and resize the buffer accordingly.
+
+## Example
+
+```eval_rst
+
+.. include:: ../../examples/others/snapshot/index.rst
+
+```
+## API
+
+
+```eval_rst
+
+.. doxygenfile:: lv_snapshot.h
+  :project: lvgl
+
+```

docs/overview/object.md

@@ -218,3 +218,5 @@ In both cases ORed state values can be used as well. E.g. `lv_obj_add_state(obj,
 
 To learn more about the states read the related section of the [Style overview](/overview/style).
 
+## Snapshot
+A snapshot image could be generated for object together with its children. Check details in [Snapshot](/others/snapshot).