Image （图象）(lv_image)

Overview（概述）

显示原文

Images are the basic object to display images from flash (as arrays) or from files. Images can display symbols (LV_SYMBOL_...) too.

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

图像是显示来自闪存（数组）或来自文件的图像的基本对象。图像也可以显示符号 (LV_SYMBOL_...) 。

使用图像解码器接口( Image decoder interface) 也可以支持自定义图像格式。

Parts and Styles（部分和样式）

显示原文

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

LV_PART_MAIN 使用典型背景样式属性的背景矩形和使用图像样式（img）属性的图像本身。

Usage（用法）

Image source（图片来源）

显示原文

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

a variable in code (a C array with the pixels).
a file stored externally (e.g. on an SD card).
a text with Symbols.

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 with its pointer lv_image_set_src(img1, &converted_img_var) To make the variable visible in the C file, you need to 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 now you should select the binary output format. You 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 to learn more. To set an image sourced from a file, use lv_image_set_src(img, "S:folder1/my_img.bin") .

You can also set a symbol similarly to Labels. 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_image_set_src(img1, LV_SYMBOL_OK) .

为了提供最大的灵活性，图像的来源可以是：

代码中的变量（带有像素的 C 数组）。
外部存储的文件（例如在 SD 卡上）。
带有 Symbols(符号) 的文本。

要设置图像的来源，请使用 lv_image_set_src(img, src) 接口。

要从 PNG、JPG 或 BMP 图像生成像素数组，请使用 LVGL官网的在线图像转换工具并将转换后的图像指针（比如 converted_img_var ）通过接口函数 lv_image_set_src(img1, &converted_img_var) 使用。要使该变量在 C 文件中可见，需要使用 LV_IMAGE_DECLARE(converted_img_var) 声明它。

要使用外部文件，还需要使用 LVGL官网的在线图像转换工具转换图像文件，这时候需要选择转为二进制输出格式；转出来之后还需要使用 LVGL 的文件系统接口对接你适配好的文件系统驱动。要设置来自文件系统的二进制图像文件，请使用这样使用该接口 lv_image_set_src(img, "S:folder1/my_img.bin") 。

图像控件还可以显示类似于标签控件那样显示 Symbols(符号) 或者字符；在这种情况下，图像将根据样式中指定的 font 呈现文本。它允许使用轻量级单色 “字母” 而不是真实图像，例如 lv_image_set_src(img1, LV_SYMBOL_OK "Some text") 。

Label as an image（标签作为图象）

显示原文

Images and labels are sometimes used to convey the same thing. For example, to describe what a button does. Therefore, 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_image_set_src(img, LV_SYMBOL_DUMMY, "Some text").

图像和标签有时可以用于传达相同的内容，例如，描述按钮的作用。因此，图像和标签在某种程度上是可以互换的，也就是说图像可以通过使用 LV_SYMBOL_DUMMY 作为文本的前缀来显示文本。例如， lv_image_set_src(img, LV_SYMBOL_DUMMY "Some text") 。

Transparency（透明度）

显示原文

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

Alpha byte: An alpha byte is added to every pixel that contains the pixel's opacity

内部（变量）和外部图像支持 2 种透明度处理方法：

Alpha 字节 向每个包含像素不透明度的像素添加一个 Alpha 字节

Palette and Alpha index（调色板和 Alpha 索引）

显示原文

Besides the True color (RGB) color format, the following formats are supported:

Indexed: Image has a palette.
Alpha indexed: Only alpha values are stored.

These options can be selected in the image converter. To learn more about the color formats, read the Images section.

除了 True color (RGB) 颜色格式外，还支持以下格式：

Indexed（索引） ：图像有调色板。
Alpha indexed（透明度索引） ：仅存储 Alpha（透明度）值。

可以在图像转换器中选择这些选项。要了解有关颜色格式的更多信息，请阅读图像部分。

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 so this feature is disabled.

The color to mix is set by img_recolor.

颜色可以与具有给定强度的图像的每个像素混合。这对于显示图像的不同状态（选中、非活动、按下等）非常有用，而无需存储同一图像的更多版本。可以通过在 LV_OPA_TRANSP （无重新着色，值：0）和 LV_OPA_COVER （完全重新着色，值：255）之间设置 image_recolor_opa 在样式中启用此功能。默认值为 LV_OPA_TRANSP 因此禁用此功能。

要混合的颜色通过 image_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 object 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.

可以通过接口 lv_image_set_offset_x(img, x_ofs) 和 lv_image_set_offset_y(img, y_ofs) 为显示的图像添加一些偏移，这在对象尺寸小于图像源大小的情况下非常有用。使用偏移参数，可以创建一个纹理图集或 "运行图像 "效果，可以通过动画 Animating 设置 x 或 y 偏移量。

Transformations（转换）

显示原文

Using the lv_image_set_scale(img, factor) the images will be zoomed. 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 scale works as well. E.g. 281 for 10% enlargement.

lv_image_set_scale_x(img, factor) and lv_image_set_scale_y(img, factor) also can be used to the scale independently horizontally and vertically (non-uniform scale).

To rotate the image use lv_image_set_rotation(img, angle). Angle has 0.1 degree precision, so for 45.8° set 458.

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

The quality of the transformation can be adjusted with lv_image_set_antialias(img, true). With enabled anti-aliasing the transformations are higher quality but slower.

The transformations require the whole image to be available. Therefore indexed images (LV_COLOR_FORMAT_I1/2/4/8_...), alpha only images cannot be transformed. In other words transformations work only on normal (A)RGB or A8 images stored as C array, or if a custom Image decoder（图像解码器） returns the whole image.

Note 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.

IMPORTANT The transformation of the image is independent of the transformation properties coming from styles. (See here). The main differences are that pure image widget transformation

doesn't transform the children of the image widget
image is transformed directly without creating an intermediate layer (buffer) to snapshot the widget

可以通过接口 lv_image_set_scale(img, factor) 缩放图像，参数 factor 控制缩放，将其设置为 256 或 LV_SCALE_NONE 就是不进行缩放；一个较大的值会放大图像（例如 512 放大两倍），较小的值会缩小它（例如 128 缩小一半）；分数缩放也可以同样有效。例如 281 用于 10% 的放大。

可以通过函数 lv_image_set_scale_x(img, factor) 和 lv_image_set_scale_y(img, factor) 进行水平和垂直独立缩放（非均匀缩放）。

要旋转图像，请使用 lv_image_set_rotation(img, angle) ；参数 factor 控制角度，其角度精度为 0.1 度，比如，要设置为 45.8° 将其设置为458。

默认情况下，旋转的轴心点是图像的中心，可以通过函数 lv_image_set_pivot(img, pivot_x, pivot_y) 更改轴心点；参数 pivot_x , pivot_y 就是要指定的轴心点坐标，比如 [0, 0] 意思是将轴心点改到图像的左上角。

转换的质量可以通过函数 lv_image_set_antialias(img, true) 进行调整；启用抗锯齿会让转换质量更高，但速度较慢。

转换需要整个图像可用。因此索引图像 (LV_COLOR_FORMAT_I1/2/4/8_...)，仅 Alpha 图像无法转换。换言之，转换仅适用于存储为 C 数组的普通 (A)RGB 或 A8 图像有效，或者如果自定义 Image decoder（图像解码器）返回整个图像。

注意，图像对象的真实坐标在转换过程中不会改变。也就是说，lv_obj_get_width / height / x / y() 将返回原始的、未缩放的坐标。

重要图像的转换与来自样式的转换属性无关，(请阅读这里 )。主要区别在于纯图像控件的转换。

不会转换图像控件的子项
图像直接转换，无需创建中间层（缓冲区）来快照控件

Inner align（内部对齐）

显示原文

By default the image widget's width and height is LV_SIZE_CONTENT. It means that the widget will be sized automatically according to the image source.

If the widget's width or height is set the larger value the inner_align property tells how to align the image source inside the widget.

The alignment set any of these:

The offset value is applied after the image source is aligned. For example setting an y=-10 and LV_IMAGE_ALIGN_CENTER will move the image source up a little bit from the center of the widget.

Or to automatically scale or tile the image

LV_IMAGE_ALIGN_STRETCH Set X and Y scale to fill the widget's area
LV_IMAGE_ALIGN_TILE Tile the image to will the widget area. Offset is applied to shift the tiling.

The alignment can be set by lv_image_set_inner_align()

默认情况下，图像控件的宽度和高度为 LV_SIZE_CONTENT ，也就是说其会根据图像源自动调整大小。

如果宽度或高度设置为较大的值，则 inner_align 属性会告知如何在图像控件内对齐图像源。

对齐方式可以设置为：

offset（偏移） 值在图像源对齐后应用。例如，设置 y=-10 和 LV_IMAGE_ALIGN_CENTER 将使图像源从控件的中心向上移动一些。

或者自动缩放或平铺图像

LV_IMAGE_ALIGN_STRETCH 自动根据 X 和 Y 的比例来平铺填充控件的区域，即使控件区域不对称。
LV_IMAGE_ALIGN_TILE 将图像像印章那样平铺满控件区域，底层应用 offset（偏移）来移动平铺。

对齐方式可以通过调用此函数设置 lv_image_set_inner_align()

Events（事件）

显示原文

No special events are sent by image objects.

See the events of the Base object too.

Learn more about Events（事件）.

图像对象不发送特殊事件。

请阅读基本对象的事件。

详细了解更多 Events（事件）。

Keys（按键）

显示原文

No Keys are processed by the object type.

Learn more about Keys（按键）.

图像对象不处理 Keys 。

阅读了解有关 Keys（按键）的更多信息。

Example

[English]

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_playback_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_playback_duration(&a, 500);
    lv_anim_set_repeat_count(&a, LV_ANIM_REPEAT_INFINITE);
    lv_anim_start(&a);

}

#endif

API

lv_image_header_cache.h

lv_image_dsc.h

lv_obj_property_names.h