Canvas（画布）(lv_canvas)
Overview（概述）
显示原文
A Canvas inherits from Image where the user can draw anything. Rectangles, texts, images, lines, arcs can be drawn here using lvgl's drawing engine.
Canvas（画布） 继承自 Image ，用户可以在其中绘制任何内容：矩形、文本、图像、线条、圆弧可以在这里使用lvgl的绘图引擎绘制。
Parts and Styles（部分和样式）
LV_PART_MAIN使用典型的矩形样式属性和图像样式属性。
Usage（用法）
Buffer（缓冲区）
显示原文
The Canvas needs a buffer in which it stores the drawn image. To assign a
buffer to a Canvas, use
lv_canvas_set_buffer(canvas, buffer, width, height, LV_COLOR_FORMAT_...).
Where buffer is a static buffer (not just a local variable) to hold
the image of the canvas. For example for a 100x50 ARGB8888 buffer:
static uint8_t buffer[100 * 50 * 4].
Or you can use
static uint8_t buffer[LV_CANVAS_BUF_SIZE(width, height, bit_per_pixel, stride_in_bytes)].
The canvas supports all the color formats like
LV_COLOR_FORMAT_ARGB8888 or LV_COLOR_FORMAT_I2. See the full
list in the Color formats section.
Canvas 需要一个缓冲区来存储绘制的图像。 要为 Canvas 分配缓冲区，请使用函数 lv_canvas_set_buffer(canvas, buffer, width, height, LV_COLOR_FORMAT_...) ， 其中参数 buffer 是一个静态缓冲区（不能是局部变量）来保存画布的图像。例如，对于 100x50 的 ARGB888缓冲区，可以这样分配：
static uint8_t buffer[100 * 50 * 4]static uint8_t buffer[LV_CANVAS_BUF_SIZE(width, height, bit_per_pixel, stride_in_bytes)]
画布支持所有LVGL内置支持的颜色格式，如 LV_COLOR_FORMAT_ARGB8888 或 LV_COLOR_FORMAT_I2 ，请阅读 Color formats 了解完整的格式列表。
Indexed colors（颜色索引）
显示原文
For LV_COLOR_FORMAT_I1/2/4/8 color formats a palette needs to be
initialized with lv_canvas_set_palette(canvas, 3, lv_color_hex(0xff0000)). It
sets pixels with index=3 to red.
对于 LV_COLOR_FORMAT_I1/2/4/8 颜色格式，调色板需要用 lv_canvas_set_palette(canvas, 3, lv_color_hex(0xff0000)) 初始化。 它将 index=3 的像素设置为红色
Drawing（画画）
显示原文
To set a pixel's color on the canvas, use
lv_canvas_set_px_color(canvas, x, y, color, opa). With
LV_COLOR_FORMAT_I1/2/4/8 the index of the color needs to be passed as
color like this lv_color_from_int(13);. It passes index 13 as a color.
lv_canvas_fill_bg(canvas, lv_color_hex(0x00ff00), LV_OPA_50) fills the whole
canvas to blue with 50% opacity. Note that if the current color format
doesn't support colors (e.g. LV_COLOR_FORMAT_A8) the color will be
ignored. Similarly, if opacity is not supported
(e.g. LV_COLOR_FORMAT_RGB565) it will be ignored.
An array of pixels can be copied to the canvas with lv_canvas_copy_buf(canvas, buffer_to_copy, x, y, width, height). The color format of the buffer and the canvas need to match.
To draw something to the canvas use LVGL's draw functions directly. See the examples for more details.
The draw function can draw to any color format to which LVGL can render. Typically it means
LV_COLOR_FORMAT_RGB565, LV_COLOR_FORMAT_RGB888,
LV_COLOR_FORMAT_XRGB888, and LV_COLOR_FORMAT_ARGB8888.
要在画布上设置像素，请使用 lv_canvas_set_px_color(canvas, x, y, color, opa) 。 对于 LV_COLOR_FORMAT_I1/2/4/8 颜色索引需要像这样 lv_color_from_int(13); 传递，它将颜色索引 13 作为颜色传递。
lv_canvas_fill_bg(canvas, lv_color_hex(0x00ff00), LV_OPA_50) 将整个画布填充为蓝色，不透明度为 50%。 请注意，如果当前颜色格式不支持(例如 LV_COLOR_FORMAT_A8)，则该颜色将被忽略。同样，如果不支持不透明度(例如 LV_COLOR_FORMAT_RGB565)，不透明度将被忽略。
可以使用 lv_canvas_copy_buf(canvas, buffer_to_copy, x, y, width, height) 将像素数组复制到画布。缓冲区和画布的颜色格式需要一致。
要在画布上绘制内容，请直接使用 LVGL 的绘制函数。有关更多详细信息，请参阅后面的示例。
draw 函数可以绘制为 LVGL 可以渲染的任何颜色格式，通常是： LV_COLOR_FORMAT_RGB565 、 LV_COLOR_FORMAT_RGB888 、 LV_COLOR_FORMAT_XRGB888 、LV_COLOR_FORMAT_ARGB8888
Events（事件）
显示原文
No special events are sent by canvas objects. The same events are sent as for the
See the events of the lv_image.h too.
Learn more about Events（事件）.
画布对象不会发送特殊事件。
也可以阅读 lv_image.h 的事件。
详细了解更多阅读 Events（事件）。
Keys（按键）
对象类型不处理 Keys。
阅读了解有关 Keys（按键） 的更多信息
Example
Drawing on the Canvas and rotate
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_CANVAS && LV_BUILD_EXAMPLES
#define CANVAS_WIDTH 200
#define CANVAS_HEIGHT 150
void lv_example_canvas_1(void)
{
lv_draw_rect_dsc_t rect_dsc;
lv_draw_rect_dsc_init(&rect_dsc);
rect_dsc.radius = 10;
rect_dsc.bg_opa = LV_OPA_COVER;
rect_dsc.bg_grad.dir = LV_GRAD_DIR_VER;
rect_dsc.bg_grad.stops[0].color = lv_palette_main(LV_PALETTE_RED);
rect_dsc.bg_grad.stops[0].opa = LV_OPA_100;
rect_dsc.bg_grad.stops[1].color = lv_palette_main(LV_PALETTE_BLUE);
rect_dsc.bg_grad.stops[1].opa = LV_OPA_50;
rect_dsc.border_width = 2;
rect_dsc.border_opa = LV_OPA_90;
rect_dsc.border_color = lv_color_white();
rect_dsc.shadow_width = 5;
rect_dsc.shadow_offset_x = 5;
rect_dsc.shadow_offset_y = 5;
lv_draw_label_dsc_t label_dsc;
lv_draw_label_dsc_init(&label_dsc);
label_dsc.color = lv_palette_main(LV_PALETTE_ORANGE);
label_dsc.text = "Some text on text canvas";
/*Create a buffer for the canvas*/
LV_DRAW_BUF_DEFINE_STATIC(draw_buf_16bpp, CANVAS_WIDTH, CANVAS_HEIGHT, LV_COLOR_FORMAT_RGB565);
LV_DRAW_BUF_INIT_STATIC(draw_buf_16bpp);
lv_obj_t * canvas = lv_canvas_create(lv_screen_active());
lv_canvas_set_draw_buf(canvas, &draw_buf_16bpp);
lv_obj_center(canvas);
lv_canvas_fill_bg(canvas, lv_palette_lighten(LV_PALETTE_GREY, 3), LV_OPA_COVER);
lv_layer_t layer;
lv_canvas_init_layer(canvas, &layer);
lv_area_t coords_rect = {30, 20, 100, 70};
lv_draw_rect(&layer, &rect_dsc, &coords_rect);
lv_area_t coords_text = {40, 80, 100, 120};
lv_draw_label(&layer, &label_dsc, &coords_text);
lv_canvas_finish_layer(canvas, &layer);
/*Test the rotation. It requires another buffer where the original image is stored.
*So use previous canvas as image and rotate it to the new canvas*/
LV_DRAW_BUF_DEFINE_STATIC(draw_buf_32bpp, CANVAS_WIDTH, CANVAS_HEIGHT, LV_COLOR_FORMAT_ARGB8888);
LV_DRAW_BUF_INIT_STATIC(draw_buf_32bpp);
/*Create a canvas and initialize its palette*/
canvas = lv_canvas_create(lv_screen_active());
lv_canvas_set_draw_buf(canvas, &draw_buf_32bpp);
lv_canvas_fill_bg(canvas, lv_color_hex3(0xccc), LV_OPA_COVER);
lv_obj_center(canvas);
lv_canvas_fill_bg(canvas, lv_palette_lighten(LV_PALETTE_GREY, 1), LV_OPA_COVER);
lv_canvas_init_layer(canvas, &layer);
lv_image_dsc_t img;
lv_draw_buf_to_image(&draw_buf_16bpp, &img);
lv_draw_image_dsc_t img_dsc;
lv_draw_image_dsc_init(&img_dsc);
img_dsc.rotation = 120;
img_dsc.src = &img;
img_dsc.pivot.x = CANVAS_WIDTH / 2;
img_dsc.pivot.y = CANVAS_HEIGHT / 2;
lv_area_t coords_img = {0, 0, CANVAS_WIDTH - 1, CANVAS_HEIGHT - 1};
lv_draw_image(&layer, &img_dsc, &coords_img);
lv_canvas_finish_layer(canvas, &layer);
}
#endif
Transparent Canvas with chroma keying
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_CANVAS && LV_BUILD_EXAMPLES
#define CANVAS_WIDTH 80
#define CANVAS_HEIGHT 40
/**
* Create a transparent canvas with transparency
*/
void lv_example_canvas_2(void)
{
lv_obj_set_style_bg_color(lv_screen_active(), lv_palette_lighten(LV_PALETTE_RED, 5), 0);
/*Create a buffer for the canvas*/
LV_DRAW_BUF_DEFINE_STATIC(draw_buf, CANVAS_WIDTH, CANVAS_HEIGHT, LV_COLOR_FORMAT_ARGB8888);
LV_DRAW_BUF_INIT_STATIC(draw_buf);
/*Create a canvas and initialize its palette*/
lv_obj_t * canvas = lv_canvas_create(lv_screen_active());
lv_canvas_set_draw_buf(canvas, &draw_buf);
lv_obj_center(canvas);
/*Red background (There is no dedicated alpha channel in indexed images so LV_OPA_COVER is ignored)*/
lv_canvas_fill_bg(canvas, lv_palette_main(LV_PALETTE_BLUE), LV_OPA_COVER);
/*Create hole on the canvas*/
uint32_t x;
uint32_t y;
for(y = 10; y < 20; y++) {
for(x = 5; x < 75; x++) {
lv_canvas_set_px(canvas, x, y, lv_palette_main(LV_PALETTE_BLUE), LV_OPA_50);
}
}
for(y = 20; y < 30; y++) {
for(x = 5; x < 75; x++) {
lv_canvas_set_px(canvas, x, y, lv_palette_main(LV_PALETTE_BLUE), LV_OPA_20);
}
}
for(y = 30; y < 40; y++) {
for(x = 5; x < 75; x++) {
lv_canvas_set_px(canvas, x, y, lv_palette_main(LV_PALETTE_BLUE), LV_OPA_0);
}
}
}
#endif
Draw a rectangle to the canvas
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_CANVAS && LV_BUILD_EXAMPLES
#define CANVAS_WIDTH 50
#define CANVAS_HEIGHT 50
/**
* Draw a rectangle to the canvas
*/
void lv_example_canvas_3(void)
{
/*Create a buffer for the canvas*/
LV_DRAW_BUF_DEFINE_STATIC(draw_buf, CANVAS_WIDTH, CANVAS_HEIGHT, LV_COLOR_FORMAT_ARGB8888);
LV_DRAW_BUF_INIT_STATIC(draw_buf);
/*Create a canvas and initialize its palette*/
lv_obj_t * canvas = lv_canvas_create(lv_screen_active());
lv_canvas_set_draw_buf(canvas, &draw_buf);
lv_canvas_fill_bg(canvas, lv_color_hex3(0xccc), LV_OPA_COVER);
lv_obj_center(canvas);
lv_layer_t layer;
lv_canvas_init_layer(canvas, &layer);
lv_draw_rect_dsc_t dsc;
lv_draw_rect_dsc_init(&dsc);
dsc.bg_color = lv_palette_main(LV_PALETTE_RED);
dsc.border_color = lv_palette_main(LV_PALETTE_BLUE);
dsc.border_width = 3;
dsc.outline_color = lv_palette_main(LV_PALETTE_GREEN);
dsc.outline_width = 2;
dsc.outline_pad = 2;
dsc.outline_opa = LV_OPA_50;
dsc.radius = 5;
dsc.border_width = 3;
lv_area_t coords = {10, 10, 40, 30};
lv_draw_rect(&layer, &dsc, &coords);
lv_canvas_finish_layer(canvas, &layer);
}
#endif
Draw a label to the canvas
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_CANVAS && LV_FONT_MONTSERRAT_18 && LV_BUILD_EXAMPLES
#define CANVAS_WIDTH 50
#define CANVAS_HEIGHT 50
/**
* Draw a text to the canvas
*/
void lv_example_canvas_4(void)
{
/*Create a buffer for the canvas*/
LV_DRAW_BUF_DEFINE_STATIC(draw_buf, CANVAS_WIDTH, CANVAS_HEIGHT, LV_COLOR_FORMAT_ARGB8888);
LV_DRAW_BUF_INIT_STATIC(draw_buf);
/*Create a canvas and initialize its palette*/
lv_obj_t * canvas = lv_canvas_create(lv_screen_active());
lv_canvas_set_draw_buf(canvas, &draw_buf);
lv_canvas_fill_bg(canvas, lv_color_hex3(0xccc), LV_OPA_COVER);
lv_obj_center(canvas);
lv_layer_t layer;
lv_canvas_init_layer(canvas, &layer);
lv_draw_label_dsc_t dsc;
lv_draw_label_dsc_init(&dsc);
dsc.color = lv_palette_main(LV_PALETTE_RED);
dsc.font = &lv_font_montserrat_18;
dsc.decor = LV_TEXT_DECOR_UNDERLINE;
dsc.text = "Hello";
lv_area_t coords = {10, 10, 30, 60};
lv_draw_label(&layer, &dsc, &coords);
lv_canvas_finish_layer(canvas, &layer);
}
#endif
Draw an arc to the canvas
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_CANVAS && LV_BUILD_EXAMPLES
#define CANVAS_WIDTH 50
#define CANVAS_HEIGHT 50
/**
* Draw an arc to the canvas
*/
void lv_example_canvas_5(void)
{
/*Create a buffer for the canvas*/
LV_DRAW_BUF_DEFINE_STATIC(draw_buf, CANVAS_WIDTH, CANVAS_HEIGHT, LV_COLOR_FORMAT_ARGB8888);
LV_DRAW_BUF_INIT_STATIC(draw_buf);
/*Create a canvas and initialize its palette*/
lv_obj_t * canvas = lv_canvas_create(lv_screen_active());
lv_canvas_set_draw_buf(canvas, &draw_buf);
lv_canvas_fill_bg(canvas, lv_color_hex3(0xccc), LV_OPA_COVER);
lv_obj_center(canvas);
lv_layer_t layer;
lv_canvas_init_layer(canvas, &layer);
lv_draw_arc_dsc_t dsc;
lv_draw_arc_dsc_init(&dsc);
dsc.color = lv_palette_main(LV_PALETTE_RED);
dsc.width = 5;
dsc.center.x = 25;
dsc.center.y = 25;
dsc.width = 10;
dsc.radius = 15;
dsc.start_angle = 0;
dsc.end_angle = 220;
lv_draw_arc(&layer, &dsc);
lv_canvas_finish_layer(canvas, &layer);
}
#endif
Draw an image to the canvas
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_CANVAS && LV_BUILD_EXAMPLES
#define CANVAS_WIDTH 50
#define CANVAS_HEIGHT 50
/**
* Draw an image to the canvas
*/
void lv_example_canvas_6(void)
{
/*Create a buffer for the canvas*/
static uint8_t cbuf[LV_CANVAS_BUF_SIZE(CANVAS_WIDTH, CANVAS_HEIGHT, 32, LV_DRAW_BUF_STRIDE_ALIGN)];
/*Create a canvas and initialize its palette*/
lv_obj_t * canvas = lv_canvas_create(lv_screen_active());
lv_canvas_set_buffer(canvas, cbuf, CANVAS_WIDTH, CANVAS_HEIGHT, LV_COLOR_FORMAT_ARGB8888);
lv_canvas_fill_bg(canvas, lv_color_hex3(0xccc), LV_OPA_COVER);
lv_obj_center(canvas);
lv_layer_t layer;
lv_canvas_init_layer(canvas, &layer);
LV_IMAGE_DECLARE(img_star);
lv_draw_image_dsc_t dsc;
lv_draw_image_dsc_init(&dsc);
dsc.src = &img_star;
lv_area_t coords = {10, 10, 10 + img_star.header.w - 1, 10 + img_star.header.h - 1};
lv_draw_image(&layer, &dsc, &coords);
lv_canvas_finish_layer(canvas, &layer);
}
#endif
Draw a line to the canvas
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_CANVAS&& LV_BUILD_EXAMPLES
#define CANVAS_WIDTH 50
#define CANVAS_HEIGHT 50
/**
* Draw a line to the canvas
*/
void lv_example_canvas_7(void)
{
/*Create a buffer for the canvas*/
LV_DRAW_BUF_DEFINE_STATIC(draw_buf, CANVAS_WIDTH, CANVAS_HEIGHT, LV_COLOR_FORMAT_ARGB8888);
LV_DRAW_BUF_INIT_STATIC(draw_buf);
/*Create a canvas and initialize its palette*/
lv_obj_t * canvas = lv_canvas_create(lv_screen_active());
lv_canvas_set_draw_buf(canvas, &draw_buf);
lv_canvas_fill_bg(canvas, lv_color_hex3(0xccc), LV_OPA_COVER);
lv_obj_center(canvas);
lv_layer_t layer;
lv_canvas_init_layer(canvas, &layer);
lv_draw_line_dsc_t dsc;
lv_draw_line_dsc_init(&dsc);
dsc.color = lv_palette_main(LV_PALETTE_RED);
dsc.width = 4;
dsc.round_end = 1;
dsc.round_start = 1;
dsc.p1.x = 15;
dsc.p1.y = 15;
dsc.p2.x = 35;
dsc.p2.y = 10;
lv_draw_line(&layer, &dsc);
lv_canvas_finish_layer(canvas, &layer);
}
#endif
Draw a vector graphic to the canvas
C code
View on GitHub#include "../../lv_examples.h"
#if LV_USE_CANVAS && LV_BUILD_EXAMPLES
#if LV_USE_VECTOR_GRAPHIC
#define CANVAS_WIDTH 150
#define CANVAS_HEIGHT 150
/**
* Draw a path to the canvas
*/
void lv_example_canvas_8(void)
{
/*Create a buffer for the canvas*/
LV_DRAW_BUF_DEFINE_STATIC(draw_buf, CANVAS_WIDTH, CANVAS_HEIGHT, LV_COLOR_FORMAT_ARGB8888);
LV_DRAW_BUF_INIT_STATIC(draw_buf);
/*Create a canvas and initialize its palette*/
lv_obj_t * canvas = lv_canvas_create(lv_screen_active());
lv_canvas_set_draw_buf(canvas, &draw_buf);
lv_canvas_fill_bg(canvas, lv_color_hex3(0xccc), LV_OPA_COVER);
lv_obj_center(canvas);
lv_layer_t layer;
lv_canvas_init_layer(canvas, &layer);
lv_vector_dsc_t * dsc = lv_vector_dsc_create(&layer);
lv_vector_path_t * path = lv_vector_path_create(LV_VECTOR_PATH_QUALITY_MEDIUM);
lv_fpoint_t pts[] = {{10, 10}, {130, 130}, {10, 130}};
lv_vector_path_move_to(path, &pts[0]);
lv_vector_path_line_to(path, &pts[1]);
lv_vector_path_line_to(path, &pts[2]);
lv_vector_path_close(path);
lv_vector_dsc_set_fill_color(dsc, lv_color_make(0x00, 0x80, 0xff));
lv_vector_dsc_add_path(dsc, path);
lv_draw_vector(dsc);
lv_vector_path_delete(path);
lv_vector_dsc_delete(dsc);
lv_canvas_finish_layer(canvas, &layer);
}
#else
void lv_example_canvas_8(void)
{
/*fallback for online examples*/
lv_obj_t * label = lv_label_create(lv_screen_active());
lv_label_set_text(label, "Vector graphics is not enabled");
lv_obj_center(label);
}
#endif /*LV_USE_VECTOR_GRAPHIC*/
#endif