acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
snapshot.md (2202B)
      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/others/snapshot.md
      4 ```
      5 # Snapshot
      6 
      7 Snapshot provides APIs to take snapshot image for LVGL object together with its children. The image will look exactly like the object.
      8 
      9 ## Usage
     10 
     11 Simply call API `lv_snapshot_take` to generate the image descriptor which can be set as image object src using `lv_img_set_src`.
     12 
     13 
     14 Note, only below color formats are supported for now:
     15  - LV_IMG_CF_TRUE_COLOR_ALPHA
     16  - LV_IMG_CF_ALPHA_1BIT
     17  - LV_IMG_CF_ALPHA_2BIT
     18  - LV_IMG_CF_ALPHA_4BIT
     19  - LV_IMG_CF_ALPHA_8BIT
     20 
     21 
     22 ### Free the Image
     23 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.
     24 
     25 
     26 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)`.
     27 
     28 
     29 Below code snippet explains usage of this API.
     30 
     31 ```c
     32 void update_snapshot(lv_obj_t * obj, lv_obj_t * img_snapshot)
     33 {
     34     lv_img_dsc_t* snapshot = (void*)lv_img_get_src(img_snapshot);
     35     if(snapshot) {
     36         lv_snapshot_free(snapshot);
     37     }
     38     snapshot = lv_snapshot_take(obj, LV_IMG_CF_TRUE_COLOR_ALPHA);
     39     lv_img_set_src(img_snapshot, snapshot);
     40 }
     41 ```
     42 
     43 ### Use Existing Buffer
     44 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.
     45 
     46 
     47 If snapshot is generated successfully, the image descriptor is updated and image data will be stored to provided `buf`.
     48 
     49 
     50 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.
     51 
     52 ## Example
     53 
     54 ```eval_rst
     55 
     56 .. include:: ../../examples/others/snapshot/index.rst
     57 
     58 ```
     59 ## API
     60 
     61 
     62 ```eval_rst
     63 
     64 .. doxygenfile:: lv_snapshot.h
     65   :project: lvgl
     66 
     67 ```