feat(drivers): add Windows backend for LVGL v9 (#5313)

Kconfig

@@ -1489,6 +1489,10 @@ menu "LVGL configuration"
 		config LV_USE_ILI9341
 			bool "Use ILI9341 LCD driver"
 			default n
+
+		config LV_USE_WINDOWS
+			bool "Use LVGL Windows backend"
+			default n
 	endmenu
 
 	menu "Examples"

docs/integration/driver/index.rst

@@ -8,3 +8,4 @@ Drivers
     display/index
     touchpad/index
     X11
+    windows

docs/integration/driver/windows.rst

@@ -0,0 +1,105 @@
+=============================
+Windows Display/Inputs driver
+=============================
+
+Overview
+-------------
+
+The **Windows** display/input `driver <https://github.com/lvgl/lvgl/src/dev/windows>`__ offers support for simulating the LVGL display and keyboard/mouse inputs in a Windows Win32 window.
+
+The main purpose for this driver is for testing/debugging the LVGL application in a **Windows** simulation window via **simulator mode**, or developing a standard **Windows** desktop application with LVGL via **application mode**.
+
+Here are the **similarity** for simulator mode and application mode.
+
+- Support LVGL pointer, keypad and encoder devices integration.
+- Support Windows touch input.
+- Support Windows input method integration input.
+- Support Per-monitor DPI Aware (both V1 and V2).
+
+Here are the **differences** for simulator mode and application mode.
+
+Simulator Mode
+^^^^^^^^^^^^^^
+
+- Designed for LVGL simulation scenario.
+- Keep the LVGL display resolution all time for trying best to simulate UI layout which will see in their production devices.
+- When Windows DPI scaling setting is changed, Windows backend will stretch the display content.
+
+Application Mode
+^^^^^^^^^^^^^^^^
+
+- Designed for Windows desktop application development scenario.
+- Have the Window resizing support and LVGL display resolution will be changed.
+- When Windows DPI scaling setting is changed, the LVGL display DPI value will also be changed.
+
+Prerequisites
+-------------
+
+The minimum Windows OS version this driver supported is Windows Server 2003, or Windows XP with East Asian language support installed because the input method integration support need that.
+
+Configure Windows driver
+--------------------
+
+Enable the Windows driver support in lv_conf.h, by cmake compiler define or by KConfig
+
+.. code:: c
+
+    #define LV_USE_WINDOWS  1
+
+Usage
+-----
+
+.. code:: c
+
+    #include <Windows.h>
+    #include "lvgl/lvgl.h"
+    #include "lvgl/examples/lv_examples.h"
+    #include "lvgl/demos/lv_demos.h"
+
+    int main()
+    {
+        lv_init();
+
+        int32_t zoom_level = 100;
+        bool allow_dpi_override = false;
+        bool simulator_mode = false;
+        lv_display_t* display = lv_windows_create_display(
+            L"LVGL Display Window",
+            800,
+            480,
+            zoom_level,
+            allow_dpi_override,
+            simulator_mode);
+        if (!display)
+        {
+            return -1;
+        }
+
+        lv_indev_t* pointer_device = lv_windows_acquire_pointer_indev(display);
+        if (!pointer_device)
+        {
+            return -1;
+        }
+
+        lv_indev_t* keypad_device = lv_windows_acquire_keypad_indev(display);
+        if (!keypad_device)
+        {
+            return -1;
+        }
+
+        lv_indev_t* encoder_device = lv_windows_acquire_encoder_indev(display);
+        if (!encoder_device)
+        {
+            return -1;
+        }
+
+        lv_demo_widgets();
+
+        while (1)
+        {
+            uint32_t time_till_next = lv_timer_handler();
+            Sleep(time_till_next);
+        }
+
+        return 0;
+    }

lv_conf_template.h

@@ -893,6 +893,8 @@
 
 #define LV_USE_GENERIC_MIPI (LV_USE_ST7735 | LV_USE_ST7789 | LV_USE_ST7796 | LV_USE_ILI9341)
 
+/* LVGL Windows backend */
+#define LV_USE_WINDOWS    0
 
 /*==================
 * EXAMPLES

lvgl.h

@@ -133,6 +133,9 @@ extern "C" {
 
 #include "src/dev/evdev/lv_evdev.h"
 
+#include "src/dev/windows/lv_windows_input.h"
+#include "src/dev/windows/lv_windows_display.h"
+
 #include "src/core/lv_global.h"
 /*********************
  *      DEFINES

src/dev/windows/lv_windows_context.h

@@ -0,0 +1,123 @@
+/**
+ * @file lv_windows_context.h
+ *
+ */
+
+#ifndef LV_WINDOWS_CONTEXT_H
+#define LV_WINDOWS_CONTEXT_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*********************
+ *      INCLUDES
+ *********************/
+
+#include "../../display/lv_display.h"
+#include "../../indev/lv_indev.h"
+
+#if LV_USE_WINDOWS
+
+#include <windows.h>
+
+/*********************
+ *      DEFINES
+ *********************/
+
+/**********************
+ *      TYPEDEFS
+ **********************/
+
+typedef struct _lv_windows_pointer_context_t {
+    lv_indev_state_t state;
+    lv_point_t point;
+    lv_indev_t * indev;
+} lv_windows_pointer_context_t;
+
+typedef struct _lv_windows_keypad_queue_item_t {
+    uint32_t key;
+    lv_indev_state_t state;
+} lv_windows_keypad_queue_item_t;
+
+typedef struct _lv_windows_keypad_context_t {
+    CRITICAL_SECTION mutex;
+    lv_ll_t queue;
+    uint16_t utf16_high_surrogate;
+    uint16_t utf16_low_surrogate;
+    lv_indev_t * indev;
+} lv_windows_keypad_context_t;
+
+typedef struct _lv_windows_encoder_context_t {
+    lv_indev_state_t state;
+    int16_t enc_diff;
+    lv_indev_t * indev;
+} lv_windows_encoder_context_t;
+
+typedef struct _lv_windows_window_context_t {
+    lv_display_t * display_device_object;
+    lv_timer_t * display_timer_object;
+
+    int32_t window_dpi;
+    int32_t zoom_level;
+    bool allow_dpi_override;
+    bool simulator_mode;
+    bool display_resolution_changed;
+    lv_point_t requested_display_resolution;
+
+    HDC display_framebuffer_context_handle;
+    uint32_t * display_framebuffer_base;
+    size_t display_framebuffer_size;
+
+    lv_windows_pointer_context_t pointer;
+    lv_windows_keypad_context_t keypad;
+    lv_windows_encoder_context_t encoder;
+
+} lv_windows_window_context_t;
+
+typedef struct _lv_windows_create_display_data_t {
+    const wchar_t * title;
+    int32_t hor_res;
+    int32_t ver_res;
+    int32_t zoom_level;
+    bool allow_dpi_override;
+    bool simulator_mode;
+    HANDLE mutex;
+    lv_display_t * display;
+} lv_windows_create_display_data_t;
+
+/**********************
+ * GLOBAL PROTOTYPES
+ **********************/
+
+/**
+ * @brief Initialize the LVGL Windows backend.
+ * @remark This is a private API which is used for LVGL Windows backend
+ *         implementation. LVGL users shouldn't use that because the
+ *         LVGL has already used it in lv_init.
+*/
+void lv_windows_platform_init(void);
+
+/**
+ * @brief Get the window context from specific LVGL display window.
+ * @param window_handle The window handle of specific LVGL display window.
+ * @return The window context from specific LVGL display window.
+ * @remark This is a private API which is used for LVGL Windows backend
+ *         implementation. LVGL users shouldn't use that because the
+ *         maintainer doesn't promise the application binary interface
+ *         compatibility for this API.
+*/
+lv_windows_window_context_t * lv_windows_get_window_context(
+    HWND window_handle);
+
+/**********************
+ *      MACROS
+ **********************/
+
+#endif // LV_USE_WINDOWS
+
+#ifdef __cplusplus
+} /*extern "C"*/
+#endif
+
+#endif /*LV_WINDOWS_CONTEXT_H*/

src/dev/windows/lv_windows_display.c

@@ -0,0 +1,170 @@
+/**
+ * @file lv_windows_display.c
+ *
+ */
+
+/*********************
+ *      INCLUDES
+ *********************/
+
+#include "lv_windows_display.h"
+#if LV_USE_WINDOWS
+
+#include "lv_windows_context.h"
+
+#include <process.h>
+
+/*********************
+ *      DEFINES
+ *********************/
+
+/**********************
+ *      TYPEDEFS
+ **********************/
+
+/**********************
+ *  STATIC PROTOTYPES
+ **********************/
+
+static unsigned int __stdcall lv_windows_display_thread_entrypoint(
+    void * parameter);
+
+/**********************
+ *  STATIC VARIABLES
+ **********************/
+
+/**********************
+ *      MACROS
+ **********************/
+
+/**********************
+ *   GLOBAL FUNCTIONS
+ **********************/
+
+lv_display_t * lv_windows_create_display(
+    const wchar_t * title,
+    int32_t hor_res,
+    int32_t ver_res,
+    int32_t zoom_level,
+    bool allow_dpi_override,
+    bool simulator_mode)
+{
+    lv_windows_create_display_data_t data;
+
+    lv_memzero(&data, sizeof(lv_windows_create_display_data_t));
+    data.title = title;
+    data.hor_res = hor_res;
+    data.ver_res = ver_res;
+    data.zoom_level = zoom_level;
+    data.allow_dpi_override = allow_dpi_override;
+    data.simulator_mode = simulator_mode;
+    data.mutex = CreateEventExW(NULL, NULL, 0, EVENT_ALL_ACCESS);
+    data.display = NULL;
+    if(!data.mutex) {
+        return NULL;
+    }
+
+    HANDLE thread = (HANDLE)_beginthreadex(
+                        NULL,
+                        0,
+                        lv_windows_display_thread_entrypoint,
+                        &data,
+                        0,
+                        NULL);
+    LV_ASSERT_NULL(thread);
+
+    WaitForSingleObjectEx(data.mutex, INFINITE, FALSE);
+
+    if(thread) {
+        CloseHandle(thread);
+    }
+
+    if(data.mutex) {
+        CloseHandle(data.mutex);
+    }
+
+    return data.display;
+}
+
+HWND lv_windows_get_display_window_handle(lv_display_t * display)
+{
+    return (HWND)lv_display_get_driver_data(display);
+}
+
+int32_t lv_windows_zoom_to_logical(int32_t physical, int32_t zoom_level)
+{
+    return MulDiv(physical, LV_WINDOWS_ZOOM_BASE_LEVEL, zoom_level);
+}
+
+int32_t lv_windows_zoom_to_physical(int32_t logical, int32_t zoom_level)
+{
+    return MulDiv(logical, zoom_level, LV_WINDOWS_ZOOM_BASE_LEVEL);
+}
+
+int32_t lv_windows_dpi_to_logical(int32_t physical, int32_t dpi)
+{
+    return MulDiv(physical, USER_DEFAULT_SCREEN_DPI, dpi);
+}
+
+int32_t lv_windows_dpi_to_physical(int32_t logical, int32_t dpi)
+{
+    return MulDiv(logical, dpi, USER_DEFAULT_SCREEN_DPI);
+}
+
+/**********************
+ *   STATIC FUNCTIONS
+ **********************/
+
+static unsigned int __stdcall lv_windows_display_thread_entrypoint(
+    void * parameter)
+{
+    lv_windows_create_display_data_t * data = parameter;
+    LV_ASSERT_NULL(data);
+
+    DWORD window_style = WS_OVERLAPPEDWINDOW;
+    if(data->simulator_mode) {
+        window_style &= ~(WS_SIZEBOX | WS_MAXIMIZEBOX | WS_THICKFRAME);
+    }
+
+    HWND window_handle = CreateWindowExW(
+                             WS_EX_CLIENTEDGE,
+                             L"LVGL.Window",
+                             data->title,
+                             window_style,
+                             CW_USEDEFAULT,
+                             0,
+                             data->hor_res,
+                             data->ver_res,
+                             NULL,
+                             NULL,
+                             NULL,
+                             data);
+    if(!window_handle) {
+        return 0;
+    }
+
+    lv_windows_window_context_t * context = lv_windows_get_window_context(
+                                                window_handle);
+    if(!context) {
+        return 0;
+    }
+
+    data->display = context->display_device_object;
+
+    ShowWindow(window_handle, SW_SHOW);
+    UpdateWindow(window_handle);
+
+    LV_ASSERT_NULL(SetEvent(data->mutex));
+
+    data = NULL;
+
+    MSG message;
+    while(GetMessageW(&message, NULL, 0, 0)) {
+        TranslateMessage(&message);
+        DispatchMessageW(&message);
+    }
+
+    return 0;
+}
+
+#endif // LV_USE_WINDOWS

src/dev/windows/lv_windows_display.h

@@ -0,0 +1,127 @@
+/**
+ * @file lv_windows_display.h
+ *
+ */
+
+#ifndef LV_WINDOWS_DISPLAY_H
+#define LV_WINDOWS_DISPLAY_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*********************
+ *      INCLUDES
+ *********************/
+
+#include "../../display/lv_display.h"
+#include "../../indev/lv_indev.h"
+
+#if LV_USE_WINDOWS
+
+#include <windows.h>
+
+/*********************
+ *      DEFINES
+ *********************/
+
+#define LV_WINDOWS_ZOOM_BASE_LEVEL 100
+
+#ifndef USER_DEFAULT_SCREEN_DPI
+#define USER_DEFAULT_SCREEN_DPI 96
+#endif
+
+/**********************
+ *      TYPEDEFS
+ **********************/
+
+/**********************
+ * GLOBAL PROTOTYPES
+ **********************/
+
+/**
+ * @brief Create a LVGL display object.
+ * @param title The window title of LVGL display.
+ * @param hor_res The horizontal resolution value of LVGL display.
+ * @param ver_res The vertical resolution value of LVGL display.
+ * @param zoom_level The zoom level value. Base value is 100 a.k.a 100%.
+ * @param allow_dpi_override Allow DPI override if true, or follow the
+ *                           Windows DPI scaling setting dynamically.
+ * @param simulator_mode Create simulator mode display if true, or create
+ *                       application mode display.
+ * @return The created LVGL display object.
+*/
+lv_display_t * lv_windows_create_display(
+    const wchar_t * title,
+    int32_t hor_res,
+    int32_t ver_res,
+    int32_t zoom_level,
+    bool allow_dpi_override,
+    bool simulator_mode);
+
+/**
+ * @brief Get the window handle from specific LVGL display object.
+ * @param display The specific LVGL display object.
+ * @return The window handle from specific LVGL display object.
+*/
+HWND lv_windows_get_display_window_handle(lv_display_t * display);
+
+/**
+ * @brief Get logical pixel value from physical pixel value taken account
+ *        with zoom level.
+ * @param physical The physical pixel value taken account with zoom level.
+ * @param zoom_level The zoom level value. Base value is 100 a.k.a 100%.
+ * @return The logical pixel value.
+ * @remark It uses the same calculation style as Windows OS implementation.
+ *         It will be useful for integrate LVGL Windows backend to other
+ *         Windows applications.
+*/
+int32_t lv_windows_zoom_to_logical(int32_t physical, int32_t zoom_level);
+
+/**
+ * @brief Get physical pixel value taken account with zoom level from
+ *        logical pixel value.
+ * @param logical The logical pixel value.
+ * @param zoom_level The zoom level value. Base value is 100 a.k.a 100%.
+ * @return The physical pixel value taken account with zoom level.
+ * @remark It uses the same calculation style as Windows OS implementation.
+ *         It will be useful for integrate LVGL Windows backend to other
+ *         Windows applications.
+*/
+int32_t lv_windows_zoom_to_physical(int32_t logical, int32_t zoom_level);
+
+/**
+ * @brief Get logical pixel value from physical pixel value taken account
+ *        with DPI scaling.
+ * @param physical The physical pixel value taken account with DPI scaling.
+ * @param dpi The DPI scaling value. Base value is USER_DEFAULT_SCREEN_DPI.
+ * @return The logical pixel value.
+ * @remark It uses the same calculation style as Windows OS implementation.
+ *         It will be useful for integrate LVGL Windows backend to other
+ *         Windows applications.
+*/
+int32_t lv_windows_dpi_to_logical(int32_t physical, int32_t dpi);
+
+/**
+ * @brief Get physical pixel value taken account with DPI scaling from
+ *        logical pixel value.
+ * @param logical The logical pixel value.
+ * @param dpi The DPI scaling value. Base value is USER_DEFAULT_SCREEN_DPI.
+ * @return The physical pixel value taken account with DPI scaling.
+ * @remark It uses the same calculation style as Windows OS implementation.
+ *         It will be useful for integrate LVGL Windows backend to other
+ *         Windows applications.
+*/
+int32_t lv_windows_dpi_to_physical(int32_t logical, int32_t dpi);
+
+/**********************
+ *      MACROS
+ **********************/
+
+#endif // LV_USE_WINDOWS
+
+#ifdef __cplusplus
+} /*extern "C"*/
+#endif
+
+#endif /*LV_WINDOWS_DISPLAY_H*/

src/dev/windows/lv_windows_input.h

@@ -0,0 +1,83 @@
+/**
+ * @file lv_windows_input.h
+ *
+ */
+
+#ifndef LV_WINDOWS_INPUT_H
+#define LV_WINDOWS_INPUT_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*********************
+ *      INCLUDES
+ *********************/
+
+#include "../../display/lv_display.h"
+#include "../../indev/lv_indev.h"
+
+#if LV_USE_WINDOWS
+
+#include <windows.h>
+
+/*********************
+ *      DEFINES
+ *********************/
+
+/**********************
+ *      TYPEDEFS
+ **********************/
+
+/**********************
+ * GLOBAL PROTOTYPES
+ **********************/
+
+/**
+ * @brief Get the window handle from specific LVGL input device object.
+ * @param indev The specific LVGL input device object.
+ * @return The window handle from specific LVGL input device object.
+*/
+HWND lv_windows_get_indev_window_handle(lv_indev_t * indev);
+
+/**
+ * @brief Open a LVGL pointer input device object for the specific LVGL
+ *        display object, or create it if the LVGL pointer input device
+ *        object is not created or removed before.
+ * @param display The specific LVGL display object.
+ * @return The LVGL pointer input device object for the specific LVGL
+ *         display object.
+*/
+lv_indev_t * lv_windows_acquire_pointer_indev(lv_display_t * display);
+
+/**
+ * @brief Open a LVGL keypad input device object for the specific LVGL
+ *        display object, or create it if the LVGL keypad input device
+ *        object is not created or removed before.
+ * @param display The specific LVGL display object.
+ * @return The LVGL keypad input device object for the specific LVGL
+ *         display object.
+*/
+lv_indev_t * lv_windows_acquire_keypad_indev(lv_display_t * display);
+
+/**
+ * @brief Open a LVGL encoder input device object for the specific LVGL
+ *        display object, or create it if the LVGL encoder input device
+ *        object is not created or removed before.
+ * @param display The specific LVGL display object.
+ * @return The LVGL encoder input device object for the specific LVGL
+ *         display object.
+*/
+lv_indev_t * lv_windows_acquire_encoder_indev(lv_display_t * display);
+
+/**********************
+ *      MACROS
+ **********************/
+
+#endif // LV_USE_WINDOWS
+
+#ifdef __cplusplus
+} /*extern "C"*/
+#endif
+
+#endif /*LV_WINDOWS_INPUT_H*/

src/lv_conf_internal.h

@@ -2937,6 +2937,14 @@
     #endif
 #endif
 
+/* LVGL Windows backend */
+#ifndef LV_USE_WINDOWS
+    #ifdef CONFIG_LV_USE_WINDOWS
+        #define LV_USE_WINDOWS CONFIG_LV_USE_WINDOWS
+    #else
+        #define LV_USE_WINDOWS    0
+    #endif
+#endif
 
 /*==================
 * EXAMPLES

src/lv_init.c

@@ -39,6 +39,9 @@
 #if LV_USE_DRAW_VG_LITE
     #include "draw/vg_lite/lv_draw_vg_lite.h"
 #endif
+#if LV_USE_WINDOWS
+    #include "src/dev/windows/lv_windows_context.h"
+#endif
 
 /*********************
  *      DEFINES
@@ -185,6 +188,10 @@ void lv_init(void)
     lv_draw_sdl_init();
 #endif
 
+#if LV_USE_WINDOWS
+    lv_windows_platform_init();
+#endif
+
     _lv_obj_style_init();
 
     /*Initialize the screen refresh system*/