feat(canvas): add api to skip canvas invalidation when setting pixel (#9592)

Author: AndreCostaaa

docs/src/widgets/canvas.rst

@@ -71,6 +71,15 @@ To set an individual pixel's color on the Canvas, use
 (``LV_COLOR_FORMAT_I1/2/4/8``) pass the color index as the ``color`` argument by using
 the *blue* channel in the ``color`` value, e.g. :cpp:expr:`lv_color_make(0, 0, index)`.
 
+.. tip::
+
+    When updating multiple pixels in a loop, follow these steps to improve performance:
+
+    1. Use :cpp:func:`lv_canvas_set_px_skip_invalidate` to set pixel colors without triggering a redraw.
+    2. Call :cpp:func:`lv_obj_invalidate` once after the loop is finished.
+
+    This prevents the canvas from being redundantly invalidated for every single pixel update.
+
 :cpp:expr:`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. :cpp:enumerator:`LV_COLOR_FORMAT_A8`) the color will be

src/widgets/canvas/lv_canvas.c

@@ -108,7 +108,7 @@ void lv_canvas_set_draw_buf(lv_obj_t * obj, lv_draw_buf_t * draw_buf)
     lv_image_cache_drop(draw_buf);
 }
 
-void lv_canvas_set_px(lv_obj_t * obj, int32_t x, int32_t y, lv_color_t color, lv_opa_t opa)
+void lv_canvas_set_px_skip_invalidate(lv_obj_t * obj, int32_t x, int32_t y, lv_color_t color, lv_opa_t opa)
 {
     LV_ASSERT_OBJ(obj, MY_CLASS);
 
@@ -182,6 +182,11 @@ void lv_canvas_set_px(lv_obj_t * obj, int32_t x, int32_t y, lv_color_t color, lv
         buf->lumi = lv_color_luminance(color);
         buf->alpha = 255;
     }
+}
+
+void lv_canvas_set_px(lv_obj_t * obj, int32_t x, int32_t y, lv_color_t color, lv_opa_t opa)
+{
+    lv_canvas_set_px_skip_invalidate(obj, x, y, color, opa);
     lv_obj_invalidate(obj);
 }
 

src/widgets/canvas/lv_canvas.h

@@ -84,6 +84,22 @@ void lv_canvas_set_draw_buf(lv_obj_t * obj, lv_draw_buf_t * draw_buf);
  */
 void lv_canvas_set_px(lv_obj_t * obj, int32_t x, int32_t y, lv_color_t color, lv_opa_t opa);
 
+/**
+ * Set a pixel's color and opacity without invalidating the canvas object
+ * In order for the canvas to be redrawn, the user is required to manually call `lv_obj_invalidate`
+ *
+ * @param obj   pointer to a canvas
+ * @param x     X coordinate of the pixel
+ * @param y     Y coordinate of the pixel
+ * @param color the color
+ * @param opa   the opacity
+ * @note        The following color formats are supported
+ *              LV_COLOR_FORMAT_I1/2/4/8, LV_COLOR_FORMAT_A8,
+ *              LV_COLOR_FORMAT_RGB565, LV_COLOR_FORMAT_RGB888,
+ *              LV_COLOR_FORMAT_XRGB8888, LV_COLOR_FORMAT_ARGB8888
+ */
+void lv_canvas_set_px_skip_invalidate(lv_obj_t * obj, int32_t x, int32_t y, lv_color_t color, lv_opa_t opa);
+
 /**
  * Set the palette color of a canvas for index format. Valid only for `LV_COLOR_FORMAT_I1/2/4/8`
  * @param obj       pointer to canvas object

tests/src/test_cases/widgets/test_canvas.c

@@ -68,6 +68,10 @@ void test_canvas_functions_invalidate(void)
     lv_refr_now(NULL);
     TEST_ASSERT(draw_counter == 2);
 
+    lv_canvas_set_px_skip_invalidate(canvas, 0, 0, lv_color_black(), LV_OPA_COVER);
+    lv_refr_now(NULL);
+    TEST_ASSERT(draw_counter == 2);
+
     lv_canvas_fill_bg(canvas, lv_color_black(), LV_OPA_COVER);
     lv_refr_now(NULL);
     TEST_ASSERT(draw_counter == 3);