From 14a5fabe0036345a21e485fd553e81969c5d3d95 Mon Sep 17 00:00:00 2001
From: Gabor Kiss-Vamosi <kisvegabor@gmail.com>
Date: Tue, 1 Oct 2024 10:21:34 +0200
Subject: [PATCH] docs(display): mention how to manipulate the invalidated area
 (#6836)

---
 docs/porting/display.rst | 25 +++++++++++++++++++++++++
 src/display/lv_display.c | 11 +++++++++++
 src/display/lv_display.h |  7 +++++++
 3 files changed, 43 insertions(+)

diff --git a/docs/porting/display.rst b/docs/porting/display.rst
index cb912afe0..49eea6868 100644
--- a/docs/porting/display.rst
+++ b/docs/porting/display.rst
@@ -239,6 +239,31 @@ In full and direct modes, the buffer size should be large enough for the whole s
 As LVGL can not handle fractional width make sure to round the horizontal resolution to 8-
 (For example 90 to 96)
 
+Constraints on the Redrawn Area
+-------------------------------
+
+Some display controllers have specific requirements for the window area where the rendered image can be sent
+(e.g., `x1` must be even, and `x2` must be odd).
+
+In the case of monochrome displays, `x1` must be `Nx8`, and `x2` must be `Nx8 - 1`.
+(If the display uses `LV_COLOR_FORMAT_I1`, LVGL automatically applies this rounding. See :ref:`monochrome`.)
+
+The size of the invalidated (redrawn) area can be controlled as follows:
+
+.. code:: c
+
+    void rounder_event_cb(lv_event_t * e)
+    {
+        lv_area_t * a = lv_event_get_invalidated_area(e);
+
+        a->x1 = a->x1 & (~0x1); /* Ensure that x1 is even */
+        a->x2 = a->x2 | 0x1;    /* Ensure that x2 is odd */
+    }
+
+    ...
+
+    lv_display_add_event_cb(disp, rounder_event_cb, LV_EVENT_INVALIDATE_AREA, NULL);
+
 
 Tiled Rendering
 ---------------
diff --git a/src/display/lv_display.c b/src/display/lv_display.c
index 0362c59b2..247fa163e 100644
--- a/src/display/lv_display.c
+++ b/src/display/lv_display.c
@@ -821,6 +821,17 @@ lv_result_t lv_display_send_event(lv_display_t * disp, lv_event_code_t code, voi
     return res;
 }
 
+lv_area_t * lv_event_get_invalidated_area(lv_event_t * e)
+{
+    if(e->code == LV_EVENT_INVALIDATE_AREA) {
+        return lv_event_get_param(e);
+    }
+    else {
+        LV_LOG_WARN("Not interpreted with this event code");
+        return NULL;
+    }
+}
+
 void lv_display_set_rotation(lv_display_t * disp, lv_display_rotation_t rotation)
 {
     if(disp == NULL) disp = lv_display_get_default();
diff --git a/src/display/lv_display.h b/src/display/lv_display.h
index b1ba7ea9e..9d4fc060c 100644
--- a/src/display/lv_display.h
+++ b/src/display/lv_display.h
@@ -479,6 +479,13 @@ uint32_t lv_display_remove_event_cb_with_user_data(lv_display_t * disp, lv_event
  */
 lv_result_t lv_display_send_event(lv_display_t * disp, lv_event_code_t code, void * param);
 
+/**
+ * Get the area to be invalidated. Can be used in `LV_EVENT_INVALIDATE_AREA`
+ * @param e     pointer to an event
+ * @return      the area to invalidated (can be modified as required)
+ */
+lv_area_t * lv_event_get_invalidated_area(lv_event_t * e);
+
 /**
  * Set the theme of a display. If there are no user created widgets yet the screens' theme will be updated
  * @param disp      pointer to a display