Image (lv_image)

Overview

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

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 Online image converter tool 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 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 the True color (RGB) color format, 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 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 decoder 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:

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.

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.

Example

Image from variable and symbol

#include "../../lv_examples.h"
#if LV_USE_IMAGE && LV_BUILD_EXAMPLES

void lv_example_image_1(void)
{
    LV_IMAGE_DECLARE(img_cogwheel_argb);
    lv_obj_t * img1 = lv_image_create(lv_screen_active());
    lv_image_set_src(img1, &img_cogwheel_argb);
    lv_obj_align(img1, LV_ALIGN_CENTER, 0, 0);

    lv_obj_t * img2 = lv_image_create(lv_screen_active());
    lv_image_set_src(img2, LV_SYMBOL_OK "Accept");
    lv_obj_align_to(img2, img1, LV_ALIGN_OUT_BOTTOM_MID, 0, 20);
}

#endif

Image recoloring

#include "../../lv_examples.h"
#if LV_USE_IMAGE && LV_USE_SLIDER && LV_BUILD_EXAMPLES

static lv_obj_t * create_slider(lv_color_t color);
static void slider_event_cb(lv_event_t * e);

static lv_obj_t * red_slider, * green_slider, * blue_slider, * intense_slider;
static lv_obj_t * img1;

/**
 * Demonstrate runtime image re-coloring
 */
void lv_example_image_2(void)
{
    /*Create 4 sliders to adjust RGB color and re-color intensity*/
    red_slider = create_slider(lv_palette_main(LV_PALETTE_RED));
    green_slider = create_slider(lv_palette_main(LV_PALETTE_GREEN));
    blue_slider = create_slider(lv_palette_main(LV_PALETTE_BLUE));
    intense_slider = create_slider(lv_palette_main(LV_PALETTE_GREY));

    lv_slider_set_value(red_slider, LV_OPA_20, LV_ANIM_OFF);
    lv_slider_set_value(green_slider, LV_OPA_90, LV_ANIM_OFF);
    lv_slider_set_value(blue_slider, LV_OPA_60, LV_ANIM_OFF);
    lv_slider_set_value(intense_slider, LV_OPA_50, LV_ANIM_OFF);

    lv_obj_align(red_slider, LV_ALIGN_LEFT_MID, 25, 0);
    lv_obj_align_to(green_slider, red_slider, LV_ALIGN_OUT_RIGHT_MID, 25, 0);
    lv_obj_align_to(blue_slider, green_slider, LV_ALIGN_OUT_RIGHT_MID, 25, 0);
    lv_obj_align_to(intense_slider, blue_slider, LV_ALIGN_OUT_RIGHT_MID, 25, 0);

    /*Now create the actual image*/
    LV_IMAGE_DECLARE(img_cogwheel_argb);
    img1 = lv_image_create(lv_screen_active());
    lv_image_set_src(img1, &img_cogwheel_argb);
    lv_obj_align(img1, LV_ALIGN_RIGHT_MID, -20, 0);

    lv_obj_send_event(intense_slider, LV_EVENT_VALUE_CHANGED, NULL);
}

static void slider_event_cb(lv_event_t * e)
{
    LV_UNUSED(e);

    /*Recolor the image based on the sliders' values*/
    lv_color_t color  = lv_color_make(lv_slider_get_value(red_slider), lv_slider_get_value(green_slider),
                                      lv_slider_get_value(blue_slider));
    lv_opa_t intense = lv_slider_get_value(intense_slider);
    lv_obj_set_style_image_recolor_opa(img1, intense, 0);
    lv_obj_set_style_image_recolor(img1, color, 0);
}

static lv_obj_t * create_slider(lv_color_t color)
{
    lv_obj_t * slider = lv_slider_create(lv_screen_active());
    lv_slider_set_range(slider, 0, 255);
    lv_obj_set_size(slider, 10, 200);
    lv_obj_set_style_bg_color(slider, color, LV_PART_KNOB);
    lv_obj_set_style_bg_color(slider, lv_color_darken(color, LV_OPA_40), LV_PART_INDICATOR);
    lv_obj_add_event_cb(slider, slider_event_cb, LV_EVENT_VALUE_CHANGED, NULL);
    return slider;
}

#endif

Rotate and zoom

#include "../../lv_examples.h"
#if LV_USE_IMAGE && LV_BUILD_EXAMPLES

static void set_angle(void * img, int32_t v)
{
    lv_image_set_rotation(img, v);
}

static void set_scale(void * img, int32_t v)
{
    lv_image_set_scale(img, v);
}

/**
 * Show transformations (zoom and rotation) using a pivot point.
 */
void lv_example_image_3(void)
{
    LV_IMAGE_DECLARE(img_cogwheel_argb);

    /*Now create the actual image*/
    lv_obj_t * img = lv_image_create(lv_screen_active());
    lv_image_set_src(img, &img_cogwheel_argb);
    lv_obj_align(img, LV_ALIGN_CENTER, 50, 50);
    lv_image_set_pivot(img, 0, 0);    /*Rotate around the top left corner*/

    lv_anim_t a;
    lv_anim_init(&a);
    lv_anim_set_var(&a, img);
    lv_anim_set_exec_cb(&a, set_angle);
    lv_anim_set_values(&a, 0, 3600);
    lv_anim_set_duration(&a, 5000);
    lv_anim_set_repeat_count(&a, LV_ANIM_REPEAT_INFINITE);
    lv_anim_start(&a);

    lv_anim_set_exec_cb(&a, set_scale);
    lv_anim_set_values(&a, 128, 256);
    lv_anim_set_reverse_duration(&a, 3000);
    lv_anim_start(&a);
}

#endif

Image offset and styling

#include "../../lv_examples.h"
#if LV_USE_IMAGE && LV_BUILD_EXAMPLES

static void ofs_y_anim(void * img, int32_t v)
{
    lv_image_set_offset_y(img, v);
}

/**
 * Image styling and offset
 */
void lv_example_image_4(void)
{
    LV_IMAGE_DECLARE(img_skew_strip);

    static lv_style_t style;
    lv_style_init(&style);
    lv_style_set_bg_color(&style, lv_palette_main(LV_PALETTE_YELLOW));
    lv_style_set_bg_opa(&style, LV_OPA_COVER);
    lv_style_set_image_recolor_opa(&style, LV_OPA_COVER);
    lv_style_set_image_recolor(&style, lv_color_black());

    lv_obj_t * img = lv_image_create(lv_screen_active());
    lv_obj_add_style(img, &style, 0);
    lv_image_set_src(img, &img_skew_strip);
    lv_obj_set_size(img, 150, 100);
    lv_obj_center(img);

    lv_anim_t a;
    lv_anim_init(&a);
    lv_anim_set_var(&a, img);
    lv_anim_set_exec_cb(&a, ofs_y_anim);
    lv_anim_set_values(&a, 0, 100);
    lv_anim_set_duration(&a, 3000);
    lv_anim_set_reverse_duration(&a, 500);
    lv_anim_set_repeat_count(&a, LV_ANIM_REPEAT_INFINITE);
    lv_anim_start(&a);

}

#endif