feat(display): Update to support multiple displays (#391)

* feat(display): Update to support multiple displays
* Update `espp::Display` to store the `flush` and `rotate` functions and to pass `this` as the context for the lvgl `display` and `event` callback

This allows any arbitrary function (including bound class member functions) to be passed for the flush callback and rotate callbacks, instead of requiring that they match the signatures and linkage of the lvgl lower-layer functions. This will enable a follow-up PR which allows the display drivers to no longer be static classes, further enabling multiple displays to be used in a single project.

Build and run `esp-box/example`, `t-dongle-s3/example` to ensure the existing code still works.

* update naming / docs

* update to assert if flush is nullptr and warn if rotation is nullptr

Author: finger563

components/display/include/display.hpp

@@ -44,13 +44,18 @@ template <typename Pixel> class Display : public BaseComponent {
   /**
    * @brief Callback for lvgl to flush segments of pixel data from the pixel
    *        buffers to the display.
+   * @param disp The display to flush data to.
+   * @param area The area of the display to flush data to.
+   * @param color_map The color data to flush to the display.
    */
-  using flush_fn = lv_display_flush_cb_t;
+  typedef std::function<void(lv_display_t *disp, const lv_area_t *area, uint8_t *color_map)>
+      flush_fn;
 
   /**
    * @brief Callback for lvgl event handler to reconfigure the display hardware.
+   * @param rotation The new rotation setting for the display.
    */
-  typedef void (*rotation_fn)(const DisplayRotation &rotation);
+  typedef std::function<void(const DisplayRotation &rotation)> rotation_fn;
 
   /**
    * @brief Callback for setting the display brightness.
@@ -325,20 +330,64 @@ template <typename Pixel> class Display : public BaseComponent {
    */
   size_t vram_size_bytes() const { return display_buffer_px_size_ * sizeof(Pixel); }
 
+  /**
+   * @brief Set the rotation of the display.
+   * @note This function is called by the event handler when the display
+   *       resolution changes, so that the display hardware can be reconfigured
+   *       to match the new software rotation setting.
+   * @param rotation The new rotation setting for the display.
+   */
+  void set_rotation(DisplayRotation rotation) {
+    if (rotation_callback_ != nullptr) {
+      rotation_callback_(rotation);
+    }
+  }
+
+  /**
+   * @brief Flush the data to the display.
+   * @warning This function is called by the LVGL flush callback, so it is
+   *          recommended to not call this function directly.
+   * @param disp The display to flush data to.
+   * @param area The area of the display to flush data to.
+   * @param color_map The color data to flush to the display.
+   */
+  void flush(lv_display_t *disp, const lv_area_t *area, uint8_t *color_map) {
+    if (flush_callback_ != nullptr) {
+      flush_callback_(disp, area, color_map);
+    }
+  }
+
 protected:
   /**
    * @brief LVGL event handler.
+   * @param event The event to handle.
    */
   static void event_cb(lv_event_t *event) {
     if (lv_event_get_code(event) == LV_EVENT_RESOLUTION_CHANGED) {
-      auto rotation = lv_display_get_rotation(lv_display_get_default());
-      auto rotation_callback = reinterpret_cast<rotation_fn>(lv_event_get_user_data(event));
-      if (rotation_callback != nullptr) {
-        rotation_callback(static_cast<DisplayRotation>(rotation));
+      auto rotation =
+          static_cast<DisplayRotation>(lv_display_get_rotation(lv_display_get_default()));
+      auto display = static_cast<Display *>(lv_display_get_user_data(lv_disp_get_default()));
+      if (display != nullptr) {
+        display->set_rotation(rotation);
       }
     }
   };
 
+  /**
+   * @brief Callback for the LVGL flush function to call when it needs to flush
+   *        data to the display.
+   * @param disp The display to flush data to.
+   * @param area The area of the display to flush data to.
+   * @param color_map The color data to flush to the display.
+   */
+  static void flush_cb(lv_display_t *disp, const lv_area_t *area, uint8_t *color_map) {
+    // use the display to call the registered flush callback appropriately
+    auto display = static_cast<Display *>(lv_display_get_user_data(disp));
+    if (display != nullptr) {
+      display->flush(disp, area, color_map);
+    }
+  }
+
   /**
    * @brief Initialize the lvgl subsystem, display buffer configuration, and
    *        display driver. Start the task to run the high-priority lvgl
@@ -350,19 +399,31 @@ template <typename Pixel> class Display : public BaseComponent {
    */
   void init_gfx(const flush_fn flush_callback, const rotation_fn rotation_callback,
                 DisplayRotation rotation, const Task::BaseConfig &task_config) {
+    // save the callbacks
+    if (flush_callback == nullptr) {
+      logger_.error("No flush callback provided, cannot initialize display!");
+      assert(false); // cannot continue without a flush callback
+    }
+    flush_callback_ = flush_callback;
+    if (rotation_callback == nullptr) {
+      logger_.warn("No rotation callback provided, resolution changed event will not automatically "
+                   "update the display hardware rotation.");
+    }
+    rotation_callback_ = rotation_callback;
+
     lv_init();
 
     display_ = lv_display_create(width_, height_);
+    // store a pointer to this object in the display user data, so that we can
+    // access it in the flush callback
+    lv_display_set_user_data(display_, this);
 
     // Configure the lvgl display buffer with our pixel buffers
     lv_display_set_buffers(display_, vram_0_, vram_1_, vram_size_bytes(),
                            LV_DISPLAY_RENDER_MODE_PARTIAL);
-    lv_display_set_flush_cb(display_, flush_callback);
+    lv_display_set_flush_cb(display_, Display::flush_cb);
 
-    if (rotation_callback != nullptr) {
-      lv_display_add_event_cb(display_, event_cb, LV_EVENT_RESOLUTION_CHANGED,
-                              reinterpret_cast<void *>(rotation_callback));
-    }
+    lv_display_add_event_cb(display_, event_cb, LV_EVENT_RESOLUTION_CHANGED, this);
 
     lv_display_set_rotation(display_, static_cast<lv_display_rotation_t>(rotation));
 
@@ -449,6 +510,8 @@ template <typename Pixel> class Display : public BaseComponent {
   std::unique_ptr<Task> task_;
   size_t width_;
   size_t height_;
+  flush_fn flush_callback_{nullptr};
+  rotation_fn rotation_callback_{nullptr};
   size_t display_buffer_px_size_;
   Pixel *vram_0_{nullptr};
   Pixel *vram_1_{nullptr};