1
2# JPG decoder
3
4Allow the use of JPG images in LVGL. Besides that it also allows the use of a custom format, called Split JPG (SJPG), which can be decoded in more optimal way on embedded systems.
5
6## Overview
7  - Supports both normal JPG and the custom SJPG formats.
8  - Decoding normal JPG consumes RAM with the size fo the whole uncompressed image (recommended only for devices with more RAM)
9  - SJPG is a custom format based on "normal" JPG and specially made for LVGL.
10  - SJPG is 'split-jpeg' which is a bundle of small jpeg fragments with an sjpg header.
11  - SJPG size will be almost comparable to the jpg file or might be a slightly larger.
12  - File read from file and c-array are implemented.
13  - SJPEG frame fragment cache enables fast fetching of lines if available in cache.
14  - By default the sjpg image cache will be image width * 2 * 16 bytes (can be modified)
15  - Only the required partion of the JPG and SJPG images are decoded, therefore they can't be zoomed or rotated.
16
17## Usage
18
19If enabled in `lv_conf.h` by `LV_USE_SJPG` LVGL will register a new image decoder automatically so JPG and SJPG files can be directly used as image sources. For example:
20```
21lv_img_set_src(my_img, "S:path/to/picture.jpg");
22```
23
24Note that, a file system driver needs to registered to open images from files. Read more about it [here](https://docs.lvgl.io/master/overview/file-system.html) or just enable one in `lv_conf.h` with `LV_USE_FS_...`
25
26
27
28## Converter
29
30### Converting JPG to C array
31  - Use lvgl online tool https://lvgl.io/tools/imageconverter
32  - Color format = RAW, output format = C Array
33
34### Converting JPG to SJPG
35python3 and the PIL library required. (PIL can be installed with `pip3 install pillow`)
36
37To create SJPG from JPG:
38- Copy the image to convert into `lvgl/scripts`
39- `cd lvgl/scripts`
40- `python3 jpg_to_sjpg.py image_to_convert.jpg`. It creates both a C files and an SJPG image.
41
42The expected result is:
43```sh
44Conversion started...
45
46Input:
47        image_to_convert.jpg
48        RES = 640 x 480
49
50Output:
51        Time taken = 1.66 sec
52        bin size = 77.1 KB
53        walpaper.sjpg           (bin file)
54        walpaper.c              (c array)
55
56All good!
57```
58
59
60## Example
61```eval_rst
62
63.. include:: ../../examples/libs/sjpg/index.rst
64
65```
66
67## API
68
69```eval_rst
70
71.. doxygenfile:: lv_sjpg.h
72  :project: lvgl
73