# Image Sources (/main-modules/images/sources)



The images module supports images in any of 3 forms:

| Form        | Source                                                                               |
| ----------- | ------------------------------------------------------------------------------------ |
| Variables\_ | <ApiLink name="lv_image_dsc_t" /> object + data in ROM or RAM                        |
| Files\_     | [File System (lv\_fs\_drv)](/main-modules/fs) path to file (e.g. JPG, PNG, BMP etc.) |
| Symbols\_   | C strings starting with Unicode characters (e.g. icons) in UTF-8                     |

Image sources are set by calling one of the `..._set_src()` functions.  See code
examples below.

Variables [#variables]

In this context, a "variable" is a C symbol that is used in C code to refer to an
object in either RAM or ROM.

Images stored as variables are comprised of an <ApiLink name="lv_image_dsc_t" /> struct
plus its data.  The struct contains the following fields:

:header:

| Field       | Description                                                                                                                                                                                                                                                                                                                                                                                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `magic`     | Magic number (must be LV\_IMAGE\_HEADER\_MAGIC) :cf: Color format. See [Color Formats](/main-modules/images/color_formats). :flags: Image flags (any of the `LV_IMAGE_FLAGS_...` enumeration values). :w: Width in pixels (\<= 2048) :h: Height in pixels (\<= 2048) :stride: Number of bytes between the beginning of one row of pixels and the beginning of the next row :reserved\_2: reserved for future use |
| `data_size` | length of `data` in bytes                                                                                                                                                                                                                                                                                                                                                                                        |
| `data`      | pointer to a byte array where the data of the image is stored (pixels and sometimes indexed color palettes \[for indexed color formats]). When `header.cf` is one of the `RAW` formats, this can also contain the contents of a file loaded into RAM at run-time, or embedded in ROM (program space).                                                                                                            |

These are usually stored within a project as a C file generated by one of these two
LVGL image converters:

* LVGL Online Image Converter
* Offline converter in `./scripts/LVGLImage.py`.

At this writing, the online converter supports these formats:

* RGB565
* RGB565A8
* RGB888
* XRGB8888
* ARGB8888

The offline converter can convert an image into the above formats plus all the other
supported color formats.

The generated C files are compiled and linked into the resulting executable like any
other `const` data.

See [Adding Images to Your Project](/main-modules/images/adding_images) for more details.

Example:

```c title=" " lineNumbers=1
LV_IMAGE_DECLARE(img_cogwheel_argb);
lv_obj_t * img = lv_image_create(lv_screen_active());
lv_image_set_src(img, &img_cogwheel_argb);
```

Files [#files]

Files can be used as image sources by passing in the path string to the image file
to the `lv_<widget>_set_src()` function as the `src` argument.  The string must
begin with a printable ASCII character (range \[0x20-0x7F]).  Example:

```c title=" " lineNumbers=1
lv_image_set_src(icon, "S:my_icon.png");
```

Images stored as files are normally not linked into the resulting executable, and must
be read into RAM before being drawn.  As a result, they are not as resource-friendly
as images linked at compile time.  However, they are easier to replace without
needing to rebuild the main program.

Exceptions where there is no meaningful extra memory usage:

* JPEG:  Only a few pixels are read and drawn at once.
* BMP:  Pixels are transferred directly from the file to the draw buffer.
* BIN:  Pixels are transferred line-by-line to the draw buffer.

For the images module to deal with files you need to add a *Driver* for the target
storage system to LVGL.  See [File System (lv\_fs\_drv)](/main-modules/fs) for details.

Symbols [#symbols]

Symbols that can be used as an image source are `char *` strings beginning with a
Unicode character encoded in UTF-8, which will have a first-byte value >= 0x80.  After
that, these strings can contain any other characters, including additional Unicode
characters.  Such strings are passed as the image source like this:

```c title=" " lineNumbers=1
lv_image_set_src(icon, LV_SYMBOL_BATTERY_FULL);
/* or */
lv_image_set_src(icon, LV_SYMBOL_OK " Accept");
```

The file `./src/font/lv_symbol_def.h` contains a wide variety of Unicode symbols you
can use directly, or you can make your own.  See [Adding a Custom Symbol](/main-modules/fonts/overview)
for details.

<Callout type="info">
  Symbols are only implemented for [Image (lv\_image)](/widgets/image) Widgets.
</Callout>

Examples [#examples]

See [Using Images Examples](/main-modules/images/using_images) for a number of examples of
using image sources in these 3 forms.

API [#api]