Image (lv_image)

---

Overview

Images are Widgets that display images from flash (as arrays) or from files. Images can also display symbols (LV_SYMBOL_...).

Using the Image decoder interface, custom image formats can be supported as well.

Parts and Styles

• LV_PART_MAIN A background rectangle that uses the typical background style properties, and the image itself uses the image style properties.

Usage

Image source

To provide maximum flexibility, the source of the image can be:

• a variable in code (a C array containing the pixels).
• a file stored externally (e.g. on an SD card).
• a Symbol as text.

To set the source of an image, use lv_image_set_src(img, src).

To generate a pixel array from a PNG, JPG or BMP image, use the LVGL Online Image Converter and set the converted image as the image source with its pointer with lv_image_set_src(img1, &converted_img_var). To make the converted image variable accessible from the C file, declare it with LV_IMAGE_DECLARE(converted_img_var).

To use external files, you also need to convert the image files using the online converter tool, but select the binary output format. You also need to use LVGL's file system module and register a driver with some functions for basic file operations. See File system to learn more. Then set the translated image as the image source with lv_image_set_src(img, "S:folder1/my_img.bin").

You can also set a symbol as an image source similar to a Labels. In this case, the image will be rendered as text according to the font specified in the style. It enables the use of light-weight monochrome "characters" instead of real images. You can set a symbol as an image source with lv_image_set_src(img1, LV_SYMBOL_OK).

Label as an image

Images and labels are sometimes used to convey the same thing, such as describing what a button does. In this context, images and labels are somewhat interchangeable: images can display text by using the macro LV_SYMBOL_DUMMY (which equates to a 3-byte C string containing a special code) as the prefix of the text. For example, lv_image_set_src(img, LV_SYMBOL_DUMMY "Some text").

Transparency

The internal (pixel array) and external images support 2 transparency handling methods:

• Alpha byte: An alpha channel is added to every pixel that contains its opacity, typically a byte. It is the 'A' in the various color formats that contain an alpha channel, such as ARGB8888, ARGB8565, ARGB1555, etc.
• Indexed transparent color: a specific index in a color palette serves to signal transparency for each pixel that uses it.

Palette and Alpha index

Besides RGB888 and ARGB8888 color formats, the following formats are supported:

• Indexed: Image has a color palette, and each pixel is an index into that palette.
• Alpha indexed: The values stored at pixel positions are alpha (opacity) values.

These options can be selected in the LVGL Online Image Converter. Learn more about color formats in the Color Formats section.

Recolor

A color can be mixed with every pixel of an image with a given intensity. This can be useful to show different states (checked, inactive, pressed, etc.) of an image without storing more versions of the same image. This 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). The default value is LV_OPA_TRANSP causing this feature to be disabled.

The color to mix is set by img_recolor.

Offset

With lv_image_set_offset_x(img, x_ofs) and lv_image_set_offset_y(img, y_ofs), you can add some offset to the displayed image. Useful if the Widget size is smaller than the image source size. Using the offset parameter a Texture atlas or a "running image" effect can be created by Animating the x or y offset.

Transformations

You can zoom images in or out by using lv_image_set_scale(img, factor). Set factor to 256 or LV_SCALE_NONE to disable zooming. A larger value enlarges the images (e.g. 512 double size), a smaller value shrinks it (e.g. 128 half size). Fractional scaling works using a value that is proportionally larger or smaller, e.g. 281 for 10% enlargement.

lv_image_set_scale_x(img, factor) and lv_image_set_scale_y(img, factor) can also be used to set the horizontal and vertical scaling independently. They can be different values.

To rotate the image use lv_image_set_rotation(img, angle_x10). The angle_x10 argument is an int32_t containing the angle (in degrees) multiplied by 10. This gives 0.1-degree resolution. Example: 458 means 45.8°.

By default, the pivot point of the rotation is the center of the image. This can be changed with lv_image_set_pivot(img, pivot_x, pivot_y) where the coordinates (0,0) represent the top left corner.

The quality of the transformation can be adjusted with lv_image_set_antialias(img, true). Enabling anti-aliasing causes the transformations to be of higher quality, but slower.

Transformations require the whole image to be available. Therefore indexed images (LV_COLOR_FORMAT_I1/2/4/8_...) and alpha only images cannot be transformed. In other words transformations work only on normal (A)RGB or A8 images stored as a C array, or on images provided by a custom Image Decoders that returns the whole image.

Note that the real coordinates of image Widgets do not change with a transformation. That is lv_obj_get_width/height/x/y will return the original, non-zoomed coordinates.

IMPORTANT: The transformation of the image is independent of the transformation properties coming from styles. The main differences are that pure Image Widget transformations:

• do not transform the children of the Image Widget, and
• the image is transformed directly without creating an intermediate layer (buffer) to snapshot the Widget.

Inner align

By default the image Widget's width and height are LV_SIZE_CONTENT, meaning that the Widget will be sized automatically to the size of its image source.

If the Widget's width or height is set to a different value, the value of the inner_align property (set using lv_image_set_inner_align(widget, align)) governs how the image source is aligned inside the Widget.

align can be any of these values:

• LV_IMAGE_ALIGN_DEFAULT: Meaning top left
• LV_IMAGE_ALIGN_TOP_LEFT
• LV_IMAGE_ALIGN_TOP_MID
• LV_IMAGE_ALIGN_TOP_RIGHT
• LV_IMAGE_ALIGN_BOTTOM_LEFT
• LV_IMAGE_ALIGN_BOTTOM_MID
• LV_IMAGE_ALIGN_BOTTOM_RIGHT
• LV_IMAGE_ALIGN_LEFT_MID
• LV_IMAGE_ALIGN_RIGHT_MID
• LV_IMAGE_ALIGN_CENTER
• LV_IMAGE_ALIGN_STRETCH
• LV_IMAGE_ALIGN_TILE
• LV_IMAGE_ALIGN_CONTAIN
• LV_IMAGE_ALIGN_COVER

Any offset value is applied after the image source is aligned. For example setting an offset of y=-10 with align == LV_IMAGE_ALIGN_CENTER will move the image source up 10 pixels from the center of the Widget.

To automatically scale or tile the image, pass one of these align values:

• LV_IMAGE_ALIGN_STRETCH Set X and Y scale to fill the Widget's area
• LV_IMAGE_ALIGN_TILE Tile image to fill Widget's area. Offset is applied to shift the tiling.
• LV_IMAGE_ALIGN_CONTAIN The image keeps its aspect ratio, but is resized to the maximum size that fits within the Widget's area.
• LV_IMAGE_ALIGN_COVER The image keeps its aspect ratio and fills the Widget's area.

Data binding

To get familiar with observers, subjects, and data bindings in general visit the Observer page.

This method of subscribing to a pointer Subject affects a Image Widget's source (src) value directly. Note that this is a one-way binding (Subject ==> Widget) so when the subject changes, the Image will be updated too.

It supports only pointer subjects.

• lv_image_bind_src(img, &subject)

Events

No special events are sent by Image Widgets. By default, Image Widgets are created without the LV_OBJ_FLAG_CLICKABLE flag, but you can add it to make an Image Widget detect and emit LV_EVENT_CLICKED events if desired.

Keys

No Keys are processed by Image Widgets.

Examples

Image from variable and symbol

Image recoloring

Rotate and zoom

Image offset and styling

API