docs update drawing and porting (display, indev)

3 files changed, 218 insertions, 198 deletions

diff --git a/docs/overview/drawing.md b/docs/overview/drawing.md
index 08ee9ce7f..0fa8e7f1a 100644
--- a/docs/overview/drawing.md
+++ b/docs/overview/drawing.md
@@ -4,106 +4,90 @@
 ```
 # Drawing
 
-With LVGL, you don't need to draw anything manually. Just create objects (like buttons, labels, arc, etc), move and change them and LVGL will refresh and redraw what is required.
+With LVGL, you don't need to draw anything manually. Just create objects (like buttons, labels, arc, etc), move and change them, and LVGL will refresh and redraw what is required.
 
-However, it might be useful to have a basic understanding of how drawing happens in LVGL.
+However, it might be useful to have a basic understanding of how drawing happens in LVGL to add customization, make it easier to find bugs or just out of curiosity.
+
+The basic concept is to not draw directly to the screen, but draw to an internal draw buffer first. When drawing (rendering) is ready copy that buffer to the screen. 
+
+The draw buffer can be smaller than the screen's size. LVGL will simply render in "tiles" that fit into the given draw buffer.
 
-The basic concept is to not draw directly to the screen, but draw to an internal draw buffer first and then copy that buffer to screen when the rendering is ready. 
-The draw buffer can be smaller than the screen's size. LVGL will simple draw "tiles" that fit into the given draw buffer.
 This approach has two main advantages compared to directly drawing to the screen:
-1. Avoids flickering while layers of the UI are drawn. For example, when drawing a *background + button + text*, each "stage" would be visible for a short time if LVGL drawn directly into the display.
-2. It's faster to modify a buffer in internal RAM and finally write one pixel once than reading/writing the display directly on each pixel access. 
+1. It avoids flickering while the layers of the UI are drawn. For example, if LVGL drawn directly into the display, when drawing a *background + button + text*, each "stage" would be visible for a short time .
+2. It's faster to modify a buffer in internal RAM and finally write one pixel only once than reading/writing the display directly on each pixel access. 
 (e.g. via a display controller with SPI interface). 
 
 Note that, this concept is different from "traditional" double buffering where there are 2 screen sized frame buffers: 
-one holds the current image to display, rendering happens to the other (inactive) frame buffer, and they are swapped when the rendering is finished. 
+one holds the current image to show on the display, and rendering happens to the other (inactive) frame buffer, and they are swapped when the rendering is finished. 
 The main difference is that with LVGL you don't have to store 2 frame buffers (which usually requires external RAM) but only smaller draw buffer(s) that can easily fit into the internal RAM too.
 
-## Buffering modes
-
-As you already might learn in the [Porting](/porting/display) section, there are 2 types of buffering:
-1. **One buffer**  LVGL draws the content of the screen into a draw buffer and sends it to the display. 
-The buffer can be smaller than the screen. In this case, the larger areas will be redrawn in multiple parts. 
-If only small areas changes (e.g. a button is  pressed), then only those areas will be refreshed.
-2. **Two buffers**  Having two buffers, LVGL can draw into one buffer while the content of the other buffer is sent to display in the background.
-DMA or other hardware should be used to transfer the data to the display to let the CPU draw meanwhile.
-This way, the rendering and refreshing of the display become parallel. If the buffer is smaller than the area to refresh, LVGL will draw the display's content in chunks similar to the *One buffer*.
-
-In the display driver (`lv_disp_drv_t`) the `full_refresh` bit can be enabled to force LVGL always redraw the whole screen. It works with both *One buffer* and *Two buffer* modes.
-With `full_refresh` enabled and providing 2 screen sized draw buffers LVGL work as in "traditional" double buffering.
 
 ## Mechanism of screen refreshing
 
-1. Something happens on the GUI which requires redrawing. For example, a button has been pressed, a chart has been changed or an animation happened, etc.
+Be sure to get familiar with the [Buffering modes of LVGL](/porting/display) first.
+
+LVGL refreshes the screen in the following steps:
+1. Something happens on the UI which requires redrawing. For example, a button is pressed, a chart is changed or an animation happened, etc.
 2. LVGL saves the changed object's old and new area into a buffer, called an *Invalid area buffer*. For optimization, in some cases, objects are not added to the buffer:
     - Hidden objects are not added.
     - Objects completely out of their parent are not added.
-    - Areas out of the parent are cropped to the parent's area.
-    - The object on other screens are not added.
-3. In every `LV_DISP_DEF_REFR_PERIOD` (set in *lv_conf.h*):
+    - Areas partially out of the parent are cropped to the parent's area.
+    - The objects on other screens are not added.
+3. In every `LV_DISP_DEF_REFR_PERIOD` (set in `lv_conf.h`) the followings happen:
     - LVGL checks the invalid areas and joins the adjacent or intersecting areas.
-    - Takes the first joined area, if it's smaller than the *draw buffer*, then simply draw the areas' content to the *draw buffer*. 
+    - Takes the first joined area, if it's smaller than the *draw buffer*, then simply render the area's content into the *draw buffer*. 
       If the area doesn't fit into the buffer, draw as many lines as possible to the *draw buffer*.
     - When the area is rendered, call `flush_cb` from the display driver to refresh the display.
     - If the area was larger than the buffer, render the remaining parts too.
     - Do the same with all the joined areas.
 
-While an area is redrawn, the library searches the top most object which covers the area to redraw, and starts to draw from that object.
-For example, if a button's label has changed, the library will see that it's enough to draw the button under the text, and it's not required to draw the screen too.
+When an area is redrawn, the library searches the top most object which covers that area, and starts drawing from that object.
+For example, if a button's label has changed, the library will see that it's enough to draw the button under the text, and it's not required to draw the screen under the button too.
 
-The difference between buffer types regarding the drawing mechanism is the following:
-1. **One buffer** - LVGL needs to wait for `lv_disp_flush_ready()` (called at the end of `flush_cb`) before starting to redraw the next part.
+The difference between buffering modes regarding the drawing mechanism is the following:
+1. **One buffer** - LVGL needs to wait for `lv_disp_flush_ready()` (called from `flush_cb`) before starting to redraw the next part.
 2. **Two buffers** -  LVGL can immediately draw to the second buffer when the first is sent to `flush_cb` because the flushing should be done by DMA (or similar hardware) in the background.
 3. **Double buffering** -  `flush_cb` should only swap the address of the frame buffer.
 
 ## Masking
-*Masking* is the basic concept of LVGL's drawing engine. 
-To use LVGL it's not required to know about the mechanisms described here, 
-but you might find interesting to know how the drawing works under hood. 
-
-To learn masking let's learn the steps of drawing first:
-1. Create a draw descriptor from an object's styles (e.g. `lv_draw_rect_dsc_t`). 
-It tells the parameters of drawing, for example the colors, widths, opacity, fonts, radius, etc. 
-2. Call the draw function with the initialized descriptor and some other parameters. (E.g. `lv_draw_rect()`) 
-It renders the primitive shape to the current draw buffer. 
-3. If the shape is very simple and doesn't require masks go to #5. 
-Else create the required masks (e.g. a rounded rectangle mask)
-4. Apply all the created mask(s) for one or a few lines. 
-It create 0..255 values into a *mask buffer* with the "shape" of the created masks. 
-E.g. in case of a "line mask" according to the parameters of the mask, 
-keep one side of the buffer as it is (255 by default) and set the rest to 0 to indicate that the latter side should be removed.
-5. Blend the image or rectangle to the screen. 
-During blending masks (make some pixels transparent or opaque), blending modes (additive, subtractive, etc), opacity are handled.
-6. Repeat from  #4. 
+*Masking* is the basic concept of LVGL's draw engine. 
+To use LVGL it's not required to know about the mechanisms described here,  you might find interesting to know how drawing works under hood. 
+Knowing about mask comes in handy if you want to customize drawing.
+
+To learn masking let's learn the steps of drawing first. 
+LVGL performs the following steps to render any shape, image or text. It can be considered as a drawing pipeline.
+
+1. **Prepare the draw descriptors** Create a draw descriptor from an object's styles (e.g. `lv_draw_rect_dsc_t`).  It tells the parameters of drawing, for example the colors, widths, opacity, fonts, radius, etc. 
+2. **Call the draw function** Call the draw function with the draw descriptor and some other parameters (e.g. `lv_draw_rect()`).  It renders the primitive shape to the current draw buffer. 
+3. **Create masks** If the shape is very simple and doesn't require masks go to #5.  Else create the required masks (e.g. a rounded rectangle mask)
+4. **Calculate all the added mask**. It creates 0..255 values into a *mask buffer* with the "shape" of the created masks. 
+E.g. in case of a "line mask" according to the parameters of the mask, keep one side of the buffer as it is (255 by default) and set the rest to 0 to indicate that this side should be removed.
+5. **Blend a color or image** During blending masks (make some pixels transparent or opaque), blending modes (additive, subtractive, etc), opacity are handled.
 
 LVGL has the following built-in mask types which can be calculated and applied real-time:
-- `LV_DRAW_MASK_TYPE_LINE` Removes a side of a line (top, bottom, left or right). `lv_draw_line` uses 4 of it. 
+- `LV_DRAW_MASK_TYPE_LINE` Removes a side from a line (top, bottom, left or right). `lv_draw_line` uses 4 of it. 
 Essentially, every (skew) line is bounded with 4 line masks by forming a rectangle.
-- `LV_DRAW_MASK_TYPE_RADIUS` Removes the inner or outer parts of a rectangle which can have radius too. It's also used to create circles by setting the radius to large value (`LV_RADIUS_CIRCLE`) 
+- `LV_DRAW_MASK_TYPE_RADIUS` Removes the inner or outer parts of a rectangle which can have radius. It's also used to create circles by setting the radius to large value (`LV_RADIUS_CIRCLE`) 
 - `LV_DRAW_MASK_TYPE_ANGLE` Removes a circle sector. It is used by `lv_draw_arc` to remove the "empty" sector. 
 - `LV_DRAW_MASK_TYPE_FADE` Create a vertical fade (change opacity) 
 - `LV_DRAW_MASK_TYPE_MAP` The mask is stored in an array and the necessary parts are applied 
 
 Masks are used the create almost every basic primitives:
-- **letters** create a mask from the letter and draw a “letter-colored” rectangle using the mask.
-- **line** created from 4 "line masks", to mask out the left, right, top and bottom part of the line to get perfectly perpendicular line ending
-- **rounded rectangle** a mask is created real-time for each line of a rounded rectangle and a normal filled rectangle is drawn according to the mask.
-- **clip corner** to clip to overflowing content on the rounded corners also a rounded rectangle mask is applied.
-- **rectangle border** same as a rounded rectangle, but inner part is masked out too.
-- **arc drawing** a circle border is drawn, but an arc mask is applied too.
-- **ARGB images** the alpha channel is separated into a mask and the image is drawn as a normal RGB image.
-
-As mentioned in #3 above in some cases no mask is required:
-- rectangles without radius
-- non ARGB images
-
-## Hooking drawing
-Although widget can be very well customized by styles ther might be cases when something really custom is required. 
-To ensure a great level of flexibility LVGL sends a lot events during drawing with parameters that tells what LVGL is planning to draw. 
-Some fields of these parameters can be modified to draw something else or any custom drawing added manually.
-
-A good use case for it is the [Button amtrix](/widgets/core/btnmatric) widget. Its buttons can be styled in different states but you can't style the buttons one by one. 
-However, an event is sent for ever button and you can tell LVGL for example to use different colors on a specific button or manually draw an image on an other button.
+- **letters** Create a mask from the letter and draw a rectangle with the letter's color considering the mask.
+- **line** Created from 4 "line masks", to mask out the left, right, top and bottom part of the line to get perfectly perpendicular line ending.
+- **rounded rectangle** A mask is created real-time to add radius to the corners.
+- **clip corner** To clip to overflowing content (usually children) on the rounded corners also a rounded rectangle mask is applied.
+- **rectangle border** Same as a rounded rectangle, but inner part is masked out too.
+- **arc drawing** A circle border is drawn, but an arc mask is applied too.
+- **ARGB images** The alpha channel is separated into a mask and the image is drawn as a normal RGB image.
+
+## Hook drawing
+Although widgets can be very well customized by styles there might be cases when something really custom is required. 
+To ensure a great level of flexibility LVGL sends a lot events during drawing with parameters that tells what LVGL is about to draw. 
+Some fields of these parameters can be modified to draw something else or any custom drawing can be added manually.
+
+A good use case for it is the [Button matrix](/widgets/core/btnmatrix) widget. By default its buttons can be styled in different states but you can't style the buttons one by one. 
+However, an event is sent for ever button and you can tell LVGL for example to use different colors on a specific buttons or manually draw an image on an some buttons.
 
 Below each related events are described in detail.
 
@@ -111,16 +95,16 @@ Below each related events are described in detail.
 
 These events are related to the actual drawing of the object. E.g. drawing of buttons, texts, etc happens here.
 
-`lv_event_get_clip_area(event)` can be used to get the current clip area.
+`lv_event_get_clip_area(event)` can be used to get the current clip area. The clip area is required in draw functions to make them draw only on limited area. 
 
 #### LV_EVENT_DRAW_MAIN_BEGIN
 
-Sent before starting to draw the object. It's a good place to add masks manually. E.g. add a line mask the "hides" the right side of an object.
+Sent before starting to draw an object. It's a good place to add masks manually. E.g. add a line mask that "removes" the right side of an object.
 
 #### LV_EVENT_DRAW_MAIN
 
-The actual drawing of the object. E.g. a rectangle for a button is drawn here. First the widget's events are called to perform drawing and you can draw anything on top of them.
-For example you can add a custom text or image.
+The actual drawing of the object happens in this event. E.g. a rectangle for a button is drawn here. First, the widgets' internal events are called to perform drawing and after that you can draw anything on top of them.
+For example you can add a custom text or an image.
 
 #### LV_EVENT_DRAW_MAIN_END
 
@@ -128,13 +112,13 @@ Called when the main drawing is finished. You can draw anything here as well and
 
 ### Post drawing
 
-Post drawing events are called when all the children of an object are drawn. For example LVGL use the post drawing "phase" to draw the scrollbars because they should be above all the children. 
+Post drawing events are called when all the children of an object are drawn. For example LVGL use the post drawing phase to draw the scrollbars because they should be above all the children. 
 
 `lv_event_get_clip_area(event)` can be used to get the current clip area.
 
 #### LV_EVENT_DRAW_POST_BEGIN
 
-Sent before starting to starting the post draw phase. Masks can be added here too to mask out the post drawn content.
+Sent before starting the post draw phase. Masks can be added here too to mask out the post drawn content.
 
 #### LV_EVENT_DRAW_POST
 
@@ -142,17 +126,17 @@ The actual drawing should happens here.
 
 #### LV_EVENT_DRAW_POST_END
 
-Called when post drawing has finished. If the mask were not removed in `LV_EVENT_DRAW_MAIN_END` they should be removed here.
-
+Called when post drawing has finished. If the masks were not removed in `LV_EVENT_DRAW_MAIN_END` they should be removed here.
 
 ### Part drawing
 
 When LVGL draws a part of an object (e.g. a slider's indicator, a table's cell or a button matrix's button) it sends events before and after drawing that part with some context of the drawing.
-It allows changind the parts on a very low level with masks, extra drawing, or changing the parameters the LVGL is planning to use for drawing.
+It allows changing the parts on a very low level with masks, extra drawing, or changing the parameters the LVGL is planning to use for drawing.
 
-In these events an `lv_obj_draw_part_t` structure is used to describe the context of the drawing. Not all fields are set. To see which fields are set for a widget see the widgets documentation.
+In these events an `lv_obj_draw_part_t` structure is used to describe the context of the drawing. Not all fields are set for every part and widget. 
+To see which fields are set for a widget see the widget's documentation.
 
-It has the following fields:
+`lv_obj_draw_part_t` has the following fields:
 
 ```c
 // Always set
@@ -181,41 +165,57 @@ const void * sub_part_ptr;          // A pointer the identifies something in the
 
 #### LV_EVENT_DRAW_PART_BEGIN
 
-Start drawing a part. It's good place to modify the draw descriptors (e.g. `rect_dsc`), or add masks.
+Start the drawing of a part. It's good place to modify the draw descriptors (e.g. `rect_dsc`), or add masks.
  
 #### LV_EVENT_DRAW_PART_END
  
-Finish to drawing a part. It's a good place to draw extra content on the part, or remove the masks added in `LV_EVENT_DRAW_PART_BEGIN`.
+Finish the drawing of a part. It's a good place to draw extra content on the part, or remove the masks added in `LV_EVENT_DRAW_PART_BEGIN`.
 
 ### Others
 
 #### LV_EVENT_COVER_CHECK   
 
-Check if the object fully covers an area. `lv_event_get_cover_check_info(event)` returns an pointer to an `lv_cover_check_info_t` variable. Its `res` field should be set to the following values considering the `area` field: 
-- `LV_DRAW_RES_COVER` the areas is fully covered
-- `LV_DRAW_RES_NOT_COVER` the areas is not covered
-- `LV_DRAW_RES_MASKED` the areas is masked out
+This event is used to check whether an object fully covers an area or not. 
+
+`lv_event_get_cover_check_info(event)` returns an pointer to an `lv_cover_check_info_t` variable. Its `res` field should be set to the following values considering the `area` field: 
+- `LV_DRAW_RES_COVER` the areas is fully covered by the object
+- `LV_DRAW_RES_NOT_COVER` the areas is not covered by the object
+- `LV_DRAW_RES_MASKED` there is a mask on the object so it can not covert the area
+
+Here are some cases why can't an object fully cover an area:
+- It's simply not fully on the that area
+- It has radius
+- It has not 100% background opacity
+- It's an ARGB or chroma keyed image
+- It's a text 
+- It has not normal blending mode. In this case LVGL needs to know the colors under the object to make the blending properly
+
+In short if for any reason the the area below the object is visible than it doesn't cover that area.
 
-Some guideline how to set the result:
-- If already set to `LV_DRAW_RES_MASKED` do nothing. In this case an other event already set it and it's the "strongest" state that shouldn't be overwritten.
+Some guideline how to set the `res` field in `lv_cover_check_info_t`:
+- Before sending this event LVGL checks if at least the widget's coordinates fully cover the area or not. If not the event is not called.
+- You need to check only the drawing you have added. The existing properties known by widget are handled in the widget's internal events. 
+E.g. if a widget has > 0 radius it might not cover an area but you need to handle `radius` only if you will modify it and widget can't know about it. 
+- If `res` is already set to `LV_DRAW_RES_MASKED` do nothing. In this case an other event already set it and it's the "strongest" state that shouldn't be overwritten.
 - If you added a draw mask on the object set `res` to `LV_DRAW_RES_MASKED`
-- If there is no draw mask but the object simply not covers the area set `LV_DRAW_RES_NOT_COVER`
+- If there is no draw masks but the object simply not covers the area for any reason set `LV_DRAW_RES_NOT_COVER`
 - If the area is fully covered by the object leave `res` unchanged.
 
-In the practice probably you need to set `LV_DRAW_RES_MASKED` only if you added masks in a MAIN or POST draw events because "normal" cover checks are handles by the widgets.
+In the practice probably you need to set only `LV_DRAW_RES_MASKED`if you added masks in a MAIN or POST draw events because "normal" cover checks are handles by the widgets.
 
-However, if you really added masks in MAIN or POST draw events you need to `LV_EVENT_COVER_CHECK` event and tell LVGL there are masks on this object.
+However, if you really added masks in MAIN or POST draw events you need to handle `LV_EVENT_COVER_CHECK` event and tell LVGL there are masks on this object.
 
 If masks are added and removed in  `LV_EVENT_DRAW_PART_BEGIN/END`, `LV_EVENT_COVER_CHECK` doesn't need to know about it except the masks affects `LV_PART_MAIN`. 
-It's because if LVGL checks the main part to decide whether an object covers an area or not. So it doesn't matter e.g. if a tabel's cell is masked because the tables background already covered the area or not.
+It's because LVGL checks the main part to decide whether an object covers an area or not. 
+So it doesn't matter e.g. if a tabel's cell is masked because the tables background already covered the area or not.
 
 #### LV_EVENT_REFR_EXT_DRAW_SIZE
 
-If you need to draw outside of a widget LVGL needs to know about it to provide this extra space. 
-It good use case for it if you creat an event the writes the current value of a  slider above the knob. In this case LVGL need to know that the slider's draw area is larger with size required for the text.
+If you need to draw outside of a widget LVGL needs to know about it to provide the extra space for drawing. 
+Let's say you create an event the writes the current value of a slider above its knob. In this case LVGL needs to know that the slider's draw area should be larger with the size required for the text.
 
-`lv_event_get_ext_draw_size_info(event)` return a pointer to an `lv_coord_t` variable in which the extra draw size should be set. 
-Note that, other events also might set values in this variable you should only values larger than the current value. For example:
+`lv_event_get_ext_draw_size_info(event)` return a pointer to an `lv_coord_t` variable in which the extra draw size can be set. 
+Note that, other events also might set the value of this variable so you should set only values larger than the current value. For example:
 ```c
 lv_coord_t * s = lv_event_get_ext_draw_size_info(event);
 *s = LV_MAX(*s, 50);
diff --git a/docs/porting/display.md b/docs/porting/display.md
index 87d9d62ab..c75d2cf6a 100644
--- a/docs/porting/display.md
+++ b/docs/porting/display.md
@@ -4,86 +4,104 @@
 ```
 # Display interface
 
-To set up a display an `lv_disp_buf_t` and an `lv_disp_drv_t` variables have to be initialized.
-- **lv_disp_buf_t** contains internal graphic buffer(s).
-- **lv_disp_drv_t** contains callback functions to interact with the display and manipulate drawing related things.
+To set up a display an `lv_disp_draw_buf_t` and an `lv_disp_drv_t` variables have to be initialized.
+- `lv_disp_draw_buf_t` contains internal graphic buffer(s), called draw buffer(s).
+- `lv_disp_drv_t` contains callback functions to interact with the display and manipulate drawing related things.
 
+## Draw buffer
 
-## Display buffer
+Draw buffer(s) are simple array(s) that LVGL uses to render the content of the screen. 
+Once rendering is ready the content of the draw buffer is send to display using the `flush_cb` set in the display driver (see below).
 
-`lv_disp_buf_t` can be initialized like this:
+A draw draw buffer can be initialized via a `lv_disp_draw_buf_t` variable like this:
 ```c
     /*A static or global variable to store the buffers*/
-    static lv_disp_buf_t disp_buf;
+    static lv_disp_draw_buf_t disp_buf;
 
     /*Static or global buffer(s). The second buffer is optional*/
     static lv_color_t buf_1[MY_DISP_HOR_RES * 10];
     static lv_color_t buf_2[MY_DISP_HOR_RES * 10];
 
     /*Initialize `disp_buf` with the buffer(s) */
-    lv_disp_buf_init(&disp_buf, buf_1, buf_2, MY_DISP_HOR_RES*10);
+    lv_disp_draw_buf_init(&disp_buf, buf_1, buf_2, MY_DISP_HOR_RES*10);
 ```
 
-There are 3 possible configurations regarding the buffer size:
-1. **One buffer** LVGL draws the content of the screen into a buffer and sends it to the display.
-The buffer can be smaller than the screen. In this case, the larger areas will be redrawn in multiple parts.
-If only small areas changes (e.g. button press) then only those areas will be refreshed.
-2. **Two non-screen-sized buffers** having two buffers LVGL can draw into one buffer while the content of the other buffer is sent to display in the background.
+Note that `lv_disp_draw_buf_t` needs to be static, global or dynamically allocated and not a local variable destroyed if goes out of the scope. 
+
+
+As you can see the draw buffer can be smaller than the screen. In this case, the larger areas will be redrawn in smaller parts that fit into the draw buffer(s). 
+If only a small area changes (e.g. a button is  pressed) then only that area will be refreshed.
+
+A larger buffer results in better performance but above 1/10 screen sized buffer(s) there is no significant performance improvement. 
+Therefore it's recommended to choose the size of the draw buffer(s) to at least 1/10 screen sized.
+
+If only **one buffer** is used LVGL draws the content of the screen into that draw buffer and sends it to the display.
+
+If **two buffers**  are used LVGL can draw into one buffer while the content of the other buffer is sent to display in the background. 
 DMA or other hardware should be used to transfer the data to the display to let the CPU draw meanwhile.
-This way the rendering and refreshing of the display become parallel.
-Similarly to the *One buffer*, LVGL will draw the display's content in chunks if the buffer is smaller than the area to refresh.
-3. **Two screen-sized buffers**.
-In contrast to *Two non-screen-sized buffers* LVGL will always provide the whole screen's content not only chunks.
-This way the driver can simply change the address of the frame buffer to the buffer received from LVGL.
-Therefore this method works the best when the MCU has an LCD/TFT interface and the frame buffer is just a location in the RAM.
+This way, the rendering and refreshing of the display become parallel. 
 
-You can measure the performance of your display configuration using the [benchmark example](https://github.com/lvgl/lv_examples/tree/master/src/lv_demo_benchmark).
+In the display driver (`lv_disp_drv_t`) the `full_refresh` bit can be enabled to force LVGL always redraw the whole screen. It works in both *one buffer* and *two buffers* modes.
+
+If `full_refresh` is enabled and 2 screen sized draw buffers are provided, LVGL work as "traditional" double buffering. 
+It means in `flush_cb` only the address of the frame buffer needs to be changed to provided pointer (`color_p` parameter).
+This configuration should be used if the MCU has LCD controller periphery and not with an external display controller (e.g. ILI9341 or SSD1963). 
+
+You can measure the performance of different draw buffer configurations using the [benchmark example](https://github.com/lvgl/lv_examples/tree/master/src/lv_demo_benchmark).
 
 ## Display driver
 
-Once the buffer initialization is ready the display drivers need to be initialized. In the most simple case only the following two fields of `lv_disp_drv_t` needs to be set:
-- **buffer** pointer to an initialized `lv_disp_buf_t` variable.
-- **flush_cb** a callback function to copy a buffer's content to a specific area of the display. `lv_disp_flush_ready()` needs to be called when flushing is ready. LVGL might render the screen in multiple chunks and therefore call `flush_cb` multiple times. To see which is the last chunk of rendering use `lv_disp_flush_is_last()`.
+Once the buffer initialization is ready a `lv_disp_drv_t` display drivers need to be
+1. initialized with `lv_disp_drv_init(&disp_drv)`
+2. its fields needs to be set and
+3. registered in LVGL with `lv_disp_drv_register(&disp_drv)`
 
-There are some optional data fields:
-- **hor_res** horizontal resolution of the display. (`LV_HOR_RES_MAX` by default from *lv_conf.h*).
-- **ver_res** vertical resolution of the display. (`LV_VER_RES_MAX` by default from *lv_conf.h*).
-- **color_chroma_key** a color which will be drawn as transparent on chrome keyed images. `LV_COLOR_TRANSP` by default from *lv_conf.h*).
-- **user_data** custom user data for the driver. Its type can be modified in lv_conf.h.
-- **anti-aliasing** use anti-aliasing (edge smoothing). `LV_ANTIALIAS` by default  from *lv_conf.h*.
-- **rotated** and **sw_rotate** See the [rotation](#rotation) section below.
-- **screen_transp** if `1` the screen can have transparent or opaque style. `LV_COLOR_SCREEN_TRANSP` needs to enabled in *lv_conf.h*.
+Note that `lv_disp_drv_t` needs to be static, global or dynamically allocated and not a local variable destroyed if goes out of the scope. 
 
-To use a GPU the following callbacks can be used:
-- **gpu_fill_cb** fill an area in memory with colors.
-- **gpu_blend_cb** blend two memory buffers using opacity.
-- **gpu_wait_cb** if any GPU function return, while the GPU is still working LVGL, will use this function when required the be sure GPU rendering is ready.
+### Mandatory fields
+In the most simple case only the following fields of `lv_disp_drv_t` needs to be set:
+- `draw_buf` pointer to an initialized `lv_disp_draw_buf_t` variable.
+- `flush_cb` a callback function to copy a buffer's content to a specific area of the display. 
+`lv_disp_flush_ready(&disp_drv)` needs to be called when flushing is ready. 
+LVGL might render the screen in multiple chunks and therefore call `flush_cb` multiple times. To see which is the last chunk of rendering use `lv_disp_flush_is_last(&disp_drv)`.
+- `hor_res` horizontal resolution of the display in pixels. 
+- `ver_res` vertical resolution of the display in pixels.
 
-Note that, these functions need to draw to the memory (RAM) and not your display directly.
+### Optional fields 
+There are some optional data fields:
+- `color_chroma_key` A color which will be drawn as transparent on chrome keyed images. Set to `LV_COLOR_CHROMA_KEY` by default from `lv_conf.h`.
+- `user_data` A custom `void `user data for the driver..
+- `anti_aliasing` use anti-aliasing (edge smoothing). Enabled by default if `LV_COLOR_DEPTH` is set to at least 16 in `lv_conf.h`.
+- `rotated` and `sw_rotate` See the [rotation](#rotation) section below.
+- `screen_transp` if `1` the screen itself can have transparency as well. `LV_COLOR_SCREEN_TRANSP` needs to enabled in `lv_conf.h` and requires `LV_COLOR_DEPTH 32`.
 
 Some other optional callbacks to make easier and more optimal to work with monochrome, grayscale or other non-standard RGB displays:
-- **rounder_cb** round the coordinates of areas to redraw. E.g. a 2x2 px can be converted to 2x8.
+- `rounder_cb` Round the coordinates of areas to redraw. E.g. a 2x2 px can be converted to 2x8.
 It can be used if the display controller can refresh only areas with specific height or width (usually 8 px height with monochrome displays).
-- **set_px_cb** a custom function to write the *display buffer*.
-It can be used to store the pixels more compactly if the display has a special color format. (e.g. 1-bit monochrome, 2-bit grayscale etc.)
-This way the buffers used in `lv_disp_buf_t` can be smaller to hold only the required number of bits for the given area size. `set_px_cb` is not working with `Two screen-sized buffers` display buffer configuration.
-- **monitor_cb** a callback function tells how many pixels were refreshed in how much time.
-- **clean_dcache_cb** a callback for cleaning any caches related to the display
+- `set_px_cb` a custom function to write the draw buffer. It can be used to store the pixels more compactly i nthe draw buffer if the display has a special color format. (e.g. 1-bit monochrome, 2-bit grayscale etc.)
+This way the buffers used in `lv_disp_draw_buf_t` can be smaller to hold only the required number of bits for the given area size. Rendering with `set_px_cb` is slower than normal rendering.
+- `monitor_cb` A callback function that tells how many pixels were refreshed in how much time.
+- `clean_dcache_cb` A callback for cleaning any caches related to the display.
 
-To set the fields of *lv_disp_drv_t* variable it needs to be initialized with `lv_disp_drv_init(&disp_drv)`.
-And finally to register a display for LVGL `lv_disp_drv_register(&disp_drv)` needs to be called.
+To use a GPU the following callbacks can be used:
+- `gpu_fill_cb` fill an area in the memory with a color.
+- `gpu_wait_cb` if any GPU function return, while the GPU is still working, LVGL will use this function when required the be sure GPU rendering is ready.
 
+### Examples
 All together it looks like this:
 ```c
-    lv_disp_drv_t disp_drv;                 /*A variable to hold the drivers. Can be local variable*/
+    static lv_disp_drv_t disp_drv;          /*A variable to hold the drivers. Must be static or global.*/
     lv_disp_drv_init(&disp_drv);            /*Basic initialization*/
-    disp_drv.buffer = &disp_buf;            /*Set an initialized buffer*/
+    disp_drv.draw_buf = &disp_buf;          /*Set an initialized buffer*/
     disp_drv.flush_cb = my_flush_cb;        /*Set a flush callback to draw to the display*/
+    disp_drv.hor_res = 320;                 /*Set the horizontal resolution in pixels*/
+    disp_drv.ver_res = 240;                 /*Set the vertical resolution in pixels*/
+    
     lv_disp_t * disp;
     disp = lv_disp_drv_register(&disp_drv); /*Register the driver and save the created display objects*/
 ```
 
-Here some simple examples of the callbacks:
+Here are some simple examples of the callbacks:
 ```c
 void my_flush_cb(lv_disp_drv_t * disp_drv, const lv_area_t * area, lv_color_t * color_p)
 {
@@ -115,19 +133,11 @@ void my_gpu_fill_cb(lv_disp_drv_t * disp_drv, lv_color_t * dest_buf, const lv_ar
     }
 }
 
-void my_gpu_blend_cb(lv_disp_drv_t * disp_drv, lv_color_t * dest, const lv_color_t * src, uint32_t length, lv_opa_t opa)
-{
-    /*It's an example code which should be done by your GPU*/
-    uint32_t i;
-    for(i = 0; i < length; i++) {
-        dest[i] = lv_color_mix(dest[i], src[i], opa);
-    }
-}
 
 void my_rounder_cb(lv_disp_drv_t * disp_drv, lv_area_t * area)
 {
-  /* Update the areas as needed. Can be only larger.
-   * For example to always have lines 8 px height:*/
+  /* Update the areas as needed.
+   * For example make the area to start only on 8th rows and have Nx8 pixel height:*/
    area->y1 = area->y1 & 0x07;
    area->y2 = (area->y2 & 0x07) + 8;
 }
@@ -136,9 +146,9 @@ void my_set_px_cb(lv_disp_drv_t * disp_drv, uint8_t * buf, lv_coord_t buf_w, lv_
 {
     /* Write to the buffer as required for the display.
      * Write only 1-bit for monochrome displays mapped vertically:*/
- buf += buf_w * (y >> 3) + x;
- if(lv_color_brightness(color) > 128) (*buf) |= (1 << (y % 8));
- else (*buf) &= ~(1 << (y % 8));
+   buf += buf_w * (y >> 3) + x;
+   if(lv_color_brightness(color) > 128) (*buf) |= (1 << (y % 8));
+   else (*buf) &= ~(1 << (y % 8));
 }
 
 void my_monitor_cb(lv_disp_drv_t * disp_drv, uint32_t time, uint32_t px)
@@ -169,6 +179,12 @@ Display rotation can also be changed at runtime using the `lv_disp_set_rotation(
 
 Support for software rotation is a new feature, so there may be some glitches/bugs depending on your configuration. If you encounter a problem please open an issue on [GitHub](https://github.com/lvgl/lvgl/issues).
 
+## Further reading
+
+See [lv_port_disp_template.c](https://github.com/lvgl/lvgl/blob/master/examples/porting/lv_port_disp_template.c) for a template for your own driver.
+
+Check out the [Drawing](/overview/drawing) section to learn more about how rendering works in LVGL.
+
 ## API
 
 ```eval_rst
diff --git a/docs/porting/indev.md b/docs/porting/indev.md
index c90dbbc43..fbe8ffc43 100644
--- a/docs/porting/indev.md
+++ b/docs/porting/indev.md
@@ -17,21 +17,18 @@ indev_drv.read_cb =...              /*See below.*/
 lv_indev_t * my_indev = lv_indev_drv_register(&indev_drv);
 ```
 
-**type** can be
-- **LV_INDEV_TYPE_POINTER** touchpad or mouse
-- **LV_INDEV_TYPE_KEYPAD** keyboard or keypad
-- **LV_INDEV_TYPE_ENCODER** encoder with left, right, push options
-- **LV_INDEV_TYPE_BUTTON** external buttons pressing the screen
-
-**read_cb** is a function pointer which will be called periodically to report the current state of an input device.
-It can also buffer data and return `false` when no more data to be read or `true` when the buffer is not empty.
+`type` can be
+- `LV_INDEV_TYPE_POINTER` touchpad or mouse
+- `LV_INDEV_TYPE_KEYPAD` keyboard or keypad
+- `LV_INDEV_TYPE_ENCODER` encoder with left/right turn and push options
+- `LV_INDEV_TYPE_BUTTON` external buttons virtually pressing the screen
 
+`read_cb` is a function pointer which will be called periodically to report the current state of an input device.
 
 Visit [Input devices](/overview/indev) to learn more about input devices in general.
 
-
 ###  Touchpad, mouse or any pointer
-Input devices which can click points of the screen belong to this category.
+Input devices that can click points of the screen belong to this category.
 
 ```c
 indev_drv.type = LV_INDEV_TYPE_POINTER;
@@ -39,12 +36,15 @@ indev_drv.read_cb = my_input_read;
 
 ...
 
-bool my_input_read(lv_indev_drv_t * drv, lv_indev_data_t*data)
+void my_input_read(lv_indev_drv_t * drv, lv_indev_data_t*data)
 {
+  if(touchpad_pressed) {
     data->point.x = touchpad_x;
     data->point.y = touchpad_y;
-    data->state = LV_INDEV_STATE_PR or LV_INDEV_STATE_REL;
-    return false; /*No buffering now so no more data read*/
+    data->state = LV_INDEV_STATE_PRESSED;
+  } else {
+    data->state = LV_INDEV_STATE_RELEASED; 
+  }
 }
 ```
 
@@ -59,7 +59,6 @@ Full keyboards with all the letters or simple keypads with a few navigation butt
 
 To use a keyboard/keypad:
 - Register a `read_cb` function with `LV_INDEV_TYPE_KEYPAD` type.
-- Enable `LV_USE_GROUP` in *lv_conf.h*
 - An object group has to be created: `lv_group_t * g = lv_group_create()`  and objects have to be added to it with `lv_group_add_obj(g, obj)`
 - The created group has to be assigned to an input device: `lv_indev_set_group(my_indev, g)` (`my_indev` is the return value of `lv_indev_drv_register`)
 - Use `LV_KEY_...` to navigate among the objects in the group. See `lv_core/lv_group.h` for the available keys.
@@ -70,13 +69,11 @@ indev_drv.read_cb = keyboard_read;
 
 ...
 
-bool keyboard_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
+void keyboard_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
   data->key = last_key();            /*Get the last pressed or released key*/
 
-  if(key_pressed()) data->state = LV_INDEV_STATE_PR;
-  else data->state = LV_INDEV_STATE_REL;
-
-  return false; /*No buffering now so no more data read*/
+  if(key_pressed()) data->state = LV_INDEV_STATE_PRESSED;
+  else data->state = LV_INDEV_STATE_RELEASED;
 }
 ```
 
@@ -103,23 +100,22 @@ indev_drv.read_cb = encoder_read;
 
 ...
 
-bool encoder_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
+void encoder_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
   data->enc_diff = enc_get_new_moves();
 
-  if(enc_pressed()) data->state = LV_INDEV_STATE_PR;
-  else data->state = LV_INDEV_STATE_REL;
-
-  return false; /*No buffering now so no more data read*/
+  if(enc_pressed()) data->state = LV_INDEV_STATE_PRESSED;
+  else data->state = LV_INDEV_STATE_RELEASED;
 }
 ```
+
 #### Using buttons with Encoder logic
-In addition to standard encoder behavior, you can also utilise its logic to navigate(focus) and edit widgets using buttons. 
-This is especially handy if you have only few buttons avalible, or you want to use other buttons in addition to encoder wheel.
+In addition to standard encoder behavior, you can also utilize its logic to navigate(focus) and edit widgets using buttons. 
+This is especially handy if you have only few buttons available, or you want to use other buttons in addition to encoder wheel.
 
-You need to have 3 buttons avalible:
-- **LV_KEY_ENTER** will simulate press or pushing of the encoder button
-- **LV_KEY_LEFT** will simulate turnuing encoder left
-- **LV_KEY_RIGHT** will simulate turnuing encoder right
+You need to have 3 buttons available:
+- `LV_KEY_ENTER` will simulate press or pushing of the encoder button
+- `LV_KEY_LEFT` will simulate turning encoder left
+- `LV_KEY_RIGHT` will simulate turning encoder right
 - other keys will be passed to the focused widget
 
 If you hold the keys it will simulate encoder click with period specified in `indev_drv.long_press_rep_time`.
@@ -133,9 +129,9 @@ indev_drv.read_cb = encoder_with_keys_read;
 bool encoder_with_keys_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
   data->key = last_key();            /*Get the last pressed or released key*/
                                      /* use LV_KEY_ENTER for encoder press */
-  if(key_pressed()) data->state = LV_INDEV_STATE_PR;
+  if(key_pressed()) data->state = LV_INDEV_STATE_PRESSED;
   else {
-      data->state = LV_INDEV_STATE_REL;
+      data->state = LV_INDEV_STATE_RELEASED;
       /* Optionally you can also use enc_diff, if you have encoder*/
       data->enc_diff = enc_get_new_moves();
   }
@@ -160,38 +156,46 @@ indev_drv.read_cb = button_read;
 
 ...
 
-bool button_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
+void button_read(lv_indev_drv_t * drv, lv_indev_data_t*data){
     static uint32_t last_btn = 0;   /*Store the last pressed button*/
     int btn_pr = my_btn_read();     /*Get the ID (0,1,2...) of the pressed button*/
     if(btn_pr >= 0) {               /*Is there a button press? (E.g. -1 indicated no button was pressed)*/
        last_btn = btn_pr;           /*Save the ID of the pressed button*/
-       data->state = LV_INDEV_STATE_PR;  /*Set the pressed state*/
+       data->state = LV_INDEV_STATE_PRESSED;  /*Set the pressed state*/
     } else {
-       data->state = LV_INDEV_STATE_REL; /*Set the released state*/
+       data->state = LV_INDEV_STATE_RELEASED; /*Set the released state*/
     }
 
     data->btn = last_btn;            /*Save the last button*/
-
-    return false;                    /*No buffering now so no more data read*/
 }
 ```
 
 ## Other features
 
-Besides `read_cb` a `feedback_cb` callback can be also specified in `lv_indev_drv_t`.
-`feedback_cb` is called when any type of event is sent by the input devices. (independently from its type). It allows making feedback for the user e.g. to play a sound on `LV_EVENT_CLICK`.
+### Parameters
 
-The default value of the following parameters can be set in *lv_conf.h* but the default value can be overwritten in `lv_indev_drv_t`:
-- **drag_limit** Number of pixels to slide before actually drag the object
-- **drag_throw**  Drag throw slow-down in [%]. Greater value means faster slow-down
-- **long_press_time** Press time to send `LV_EVENT_LONG_PRESSED` (in milliseconds)
-- **long_press_rep_time** Interval of sending `LV_EVENT_LONG_PRESSED_REPEAT` (in milliseconds)
-- **read_task** pointer to the `lv_task` which reads the input device. Its parameters can be changed by `lv_task_...()` functions
+The default value of the following parameters can changed in `lv_indev_drv_t`:
+- `scroll_limit` Number of pixels to slide before actually scrolling the object.
+- `scroll_throw`  Scroll throw (momentum) slow-down in [%]. Greater value means faster slow-down.
+- `long_press_time` Press time to send `LV_EVENT_LONG_PRESSED` (in milliseconds)
+- `long_press_rep_time` Interval of sending `LV_EVENT_LONG_PRESSED_REPEAT` (in milliseconds)
+- `read_timer` pointer to the `lv_rimer` which reads the input device. Its parameters can be changed by `lv_timer_...()` functions. `LV_INDEV_DEF_READ_PERIOD` in `lv_conf.h` sets the default read period.
 
+### Feedback
 
+Besides `read_cb` a `feedback_cb` callback can be also specified in `lv_indev_drv_t`.
+`feedback_cb` is called when any type of event is sent by the input devices. (independently from its type). It allows making feedback for the user e.g. to play a sound on `LV_EVENT_CLICKED`.
+
+
+### Associating with a display
 Every Input device is associated with a display. By default, a new input device is added to the lastly created or the explicitly selected (using `lv_disp_set_default()`) display.
 The associated display is stored and can be changed in `disp` field of the driver.
 
+### Event driven reading
+By default LVGL calls `read_cb` periodically. This way there is a chance that some user gestures are missed. 
+
+To solve this you write an event driven driver for your input device that buffers measured data. In `read_cb` you can set the buffered data instead of reading the input device. 
+You can set the `data->continue_reding` flag to LVGL there is more data to read and call `read_cb` again.
 
 ## API