Add example that demonstrates screen rotation using canvas

Author: dr-glenn

components/lcd/esp_lcd_ssd1681/examples/epaper_lvgl_rotate/CMakeLists.txt

@@ -0,0 +1,8 @@
+# For more information about build system see
+# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
+# The following five lines of boilerplate have to be in your project's
+# CMakeLists in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.5)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(epaper_lvgl_rotate)

components/lcd/esp_lcd_ssd1681/examples/epaper_lvgl_rotate/README.md

@@ -0,0 +1,92 @@
+# _LVGL Rotate_
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+This example demonstrates rotation of the screen on an eInk display. It displays a long text string
+at rotations of 0, 90, 180 and 270 degrees. It will work on a Waveshare 2.7" eInk display that natively
+has screen dimensions of 176W x 264H; it should also work on a Waveshare 1.54" display with dimensions
+200 x 200 (not tested by me). Changing the width and height constants (search main.c for DISPLAY_X)
+should work with other displays that have SSD1680 or SSD1681 controllers.
+
+Rotating eInk displays is not the same as more dyanmic displays such as LCD.
+The screen can be rotated only in multiples of 90 degrees: 0, 90, 180, 270.
+An eInk display should not be updated often, in fact the manufacturers (Waveshare and GooDisplay)
+state that displays should be rewritten no more often than 3 minutess. During development you can
+rewrite more often, but this can shorten the lifetime of the display.
+With some eInk displays it is possible to only update portions of the screen, but manufacturers
+warn that this should not be done for too many cycles - eventually you should refresh the entire screen.
+This demo only does full screen refreshes.
+
+An eInk display should usually be thought of as static - for example you will display
+a weather forecast and update it every 15 minutes.
+
+Let's discuss eInk rotation.
+
+- eInk displays handled by this example have either a SSD1680 or SSD1681 controller.
+
+- The controller cannot perform hardware rotation (unlike some LCD).
+
+- Some eInk display examples in ESP-IDF and ESP-BSP use a 1.54 inch square display, 200x200 pixels.
+You can rotate a square screen by multiples of 90 degrees by using mirror and swap axes operations.
+
+- If the display is not square, then most rotation schemes result in a clipped output.
+Swapping X&Y axes is poorly defined.
+
+- LVGL can do software rotation (sw_rotate=true), but it is unusable for our needs. Why?
+Suppose the display is 200W x 100H. When you rotate by 90, many algorithms don't know
+where to put the pixels from 101 to 200, so the screen image becomes a square measuring 100 x 100
+and the screen image is clipped.
+
+Waveshare eInk displays have a default orientation, portrait or landscape. AFAIK,
+the SSD1680 controller cannot be programmed to change the orientation (sure would be nice).
+Many non-square displays are portrait, even though many applications would prefer landscape.
+So what to do?
+
+- The controller does not perform hardware rotation.
+
+- LVGL software rotation has problems (see below).
+
+- Since we want to change orientation between portrait and landscape, we need a function that
+moves the pixels from rows to columns.
+
+## What are the problems with LVGL sw_rotate?
+
+If **sw_rotate=true**, then **full_refresh** must be *false*. This results in the full screen image
+getting rotated in pieces and written to the device by DMA. While this is fine for an LCD,
+eInk displays need to refresh when each DMA transfer completes, resulting in flashing of the disdplay
+multiple times until all the chunks have been transferred. Furthermore, **sw_rotate** will clip the screen
+image as mentioned above.
+
+## How can we change from portrait to landscape orientation?
+
+The answer is to use a *canvas*. We create a canvas in the desired orientation (for example: landscape)
+and write to it. If you write a landscape canvas to a portrait display, it will be clipped. If you rotate
+the landscape canvas by 90 or 270 degrees, you expect that it should appear on the screen without clipping.
+You should be able to rotate a canvas with **lv_canvas_transform()**, but I was unable to get it to work
+with LVGL v. 8.3.0. Therefore I wrote function **rotate_buffer()** to perform a 90 degree rotation.
+270 degree roatation is performed with 90 degree rotation plus mirror on both X and Y axes.
+
+## How to use example
+We encourage the users to use the example as a template for new projects.
+A recommended way is to follow the instructions on a [docs page](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html#start-a-new-project).
+
+## Example folder contents
+
+The project **sample_project** contains one source file in C language [main.c](main/main.c). The file is located in folder [main](main).
+
+ESP-IDF projects are built using CMake. The project build configuration is contained in `CMakeLists.txt`
+files that provide set of directives and instructions describing the project's source files and targets
+(executable, library, or both). 
+
+Below is short explanation of remaining files in the project folder.
+
+```
+├── CMakeLists.txt
+├── main
+│   ├── CMakeLists.txt
+│   ├── main.c
+│   └── lvgl_demo_ui.c
+└── README.md                  This is the file you are currently reading
+```
+Additionally, the sample project contains Makefile and component.mk files, used for the legacy Make based build system. 
+They are not used or needed when building with CMake and idf.py.

components/lcd/esp_lcd_ssd1681/examples/epaper_lvgl_rotate/main/CMakeLists.txt

@@ -0,0 +1,2 @@
+idf_component_register(SRCS "main.c" "lvgl_demo_ui.c"
+                       INCLUDE_DIRS ".")

components/lcd/esp_lcd_ssd1681/examples/epaper_lvgl_rotate/main/idf_component.yml

@@ -0,0 +1,9 @@
+dependencies:
+  idf: ">=5.0"
+  lvgl/lvgl: "~8.3.0"
+  esp_lcd_ssd1681: 
+    # I am specifying the path of the component because the component
+    # had not been published to the ESP Component Registry by the time 
+    # I write this example.
+    # Development will be better if you add esp_lcd_ssd1681 as a component to your project.
+    path: "../../../"

components/lcd/esp_lcd_ssd1681/examples/epaper_lvgl_rotate/main/lvgl_demo_ui.c

@@ -0,0 +1,104 @@
+/*
+ * SPDX-FileCopyrightText: 2021-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: CC0-1.0
+ */
+
+// This demo UI is adapted from LVGL official example: https://docs.lvgl.io/master/widgets/extra/meter.html#simple-meter
+// This demo writes text onto canvas that can later be rotated to appear on a portrait or landscape oriened display.
+
+#define LV_FONT_MONTSERRAT_28 1 // 28 pt font. Must precede "lvgl.h".
+
+#include "lvgl.h"
+#include "esp_heap_caps.h"
+
+#define CANVAS_COLOR_FORMAT LV_IMG_CF_ALPHA_1BIT    // desginates 1 bit per pixel display.
+
+extern void rotate_buffer(uint32_t rotate, int xlen, int ylen, uint8_t *in_buf, uint8_t *out_buf);
+
+static lv_style_t style_28;
+static uint8_t *canvas_buffer = NULL;
+/**
+ *
+ * @brief Use LVGL canvas to generate display and demonstrate rotation
+ * @param width pixels of non-rotated display
+ * @param height pixels of non-rotated display
+ * @param rotate LVGL rotation value, [0, 1, 2, 3] for LV_DISP_ROT_<NONE|90|180|270]>
+ * @note A canvas is created with no parent. Text is written to the canvas.
+ *       The canvas is then assigned the active screen as parent.
+ *       This apparently causes lvgl_flush_callback to be invoked.
+ */
+void lvgl_canvas_ui(int width, int height, uint32_t rotate)
+
+{
+    int disp_x, disp_y;
+    if (rotate == LV_DISP_ROT_90 || rotate == LV_DISP_ROT_270) {
+        disp_x = height;
+        disp_y = width;
+    } else {
+        disp_y = height;
+        disp_x = width;
+    }
+    if (!canvas_buffer) {
+        // Needs 8 extra bytes for monochrome displays?
+        canvas_buffer = heap_caps_malloc(disp_x * disp_y / 8 + 8, MALLOC_CAP_DMA);
+    }
+    memset(canvas_buffer, 0x00, disp_x * disp_y / 8 + 8);
+
+    // Create a screen (a necessary, non-visible step in LVGL)
+    lv_obj_t *scr = lv_obj_create(NULL);    // canvas must not be attached to display until later
+    // Create the canvas on the screen
+    lv_obj_t *canvas = lv_canvas_create(scr);
+    // Assign canvas_buffer to the canvas. The canvas is configured to be either portrait or landscape orientation.
+    lv_canvas_set_buffer(canvas, canvas_buffer, disp_x, disp_y, CANVAS_COLOR_FORMAT);
+    lv_canvas_fill_bg(canvas, lv_color_hex(0x000000), LV_OPA_0);    // 0x000000 is a white background on eInk displays
+
+#if 0
+    // NOTE: palette is only used with indexed color formats, not monochrome.
+    // Might be used for multi-color eInk displays?
+    lv_canvas_set_palette(canvas, 0, LV_COLOR_WHITE);
+    lv_canvas_set_palette(canvas, 1, LV_COLOR_BLACK);
+#endif
+
+    lv_style_init(&style_28);
+    lv_style_set_text_font(&style_28, &lv_font_montserrat_28);
+    lv_draw_label_dsc_t label_dsc;  // label properties descriptor
+    lv_draw_label_dsc_init(&label_dsc);
+    label_dsc.color = lv_color_make(0xFF, 0xFF, 0xFF); // Black color (or use lv_color_hex(0xFFFFFF))
+    label_dsc.font = &lv_font_montserrat_28; // Use a built-in font
+    label_dsc.align = LV_TEXT_ALIGN_LEFT;
+
+    int xoff = 10, yoff = 10;   // offset for start of text string
+    // canvas_draw_text automatically wraps text when right margin is reached
+    lv_canvas_draw_text(canvas, xoff, yoff, disp_x - xoff, &label_dsc, "This text goes to end of line and then wraps. Isn't that cool?");
+
+    // Now we need a second canvas if we want to rotate
+    lv_obj_t *rot_canvas = lv_canvas_create(lv_obj_create(NULL));
+    uint8_t *rot_buf = heap_caps_malloc(disp_x * disp_y / 8 + 8, MALLOC_CAP_DMA);
+    memset(rot_buf, 0x00, disp_x * disp_y / 8 + 8);
+
+    if (rotate == LV_DISP_ROT_90 || rotate == LV_DISP_ROT_270) {
+#if 1    // use my rotate function
+        // ROT_270 is performed by ROT90 and then mirror both X & Y (in main.c)
+        rotate_buffer(rotate, disp_x, disp_y, canvas_buffer, rot_buf);
+        lv_canvas_set_buffer(canvas, rot_buf, width, height, LV_IMG_CF_ALPHA_1BIT);
+
+#else    // use lvgl_canvas_transform
+        // Display of 90 appears as 0 degrees, and clipped on right side.
+        // Display of 270 appears as 180 degrees, and clipped on left side of display.
+        // The text is first written to a landscape canvas. Thus it seems that no rotation occurs,
+        // thereby resulting in the text clipping.
+        int angle = 900 * rotate;
+
+        lv_canvas_set_buffer(rot_canvas, rot_buf, height, width, LV_IMG_CF_ALPHA_1BIT);
+        lv_img_dsc_t img_desc = *lv_canvas_get_img(canvas);
+        lv_canvas_transform(rot_canvas, &img_desc, angle, 256, 0, 264, width / 2, height / 2, true);
+        lv_canvas_copy_buf(canvas, rot_buf, 0, 0, lv_obj_get_height(rot_canvas), lv_obj_get_width(rot_canvas));
+#endif
+    }
+    // Must clear LVGL display, else we get "double-exposure" image on screen
+    lv_obj_clean(lv_scr_act());
+    // Attach the canvas to the active screen (the display device).
+    // This presumably triggers LVGL flush callback (see flush_cb in main.c)
+    lv_obj_set_parent(canvas, lv_scr_act());
+}