==================================
画布(lv_canvas)
==================================

概述
##################################
画布继承自 `图像`_ ，用户可以在其中绘制任何内容。可以使用lvgl的绘图引擎在此处绘制矩形，文本，图像，线弧。除了一些“效果”，还可以应用，例如旋转，缩放和模糊。

.. _图像: http://lvgl.100ask.net/documentation/04_widgets/14_img.html


零件和样式
##################################
画布的一个主要部分称为 ``LV_CANVAS_PART_MAIN`` ，只有image_recolor属性用于为 ``LV_IMG_CF_ALPHA_1/2/4/8BIT`` 图像赋予颜色。


用法
##################################

缓冲区
**********************************
画布需要一个缓冲区来存储绘制的图像。要将缓冲区分配给画布，请使用 ``lv_canvas_set_buffer(canvas, buffer, width, height, LV_IMG_CF_...)`` 。其中 ``buffer`` 是用于保存画布图像的静态缓冲区（而不仅仅是局部变量）。例如， ``static lv_color_t buffer[LV_CANVAS_BUF_SIZE_TRUE_COLOR(width, height)]`` 。 ``LV_CANVAS_BUF_SIZE_...`` 宏有助于确定不同颜色格式的缓冲区大小。

画布支持所有内置的颜色格式，例如 ``LV_IMG_CF_TRUE_COLOR`` 或 ``LV_IMG_CF_INDEXED_2BIT`` 。请参阅 `颜色格式`_ 部分中的完整列表。

.. _颜色格式: http://lvgl.100ask.net/documentation/03_overview/08_image.html#id4


调色板
**********************************
对于 ``LV_IMG_CF_INDEXED_...`` 颜色格式，需要使用 ``lv_canvas_set_palette(canvas, 3, LV_COLOR_RED)`` 初始化调色板。它将 index=3 的像素设置为红色。


画画
**********************************
要在画布上设置像素，请使用 ``lv_canvas_set_px(canvas, x, y, LV_COLOR_RED)`` 。对于 ``LV_IMG_CF_INDEXED _...`` 或 ``LV_IMG_CF_ALPHA _...`` ，需要将颜色的索引或alpha值作为颜色传递。例如：  ``lv_color_t c; c.full = 3`` ;

``lv_canvas_fill_bg(canvas, LV_COLOR_BLUE, LV_OPA_50)`` 将整个画布填充为蓝色，不透明度为50％。请注意，如果当前的颜色格式不支持颜色（例如 ``LV_IMG_CF_ALPHA_2BIT`` ），则会忽略颜色。同样，如果不支持不透明度（例如 ``LV_IMG_CF_TRUE_COLOR`` ），则会将其忽略。

可以使用 ``lv_canvas_copy_buf(canvas, buffer_to_copy, x, y, width, height)`` 将像素数组复制到画布。缓冲区和画布的颜色格式需要匹配。


画一些东西到画布上使用

- ``lv_canvas_draw_rect(canvas, x, y, width, heigth, &draw_dsc)``
- ``lv_canvas_draw_text(canvas, x, y, max_width, &draw_dsc, txt, LV_LABEL_ALIGN_LEFT/CENTER/RIGHT)``
- ``lv_canvas_draw_img(canvas, x, y, &img_src, &draw_dsc)``
- ``lv_canvas_draw_line(canvas, point_array, point_cnt, &draw_dsc)``
- ``lv_canvas_draw_polygon(canvas, points_array, point_cnt, &draw_dsc)``
- ``lv_canvas_draw_arc(canvas, x, y, radius, start_angle, end_angle, &draw_dsc)``


``draw_dsc`` 是 ``lv_draw_rect/label/img/line_dsc_t`` 变量，应首先使用 ``lv_draw_rect/label/img/line_dsc_init()`` 函数初始化，然后使用所需的颜色和其他值对其进行修改。

绘制功能可以绘制为任何颜色格式。例如，可以在 ``LV_IMG_VF_ALPHA_8BIT`` 画布上绘制文本，然后将结果图像用作lv_objmask中的蒙版。


旋转和缩放
**********************************
``lv_canvas_transform()`` 可用于旋转和/或缩放图像的图像并将结果存储在画布上。该函数需要以下参数：


- ``canvas`` 指向画布对象以存储转换结果的指针。
- ``img pointer`` 转换为图像描述符。也可以是其他画布的图像描述符（ ``lv_canvas_get_img()`` ）。
- ``angle`` 旋转角度（0..3600），0.1度分辨率
- ``zoom`` 缩放系数（256不缩放，512倍大小，128个一半大小）；
- ``offset_x`` 偏移量X，以指示将结果数据放在目标画布上的位置
- ``offset_y`` 偏移量Y，以指示将结果数据放在目标画布上的位置
- ``pivot_x`` 旋转的X轴。相对于源画布。设置为 ``源宽度/ 2`` 以围绕中心旋转
- ``pivot_y`` 旋转的枢轴Y。相对于源画布。设置为 ``源高度/ 2`` 以围绕中心旋转
- ``antialias`` true：在转换过程中应用抗锯齿。看起来更好，但速度较慢。

请注意，画布无法自身旋转。您需要源和目标画布或图像。


模糊效果
##################################
画布的给定区域可以使用 ``lv_canvas_blur_hor(canvas, &area, r)`` 水平模糊，垂直使用 ``lv_canvas_blur_ver(canvas, &area, r)`` 模糊。r是模糊的半径（值越大表示毛刺强度越大）。  ``area`` 是应该应用模糊的区域（相对于画布进行解释）


事件
##################################
默认情况下，画布的单击被禁用（由Image继承），因此不生成任何事件。

如果启用了单击（lv_obj_set_click（canvas，true）），则仅 `通用事件`_ 由对象类型发送。

了解有关 `事件`_ 的更多信息。

.. _通用事件: http://lvgl.100ask.net/documentation/03_overview/03_events.html#id2
.. _事件: http://lvgl.100ask.net/documentation/03_overview/03_events.html



按键
##################################
画布对象类型不处理任何键。 


进一步了解 `按键`_ 。

.. _按键: http://lvgl.100ask.net/documentation/03_overview/05_indev.html



范例
##################################

在画布上绘图并旋转
**********************************

.. figure:: http://photos.100ask.net/lvgl/04_widgets/07_canvas/01_lv_ex_canvas_1.png
	   
	  在画布上绘图并旋转


上述效果的示例代码：

.. code-block:: c
    :linenos:


	#include "../../../lv_examples.h"
	#if LV_USE_CANVAS


	#define CANVAS_WIDTH  200
	#define CANVAS_HEIGHT  150

	void lv_ex_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_HOR;
		rect_dsc.bg_color = LV_COLOR_RED;
		rect_dsc.bg_grad_color = LV_COLOR_BLUE;
		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_ofs_x = 5;
		rect_dsc.shadow_ofs_y = 5;

		lv_draw_label_dsc_t label_dsc;
		lv_draw_label_dsc_init(&label_dsc);
		label_dsc.color = LV_COLOR_YELLOW;

		static lv_color_t cbuf[LV_CANVAS_BUF_SIZE_TRUE_COLOR(CANVAS_WIDTH, CANVAS_HEIGHT)];

		lv_obj_t * canvas = lv_canvas_create(lv_scr_act(), NULL);
		lv_canvas_set_buffer(canvas, cbuf, CANVAS_WIDTH, CANVAS_HEIGHT, LV_IMG_CF_TRUE_COLOR);
		lv_obj_align(canvas, NULL, LV_ALIGN_CENTER, 0, 0);
		lv_canvas_fill_bg(canvas, LV_COLOR_SILVER, LV_OPA_COVER);

		lv_canvas_draw_rect(canvas, 70, 60, 100, 70, &rect_dsc);

		lv_canvas_draw_text(canvas, 40, 20, 100, &label_dsc, "Some text on text canvas", LV_LABEL_ALIGN_LEFT);

		/* Test the rotation. It requires an other buffer where the orignal image is stored.
		 * So copy the current image to buffer and rotate it to the canvas */
		static lv_color_t cbuf_tmp[CANVAS_WIDTH * CANVAS_HEIGHT];
		memcpy(cbuf_tmp, cbuf, sizeof(cbuf_tmp));
		lv_img_dsc_t img;
		img.data = (void *)cbuf_tmp;
		img.header.cf = LV_IMG_CF_TRUE_COLOR;
		img.header.w = CANVAS_WIDTH;
		img.header.h = CANVAS_HEIGHT;

		lv_canvas_fill_bg(canvas, LV_COLOR_SILVER, LV_OPA_COVER);
		lv_canvas_transform(canvas, &img, 30, LV_IMG_ZOOM_NONE, 0, 0, CANVAS_WIDTH / 2, CANVAS_HEIGHT / 2, true);
	}

	#endif




色度键控的透明画布
**********************************

.. figure:: http://photos.100ask.net/lvgl/04_widgets/07_canvas/02_lv_ex_canvas_2.png
	   
	  色度键控的透明画布


上述效果的示例代码：

.. code-block:: c
    :linenos:


	#include "../../../lv_examples.h"
	#if LV_USE_CANVAS

	#define CANVAS_WIDTH  50
	#define CANVAS_HEIGHT  50

	/**
	 * Create a transparent canvas with Chroma keying and indexed color format (palette).
	 */
	void lv_ex_canvas_2(void)
	{
		/*Create a button to better see the transparency*/
		lv_btn_create(lv_scr_act(), NULL);

		/*Create a buffer for the canvas*/
		static lv_color_t cbuf[LV_CANVAS_BUF_SIZE_INDEXED_1BIT(CANVAS_WIDTH, CANVAS_HEIGHT)];

		/*Create a canvas and initialize its the palette*/
		lv_obj_t * canvas = lv_canvas_create(lv_scr_act(), NULL);
		lv_canvas_set_buffer(canvas, cbuf, CANVAS_WIDTH, CANVAS_HEIGHT, LV_IMG_CF_INDEXED_1BIT);
		lv_canvas_set_palette(canvas, 0, LV_COLOR_TRANSP);
		lv_canvas_set_palette(canvas, 1, LV_COLOR_RED);

		/*Create colors with the indices of the palette*/
		lv_color_t c0;
		lv_color_t c1;

		c0.full = 0;
		c1.full = 1;

		/*Transparent background*/
		lv_canvas_fill_bg(canvas, c1, LV_OPA_TRANSP);

		/*Create hole on the canvas*/
		uint32_t x;
		uint32_t y;
		for( y = 10; y < 30; y++) {
			for( x = 5; x < 20; x++) {
				lv_canvas_set_px(canvas, x, y, c0);
			}
		}

	}
	#endif



相关API
##################################
Typedefs 
**********************************
.. code-block:: c
    :linenos:
	
	typedef uint8_t lv_canvas_part_t


enums 
**********************************
.. code-block:: c
    :linenos:
	
	enum [anonymous]
	值：
	enumerator LV_CANVAS_PART_MAIN


函数
**********************************
.. code-block:: c
    :linenos:
	
	lv_obj_t * lv_canvas_create(lv_obj_t * par，constlv_obj_t *copy)
	功能：创建一个画布对象
	返回：
	指向创建的画布的指针
	形参：
	par：指向对象的指针，它将是新画布的父对象
	copy：指向画布对象的指针，如果不为NULL，则将从其复制新对象


	void lv_canvas_set_buffer(lv_obj_t * canvas，void * buf，lv_coord_t w，lv_coord_t h，lv_img_cf_t cf )
	功能：为画布设置缓冲区。
	形参：
	buf：画布内容所在的缓冲区。所需的大小为(lv_img_color_format_get_px_size(cf)* w)/ 8 * h)
	可以使用它分配lv_mem_alloc()或可以是静态分配的数组(例如，静态lv_color_t buf [100 * 50])，
	也可以是RAM中的地址或外部地址SRAM
	canvas：指向画布对象的指针
	w：画布的宽度
	h：画布的高度
	cf：颜色格式。LV_IMG_CF_...


	void lv_canvas_set_px(lv_obj_t * canvas，lv_coord_t x，lv_coord_t y，lv_color_t c )
	功能：设置画布上像素的颜色
	形参：
	canvas：
	x：要设置点的x坐标
	y：要设置点的x坐标
	c：点的颜色


	void lv_canvas_set_palette(lv_obj_t * canvas，uint8_t id，lv_color_t c )
	功能：使用索引格式设置画布的调色板颜色。仅对LV_IMG_CF_INDEXED1/2/4/8
	形参：
	canvas：指向画布对象的指针
	id：要设置的调色板颜色：
	为LV_IMG_CF_INDEXED1：0..1
	为LV_IMG_CF_INDEXED2：0..3
	为LV_IMG_CF_INDEXED4：0..15
	为LV_IMG_CF_INDEXED8：0..255
	c：要设置的颜色


	lv_color_t lv_canvas_get_px(lv_obj_t * canvas，lv_coord_t x，lv_coord_t y )
	功能：获取画布上像素的颜色
	返回：
	点的颜色
	形参：
	canvas：
	x：要设置点的x坐标
	y：要设置点的x坐标


	lv_img_dsc_t * lv_canvas_get_img(lv_obj_t * canvas )
	功能：获取画布的图像作为指向lv_img_dsc_t变量的指针。
	返回：
	指向图像描述符的指针。
	形参：
	canvas：指向画布对象的指针


	void lv_canvas_copy_buf(lv_obj_t *canvas，constvoid * to_copy，lv_coord_t x，lv_coord_t y，lv_coord_t w，lv_coord_t h )
	功能：将缓冲区复制到画布
	形参：
	canvas：指向画布对象的指针
	to_copy：要复制的缓冲区。颜色格式必须与画布的缓冲区颜色格式匹配
	x：目标位置的左侧
	y：目标位置的顶部
	w：要复制的缓冲区的宽度
	h：要复制的缓冲区的高度


	void lv_canvas_transform(lv_obj_t * canvas，lv_img_dsc_t * img，int16_t angle，uint16_t zoom，lv_coord_t offset_x，lv_coord_t offset_y，int32_tivot_x，int32_tivot_y，bool antialias )
	功能：转换并成像并将结果存储在画布上。
	形参：
	canvas：指向画布对象的指针，以存储转换结果。
	img：指向要转换的图像描述符的指针。也可以是其他画布的图像描述符(lv_canvas_get_img())。
	angle：旋转角度(0..3600)，0.1度分辨率
	zoom：变焦倍数(256无变焦)；
	offset_x：偏移X以告知将结果数据放在目标画布上的位置
	offset_y：偏移X以告知将结果数据放在目标画布上的位置
	pivot_x：旋转X轴。相对于源画布设置为围绕中心旋转source width / 2
	pivot_y：旋转的枢轴Y。相对于源画布设置为围绕中心旋转source height / 2
	antialias：在转换过程中应用抗锯齿。看起来更好，但速度较慢。


	void lv_canvas_blur_hor(lv_obj_t *canvas，constlv_area_t * area，uint16_t r )
	功能：在画布上应用水平模糊
	形参：
	canvas：指向画布对象的指针
	area：要模糊的区域。如果NULL整个画布会模糊。
	r：模糊半径


	void lv_canvas_blur_ver(lv_obj_t *canvas，constlv_area_t * area，uint16_t r )
	功能：在画布上应用垂直模糊
	形参：
	canvas：指向画布对象的指针
	area：要模糊的区域。如果NULL整个画布会模糊。
	r：模糊半径


	void lv_canvas_fill_bg(lv_obj_t *canvas，lv_color_t color，lv_opa_t opa )
	功能：用颜色填充画布
	形参：
	canvas：指向画布的指针
	color：背景色
	opa：所需的不透明度


	void lv_canvas_draw_rect(lv_obj_t * canvas，lv_coord_t x，lv_coord_t y，lv_coord_t w，lv_coord_t h，constlv_draw_rect_dsc_t * rect_dsc )
	功能：在画布上画一个矩形
	形参：
	canvas：指向画布对象的指针
	x：矩形的左坐标
	y：矩形的顶部坐标
	w：矩形的宽度
	h：矩形的高度
	rect_dsc：矩形的描述符


	void lv_canvas_draw_text(lv_obj_t *canvas，lv_coord_t x，lv_coord_t y，lv_coord_t max_w，lv_draw_label_dsc_t * label_draw_dsc，constchar * txt，lv_label_align_t align )
	功能：在画布上绘制文本。
	形参：
	canvas：指向画布对象的指针
	x：文本的左坐标
	y：文本的顶部坐标
	max_w：文字的最大宽度。文本将被包装以适合此大小
	label_draw_dsc：指向有效标签描述符的指针 lv_draw_label_dsc_t
	txt：要显示的文字
	align：对齐文字(LV_LABEL_ALIGN_LEFT/RIGHT/CENTER)


	void lv_canvas_draw_img(lv_obj_t * canvas，lv_coord_t x，lv_coord_t y，constvoid * src，constlv_draw_img_dsc_t * img_draw_dsc )
	功能：在画布上绘制图像
	形参：
	canvas：指向画布对象的指针
	x：图像的左坐标
	y：图像的最高坐标
	src：图像源。可以是lv_img_dsc_t变量的指针或图像的路径。
	img_draw_dsc：指向有效标签描述符的指针 lv_draw_img_dsc_t


	void lv_canvas_draw_line(lv_obj_t *canvas，constlv_point_t points[]，uint32_t point_cnt，constlv_draw_line_dsc_t * line_draw_dsc )
	功能：在画布上画一条线
	形参：
	canvas：指向画布对象的指针
	points：线的点
	point_cnt：点数
	line_draw_dsc：指向初始化lv_draw_line_dsc_t变量的指针


	void lv_canvas_draw_polygon(lv_obj_t *canvas，constlv_point_t点[]，uint32_t point_cnt，constlv_draw_rect_dsc_t * poly_draw_dsc )
	功能：在画布上绘制多边形
	形参：
	canvas：指向画布对象的指针
	points：多边形的点
	point_cnt：点数
	poly_draw_dsc：指向初始化lv_draw_rect_dsc_t变量的指针


	void lv_canvas_draw_arc(lv_obj_t * canvas，lv_coord_t x，lv_coord_t y，lv_coord_t r，int32_t start_angle，int32_t end_angle，constlv_draw_line_dsc_t * arc_draw_dsc )
	功能：在画布上画圆弧
	形参：
	canvas：指向画布对象的指针
	x：弧的origo x
	y：弧线的起源
	r：圆弧半径
	start_angle：起始角度(度)
	end_angle：结束角度(度)
	arc_draw_dsc：指向初始化lv_draw_line_dsc_t变量的指针