1# Image (lv_img) 2 3 4## Overview 5 6Images are the basic object to display images from flash (as arrays) or from files. Images can display symbols (`LV_SYMBOL_...`) too. 7 8Using the [Image decoder interface](/overview/image.html#image-decoder) custom image formats can be supported as well. 9 10## Parts and Styles 11- `LV_PART_MAIN` A background rectangle that uses the typical background style properties and the image itself using the image style properties. 12 13## Usage 14 15### Image source 16To provide maximum flexibility, the source of the image can be: 17 18- a variable in code (a C array with the pixels). 19- a file stored externally (e.g. on an SD card). 20- a text with [Symbols](/overview/font). 21 22To set the source of an image, use `lv_img_set_src(img, src)`. 23 24To generate a pixel array from a PNG, JPG or BMP image, use the [Online image converter tool](https://lvgl.io/tools/imageconverter) and set the converted image with its pointer: `lv_img_set_src(img1, &converted_img_var);` 25To make the variable visible in the C file, you need to declare it with `LV_IMG_DECLARE(converted_img_var)`. 26 27To use external files, you also need to convert the image files using the online converter tool but now you should select the binary output format. 28You also need to use LVGL's file system module and register a driver with some functions for the basic file operation. Go to the [File system](/overview/file-system) to learn more. 29To set an image sourced from a file, use `lv_img_set_src(img, "S:folder1/my_img.bin")`. 30 31You can also set a symbol similarly to [Labels](/widgets/core/label). In this case, the image will be rendered as text according to the *font* specified in the style. It enables to use of light-weight monochrome "letters" instead of real images. You can set symbol like `lv_img_set_src(img1, LV_SYMBOL_OK)`. 32 33### Label as an image 34Images and labels are sometimes used to convey the same thing. For example, to describe what a button does. 35Therefore, images and labels are somewhat interchangeable, that is the images can display texts by using `LV_SYMBOL_DUMMY` as the prefix of the text. For example, `lv_img_set_src(img, LV_SYMBOL_DUMMY "Some text")`. 36 37 38### Transparency 39The internal (variable) and external images support 2 transparency handling methods: 40 41- **Chroma-keying** - Pixels with `LV_COLOR_CHROMA_KEY` (*lv_conf.h*) color will be transparent. 42- **Alpha byte** - An alpha byte is added to every pixel that contains the pixel's opacity 43 44### Palette and Alpha index 45Besides the *True color* (RGB) color format, the following formats are supported: 46- **Indexed** - Image has a palette. 47- **Alpha indexed** - Only alpha values are stored. 48 49These options can be selected in the image converter. To learn more about the color formats, read the [Images](/overview/image) section. 50 51### Recolor 52A color can be mixed with every pixel of an image with a given intensity. 53This can be useful to show different states (checked, inactive, pressed, etc.) of an image without storing more versions of the same image. 54This feature can be enabled in the style by setting `img_recolor_opa` between `LV_OPA_TRANSP` (no recolor, value: 0) and `LV_OPA_COVER` (full recolor, value: 255). 55The default value is `LV_OPA_TRANSP` so this feature is disabled. 56 57The color to mix is set by `img_recolor`. 58 59### Auto-size 60If the width or height of the image object is set to `LV_SIZE_CONTENT` the object's size will be set according to the size of the image source in the respective direction. 61 62### Mosaic 63If the object's size is greater than the image size in any directions, then the image will be repeated like a mosaic. 64This allows creation a large image from only a very narrow source. 65For example, you can have a *300 x 5* image with a special gradient and set it as a wallpaper using the mosaic feature. 66 67### Offset 68With `lv_img_set_offset_x(img, x_ofs)` and `lv_img_set_offset_y(img, y_ofs)`, you can add some offset to the displayed image. 69Useful if the object size is smaller than the image source size. 70Using the offset parameter a [Texture atlas](https://en.wikipedia.org/wiki/Texture_atlas) or a "running image" effect can be created by [Animating](/overview/animation) the x or y offset. 71 72## Transformations 73 74Using the `lv_img_set_zoom(img, factor)` the images will be zoomed. Set `factor` to `256` or `LV_IMG_ZOOM_NONE` to disable zooming. 75A larger value enlarges the images (e.g. `512` double size), a smaller value shrinks it (e.g. `128` half size). 76Fractional scale works as well. E.g. `281` for 10% enlargement. 77 78To rotate the image use `lv_img_set_angle(img, angle)`. Angle has 0.1 degree precision, so for 45.8° set 458. 79 80The `transform_zoom` and `transform_angle` style properties are also used to determine the final zoom and angle. 81 82By default, the pivot point of the rotation is the center of the image. It can be changed with `lv_img_set_pivot(img, pivot_x, pivot_y)`. `0;0` is the top left corner. 83 84The quality of the transformation can be adjusted with `lv_img_set_antialias(img, true/false)`. With enabled anti-aliasing the transformations are higher quality but slower. 85 86The transformations require the whole image to be available. Therefore indexed images (`LV_IMG_CF_INDEXED_...`), alpha only images (`LV_IMG_CF_ALPHA_...`) or images from files can not be transformed. 87In other words transformations work only on true color images stored as C array, or if a custom [Image decoder](/overview/images#image-edecoder) returns the whole image. 88 89Note that the real coordinates of image objects won't change during transformation. That is `lv_obj_get_width/height/x/y()` will return the original, non-zoomed coordinates. 90 91**IMPORTANT** 92The transformation of the image is independent of the transformation properties coming from styles. (See [here](/overview/style#opacity-and-transformations)). The main differences are that pure image widget transformation 93- doesn't transform the children of the image widget 94- image is transformed directly without creating an intermediate layer (buffer) to snapshot the widget 95 96### Size mode 97 98By default, when the image is zoomed or rotated the real coordinates of the image object are not changed. 99The larger content simply overflows the object's boundaries. 100It also means the layouts are not affected the by the transformations. 101 102If you need the object size to be updated to the transformed size set `lv_img_set_size_mode(img, LV_IMG_SIZE_MODE_REAL)`. (The previous mode is the default and called `LV_IMG_SIZE_MODE_VIRTUAL`). 103In this case if the width/height of the object is set to `LV_SIZE_CONTENT` the object's size will be set to the zoomed and rotated size. 104If an explicit size is set then the overflowing content will be cropped. 105 106### Rounded image 107 108You can use `lv_obj_set_style_radius` to set radius to an image, and enable `lv_obj_set_style_clip_corner` to clip the 109content to rounded rectangle or circular shape. Please note this will have some negative performance impact to CPU 110based renderers. 111 112## Events 113No special events are sent by image objects. 114 115See the events of the [Base object](/widgets/obj) too. 116 117Learn more about [Events](/overview/event). 118 119## Keys 120No *Keys* are processed by the object type. 121 122Learn more about [Keys](/overview/indev). 123 124## Example 125 126```eval_rst 127 128.. include:: ../../../examples/widgets/img/index.rst 129 130``` 131 132## API 133 134```eval_rst 135 136.. doxygenfile:: lv_img.h 137 :project: lvgl 138 139``` 140
