Annotate code with coordinate system information

src/flutter/shell/platform/linux_embedded/flutter_elinux_view.cc

@@ -86,36 +86,37 @@ void FlutterELinuxView::RegisterPlatformViewFactory(
   platform_views_handler_->RegisterViewFactory(view_type, std::move(factory));
 }
 
-void FlutterELinuxView::OnWindowSizeChanged(size_t width, size_t height) const {
-  if (!GetRenderSurfaceTarget()->OnScreenSurfaceResize(width, height)) {
+void FlutterELinuxView::OnWindowSizeChanged(size_t width_px,
+                                            size_t height_px) const {
+  if (!GetRenderSurfaceTarget()->OnScreenSurfaceResize(width_px, height_px)) {
     ELINUX_LOG(ERROR) << "Failed to change surface size.";
     return;
   }
-  SendWindowMetrics(width, height, binding_handler_->GetDpiScale());
+  SendWindowMetrics(width_px, height_px, binding_handler_->GetDpiScale());
 }
 
-void FlutterELinuxView::OnPointerMove(double x, double y) {
-  auto trimmed_xy = GetPointerRotation(x, y);
+void FlutterELinuxView::OnPointerMove(double x_px, double y_px) {
+  auto trimmed_xy = GetPointerRotation(x_px, y_px);
   SendPointerMove(trimmed_xy.first, trimmed_xy.second);
 }
 
 void FlutterELinuxView::OnPointerDown(
-    double x,
-    double y,
+    double x_px,
+    double y_px,
     FlutterPointerMouseButtons flutter_button) {
   if (flutter_button != 0) {
     uint64_t mouse_buttons = mouse_state_.buttons | flutter_button;
-    auto trimmed_xy = GetPointerRotation(x, y);
+    auto trimmed_xy = GetPointerRotation(x_px, y_px);
     SetMouseButtons(mouse_buttons);
     SendPointerDown(trimmed_xy.first, trimmed_xy.second);
   }
 }
 
-void FlutterELinuxView::OnPointerUp(double x,
-                                    double y,
+void FlutterELinuxView::OnPointerUp(double x_px,
+                                    double y_px,
                                     FlutterPointerMouseButtons flutter_button) {
   if (flutter_button != 0) {
-    auto trimmed_xy = GetPointerRotation(x, y);
+    auto trimmed_xy = GetPointerRotation(x_px, y_px);
     uint64_t mouse_buttons = mouse_state_.buttons & ~flutter_button;
     SetMouseButtons(mouse_buttons);
     SendPointerUp(trimmed_xy.first, trimmed_xy.second);
@@ -277,13 +278,13 @@ FlutterELinuxView::touch_point* FlutterELinuxView::GgeTouchPoint(int32_t id) {
 }
 
 // Sends new size  information to FlutterEngine.
-void FlutterELinuxView::SendWindowMetrics(size_t width,
-                                          size_t height,
+void FlutterELinuxView::SendWindowMetrics(size_t width_px,
+                                          size_t height_px,
                                           double dpiScale) const {
   FlutterWindowMetricsEvent event = {};
   event.struct_size = sizeof(event);
-  event.width = width;
-  event.height = height;
+  event.width = width_px;
+  event.height = height_px;
   event.pixel_ratio = dpiScale;
   engine_->SendWindowMetricsEvent(event);
 }
@@ -308,28 +309,28 @@ void FlutterELinuxView::SetEventPhaseFromCursorButtonState(
                                            : FlutterPointerPhase::kDown;
 }
 
-void FlutterELinuxView::SendPointerMove(double x, double y) {
+void FlutterELinuxView::SendPointerMove(double x_px, double y_px) {
   FlutterPointerEvent event = {};
-  event.x = x;
-  event.y = y;
+  event.x = x_px;
+  event.y = y_px;
   SetEventPhaseFromCursorButtonState(&event);
   SendPointerEventWithData(event);
 }
 
-void FlutterELinuxView::SendPointerDown(double x, double y) {
+void FlutterELinuxView::SendPointerDown(double x_px, double y_px) {
   FlutterPointerEvent event = {};
   SetEventPhaseFromCursorButtonState(&event);
-  event.x = x;
-  event.y = y;
+  event.x = x_px;
+  event.y = y_px;
   SendPointerEventWithData(event);
   SetMouseFlutterStateDown(true);
 }
 
-void FlutterELinuxView::SendPointerUp(double x, double y) {
+void FlutterELinuxView::SendPointerUp(double x_px, double y_px) {
   FlutterPointerEvent event = {};
   SetEventPhaseFromCursorButtonState(&event);
-  event.x = x;
-  event.y = y;
+  event.x = x_px;
+  event.y = y_px;
   SendPointerEventWithData(event);
   if (event.phase == FlutterPointerPhase::kUp) {
     SetMouseFlutterStateDown(false);
@@ -468,21 +469,21 @@ FlutterTransformation FlutterELinuxView::GetRootSurfaceTransformation() {
   return view_rotation_transformation_;
 }
 
-std::pair<double, double> FlutterELinuxView::GetPointerRotation(double x,
-                                                                double y) {
+std::pair<double, double> FlutterELinuxView::GetPointerRotation(double x_px,
+                                                                double y_px) {
   auto degree = binding_handler_->GetRotationDegree();
   auto bounds = binding_handler_->GetPhysicalWindowBounds();
-  std::pair<double, double> res = {x, y};
+  std::pair<double, double> res = {x_px, y_px};
 
   if (degree == 90) {
-    res.first = y;
-    res.second = bounds.height - x;
+    res.first = y_px;
+    res.second = bounds.height - x_px;
   } else if (degree == 180) {
-    res.first = bounds.width - x;
-    res.second = bounds.height - y;
+    res.first = bounds.width - x_px;
+    res.second = bounds.height - y_px;
   } else if (degree == 270) {
-    res.first = bounds.width - y;
-    res.second = x;
+    res.first = bounds.width - y_px;
+    res.second = x_px;
   }
   return res;
 }

src/flutter/shell/platform/linux_embedded/flutter_elinux_view.h

@@ -82,19 +82,19 @@ class FlutterELinuxView : public WindowBindingHandlerDelegate {
   void SendInitialBounds();
 
   // |WindowBindingHandlerDelegate|
-  void OnWindowSizeChanged(size_t width, size_t height) const override;
+  void OnWindowSizeChanged(size_t width_px, size_t height_px) const override;
 
   // |WindowBindingHandlerDelegate|
-  void OnPointerMove(double x, double y) override;
+  void OnPointerMove(double x_px, double y_px) override;
 
   // |WindowBindingHandlerDelegate|
-  void OnPointerDown(double x,
-                     double y,
+  void OnPointerDown(double x_px,
+                     double y_px,
                      FlutterPointerMouseButtons button) override;
 
   // |WindowBindingHandlerDelegate|
-  void OnPointerUp(double x,
-                   double y,
+  void OnPointerUp(double x_px,
+                   double y_px,
                    FlutterPointerMouseButtons button) override;
 
   // |WindowBindingHandlerDelegate|
@@ -188,17 +188,27 @@ class FlutterELinuxView : public WindowBindingHandlerDelegate {
   touch_point* GgeTouchPoint(int32_t id);
 
   // Sends a window metrics update to the Flutter engine using current window
-  // dimensions in physical
-  void SendWindowMetrics(size_t width, size_t height, double dpiscale) const;
+  // dimensions in physical pixels.
+  // @param[in] width_px       Physical width of the window.
+  // @param[in] height_px      Physical height of the window.
+  void SendWindowMetrics(size_t width_px,
+                         size_t height_px,
+                         double dpiscale) const;
 
   // Reports a mouse movement to Flutter engine.
-  void SendPointerMove(double x, double y);
+  // @param[in] x_px The x coordinate of the pointer event in physical pixels.
+  // @param[in] y_px The y coordinate of the pointer event in physical pixels.
+  void SendPointerMove(double x_px, double y_px);
 
   // Reports mouse press to Flutter engine.
-  void SendPointerDown(double x, double y);
+  // @param[in] x_px The x coordinate of the pointer event in physical pixels.
+  // @param[in] y_px The y coordinate of the pointer event in physical pixels.
+  void SendPointerDown(double x_px, double y_px);
 
   // Reports mouse release to Flutter engine.
-  void SendPointerUp(double x, double y);
+  // @param[in] x_px The x coordinate of the pointer event in physical pixels.
+  // @param[in] y_px The y coordinate of the pointer event in physical pixels.
+  void SendPointerUp(double x_px, double y_px);
 
   // Reports mouse left the window client area.
   //
@@ -243,7 +253,9 @@ class FlutterELinuxView : public WindowBindingHandlerDelegate {
   void SetMouseButtons(uint64_t buttons) { mouse_state_.buttons = buttons; }
 
   // Returns a trimmed pointer of user inputs with the window rotation.
-  std::pair<double, double> GetPointerRotation(double x, double y);
+  // @param[in] x_px The x coordinate of the pointer event in physical pixels.
+  // @param[in] y_px The y coordinate of the pointer event in physical pixels.
+  std::pair<double, double> GetPointerRotation(double x_px, double y_px);
 
   // The engine associated with this view.
   std::unique_ptr<FlutterELinuxEngine> engine_;

src/flutter/shell/platform/linux_embedded/surface/surface_base.cc

@@ -29,9 +29,9 @@ bool SurfaceBase::SetNativeWindow(NativeWindow* window) {
   return true;
 };
 
-bool SurfaceBase::OnScreenSurfaceResize(const size_t width,
-                                        const size_t height) {
-  if (!native_window_->Resize(width, height)) {
+bool SurfaceBase::OnScreenSurfaceResize(const size_t width_px,
+                                        const size_t height_px) {
+  if (!native_window_->Resize(width_px, height_px)) {
     ELINUX_LOG(ERROR) << "Failed to resize.";
     return false;
   }

src/flutter/shell/platform/linux_embedded/surface/surface_base.h

@@ -28,7 +28,9 @@ class SurfaceBase {
   // On-screen surface needs to be recreated after window size changed only when
   // using DRM-GBM backend. Because gbm-surface is recreated when the window
   // size changed.
-  bool OnScreenSurfaceResize(const size_t width, const size_t height);
+  // @param[in] width_px       Physical width of the surface.
+  // @param[in] height_px      Physical height of the surface.
+  bool OnScreenSurfaceResize(const size_t width_px, const size_t height_px);
 
   // Clears current on-screen context.
   bool ClearCurrentContext() const;

src/flutter/shell/platform/linux_embedded/surface/surface_decoration.cc

@@ -27,8 +27,8 @@ bool SurfaceDecoration::SetNativeWindow(NativeWindow* window) {
   return true;
 };
 
-bool SurfaceDecoration::Resize(const size_t width, const size_t height) {
-  if (!native_window_->Resize(width, height)) {
+bool SurfaceDecoration::Resize(const size_t width_px, const size_t height_px) {
+  if (!native_window_->Resize(width_px, height_px)) {
     ELINUX_LOG(ERROR) << "Failed to resize.";
     return false;
   }

src/flutter/shell/platform/linux_embedded/surface/surface_decoration.h

@@ -26,8 +26,10 @@ class SurfaceDecoration : public SurfaceGlDelegate {
   // Sets a netive platform's window.
   bool SetNativeWindow(NativeWindow* window);
 
-  // Changes an decoration surface size.
-  bool Resize(const size_t width, const size_t height);
+  // Changes a decoration surface size.
+  // @param[in] width_px       Physical width of the surface.
+  // @param[in] height_px      Physical height of the surface.
+  bool Resize(const size_t width_px, const size_t height_px);
 
   // Clears and destroys current decoration context.
   void DestroyContext();

src/flutter/shell/platform/linux_embedded/window/elinux_window.h

@@ -17,8 +17,10 @@ class ELinuxWindow {
  protected:
   virtual bool IsValid() const = 0;
 
+  // Get current window width in physical pixels.
   uint32_t GetCurrentWidth() const { return view_properties_.width; }
 
+  // Get current window height in physical pixels.
   uint32_t GetCurrentHeight() const { return view_properties_.height; }
 
   void SetRotation(FlutterDesktopViewRotation rotation) {
@@ -36,7 +38,9 @@ class ELinuxWindow {
   FlutterDesktopViewProperties view_properties_;
   double current_scale_ = 1.0;
   uint16_t current_rotation_ = 0;
+  // The x coordinate of the pointer in physical pixels.
   double pointer_x_ = 0;
+  // The y coordinate of the pointer in physical pixels.
   double pointer_y_ = 0;
   std::string clipboard_data_ = "";
 };

src/flutter/shell/platform/linux_embedded/window/elinux_window_wayland.cc

@@ -1139,7 +1139,8 @@ bool ELinuxWindowWayland::DispatchEvent() {
   return true;
 }
 
-bool ELinuxWindowWayland::CreateRenderSurface(int32_t width, int32_t height) {
+bool ELinuxWindowWayland::CreateRenderSurface(int32_t width_px,
+                                              int32_t height_px) {
   if (!display_valid_) {
     ELINUX_LOG(ERROR) << "Wayland display is invalid.";
     return false;
@@ -1156,12 +1157,12 @@ bool ELinuxWindowWayland::CreateRenderSurface(int32_t width, int32_t height) {
   }
 
   if (view_properties_.view_mode == FlutterDesktopViewMode::kFullscreen) {
-    width = view_properties_.width;
-    height = view_properties_.height;
+    width_px = view_properties_.width;
+    height_px = view_properties_.height;
   }
 
-  ELINUX_LOG(TRACE) << "Created the Wayland surface: " << width << "x"
-                    << height;
+  ELINUX_LOG(TRACE) << "Created the Wayland surface: " << width_px << "x"
+                    << height_px;
   if (view_properties_.use_mouse_cursor) {
     wl_cursor_surface_ = wl_compositor_create_surface(wl_compositor_);
     if (!wl_cursor_surface_) {
@@ -1172,10 +1173,10 @@ bool ELinuxWindowWayland::CreateRenderSurface(int32_t width, int32_t height) {
   }
 
   if (current_rotation_ == 90 || current_rotation_ == 270) {
-    std::swap(width, height);
+    std::swap(width_px, height_px);
   }
-  native_window_ =
-      std::make_unique<NativeWindowWayland>(wl_compositor_, width, height);
+  native_window_ = std::make_unique<NativeWindowWayland>(wl_compositor_,
+                                                         width_px, height_px);
 
   wl_surface_add_listener(native_window_->Surface(), &kWlSurfaceListener, this);
 
@@ -1211,7 +1212,7 @@ bool ELinuxWindowWayland::CreateRenderSurface(int32_t width, int32_t height) {
   if (view_properties_.use_window_decoration) {
     window_decorations_ = std::make_unique<WindowDecorationsWayland>(
         wl_display_, wl_compositor_, wl_subcompositor_,
-        native_window_->Surface(), width, height);
+        native_window_->Surface(), width_px, height_px);
   }
 
   return true;

src/flutter/shell/platform/linux_embedded/window/elinux_window_wayland.h

@@ -45,7 +45,7 @@ class ELinuxWindowWayland : public ELinuxWindow, public WindowBindingHandler {
   bool DispatchEvent() override;
 
   // |FlutterWindowBindingHandler|
-  bool CreateRenderSurface(int32_t width, int32_t height) override;
+  bool CreateRenderSurface(int32_t width_px, int32_t height_px) override;
 
   // |FlutterWindowBindingHandler|
   void DestroyRenderSurface() override;

src/flutter/shell/platform/linux_embedded/window/native_window.h

@@ -21,13 +21,15 @@ class NativeWindow {
   // Gets a window (GBM surface) for offscreen resource.
   EGLNativeWindowType WindowOffscreen() const { return window_offscreen_; }
 
+  // Get physical width of the window.
   int32_t Width() const {
     if (!valid_) {
       return -1;
     }
     return width_;
   }
 
+  // Get physical height of the window.
   int32_t Height() const {
     if (!valid_) {
       return -1;
@@ -39,12 +41,16 @@ class NativeWindow {
 
   // Sets a window position. Basically, this API is used for window decorations
   // such as titlebar.
-  virtual void SetPosition(const int32_t x, const int32_t y) {
-    x_ = x;
-    y_ = y;
+  // @param[in] x_dip   The x coordinate in logical pixels.
+  // @param[in] y_dip   The y coordinate in logical pixels.
+  virtual void SetPosition(const int32_t x_dip, const int32_t y_dip) {
+    x_ = x_dip;
+    y_ = y_dip;
   };
 
-  virtual bool Resize(const size_t width, const size_t height) = 0;
+  // @param[in] width_px       Physical width of the window.
+  // @param[in] height_px      Physical height of the window.
+  virtual bool Resize(const size_t width_px, const size_t height_px) = 0;
 
   // Swaps frame buffers. This API performs processing only for the DRM-GBM
   // backend. It is prepared to make the interface common.
@@ -53,9 +59,13 @@ class NativeWindow {
  protected:
   EGLNativeWindowType window_;
   EGLNativeWindowType window_offscreen_;
+  // Physical width of the window.
   int32_t width_;
+  // Physical height of the window.
   int32_t height_;
+  // The x coordinate of the window in logical pixels.
   int32_t x_;
+  // The y coordinate of the window in logical pixels.
   int32_t y_;
   bool valid_ = false;
 };