1 /** 2 * @file lv_canvas.h 3 * 4 */ 5 6 #ifndef LV_CANVAS_H 7 #define LV_CANVAS_H 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 /********************* 14 * INCLUDES 15 *********************/ 16 #include "../../lv_conf_internal.h" 17 18 #if LV_USE_CANVAS != 0 19 20 #include "../image/lv_image.h" 21 #include "../../draw/lv_draw_image.h" 22 23 /********************* 24 * DEFINES 25 *********************/ 26 27 /********************** 28 * TYPEDEFS 29 **********************/ 30 LV_ATTRIBUTE_EXTERN_DATA extern const lv_obj_class_t lv_canvas_class; 31 32 /********************** 33 * GLOBAL PROTOTYPES 34 **********************/ 35 36 /** 37 * Create a canvas object 38 * @param parent pointer to an object, it will be the parent of the new canvas 39 * @return pointer to the created canvas 40 */ 41 lv_obj_t * lv_canvas_create(lv_obj_t * parent); 42 43 /*===================== 44 * Setter functions 45 *====================*/ 46 47 /** 48 * Set a buffer for the canvas. 49 * 50 * Use lv_canvas_set_draw_buf() instead if you need to set a buffer with alignment requirement. 51 * 52 * @param obj pointer to a canvas object 53 * @param buf buffer where content of canvas will be. 54 * The required size is (lv_image_color_format_get_px_size(cf) * w) / 8 * h) 55 * It can be allocated with `lv_malloc()` or 56 * it can be statically allocated array (e.g. static lv_color_t buf[100*50]) or 57 * it can be an address in RAM or external SRAM 58 * @param w width of canvas 59 * @param h height of canvas 60 * @param cf color format. `LV_COLOR_FORMAT...` 61 */ 62 void lv_canvas_set_buffer(lv_obj_t * obj, void * buf, int32_t w, int32_t h, lv_color_format_t cf); 63 64 /** 65 * Set a draw buffer for the canvas. A draw buffer either can be allocated by `lv_draw_buf_create()` 66 * or defined statically by `LV_DRAW_BUF_DEFINE_STATIC`. When buffer start address and stride has alignment 67 * requirement, it's recommended to use `lv_draw_buf_create`. 68 * @param obj pointer to a canvas object 69 * @param draw_buf pointer to a draw buffer 70 */ 71 void lv_canvas_set_draw_buf(lv_obj_t * obj, lv_draw_buf_t * draw_buf); 72 73 /** 74 * Set a pixel's color and opacity 75 * @param obj pointer to a canvas 76 * @param x X coordinate of the pixel 77 * @param y Y coordinate of the pixel 78 * @param color the color 79 * @param opa the opacity 80 * @note The following color formats are supported 81 * LV_COLOR_FORMAT_I1/2/4/8, LV_COLOR_FORMAT_A8, 82 * LV_COLOR_FORMAT_RGB565, LV_COLOR_FORMAT_RGB888, 83 * LV_COLOR_FORMAT_XRGB8888, LV_COLOR_FORMAT_ARGB8888 84 */ 85 void lv_canvas_set_px(lv_obj_t * obj, int32_t x, int32_t y, lv_color_t color, lv_opa_t opa); 86 87 /** 88 * Set the palette color of a canvas for index format. Valid only for `LV_COLOR_FORMAT_I1/2/4/8` 89 * @param obj pointer to canvas object 90 * @param index the palette color to set: 91 * - for `LV_COLOR_FORMAT_I1`: 0..1 92 * - for `LV_COLOR_FORMAT_I2`: 0..3 93 * - for `LV_COLOR_FORMAT_I4`: 0..15 94 * - for `LV_COLOR_FORMAT_I8`: 0..255 95 * @param color the color to set 96 */ 97 void lv_canvas_set_palette(lv_obj_t * obj, uint8_t index, lv_color32_t color); 98 99 /*===================== 100 * Getter functions 101 *====================*/ 102 103 lv_draw_buf_t * lv_canvas_get_draw_buf(lv_obj_t * obj); 104 105 /** 106 * Get a pixel's color and opacity 107 * @param obj pointer to a canvas 108 * @param x X coordinate of the pixel 109 * @param y Y coordinate of the pixel 110 * @return ARGB8888 color of the pixel 111 */ 112 lv_color32_t lv_canvas_get_px(lv_obj_t * obj, int32_t x, int32_t y); 113 114 /** 115 * Get the image of the canvas as a pointer to an `lv_image_dsc_t` variable. 116 * @param canvas pointer to a canvas object 117 * @return pointer to the image descriptor. 118 */ 119 lv_image_dsc_t * lv_canvas_get_image(lv_obj_t * canvas); 120 121 /** 122 * Return the pointer for the buffer. 123 * It's recommended to use this function instead of the buffer form the 124 * return value of lv_canvas_get_image() as is can be aligned 125 * @param canvas pointer to a canvas object 126 * @return pointer to the buffer 127 */ 128 const void * lv_canvas_get_buf(lv_obj_t * canvas); 129 130 /*===================== 131 * Other functions 132 *====================*/ 133 134 /** 135 * Copy a buffer to the canvas 136 * @param obj pointer to a canvas object 137 * @param canvas_area the area of the canvas to copy 138 * @param dest_buf pointer to a buffer to store the copied data 139 * @param dest_area the area of the destination buffer to copy to. If omitted NULL, copy to the whole `dest_buf` 140 */ 141 void lv_canvas_copy_buf(lv_obj_t * obj, const lv_area_t * canvas_area, lv_draw_buf_t * dest_buf, 142 const lv_area_t * dest_area); 143 144 /** 145 * Fill the canvas with color 146 * @param obj pointer to a canvas 147 * @param color the background color 148 * @param opa the desired opacity 149 */ 150 void lv_canvas_fill_bg(lv_obj_t * obj, lv_color_t color, lv_opa_t opa); 151 152 /** 153 * Initialize a layer to use LVGL's generic draw functions (lv_draw_rect/label/...) on the canvas. 154 * Needs to be usd in pair with `lv_canvas_finish_layer`. 155 * @param canvas pointer to a canvas 156 * @param layer pointer to a layer variable to initialize 157 */ 158 void lv_canvas_init_layer(lv_obj_t * canvas, lv_layer_t * layer); 159 160 /** 161 * Wait until all the drawings are finished on layer. 162 * Needs to be usd in pair with `lv_canvas_init_layer`. 163 * @param canvas pointer to a canvas 164 * @param layer pointer to a layer to finalize 165 */ 166 void lv_canvas_finish_layer(lv_obj_t * canvas, lv_layer_t * layer); 167 168 /********************** 169 * MACROS 170 **********************/ 171 172 #define LV_CANVAS_BUF_SIZE(w, h, bpp, stride) (((((w * bpp + 7) >> 3) + stride - 1) & ~(stride - 1)) * h + LV_DRAW_BUF_ALIGN) 173 174 /** 175 * Just a wrapper to `LV_CANVAS_BUF_SIZE` for bindings. 176 */ 177 uint32_t lv_canvas_buf_size(int32_t w, int32_t h, uint8_t bpp, uint8_t stride); 178 179 #endif /*LV_USE_CANVAS*/ 180 181 #ifdef __cplusplus 182 } /*extern "C"*/ 183 #endif 184 185 #endif /*LV_CANVAS_H*/ 186
