feat: add relative mouse movement

Author: developer239

include/robot/Mouse.h

@@ -46,6 +46,11 @@ class Mouse {
       LogicalPoint point, const MouseMoveOptions& options = {}
   );
 
+  // Relative motion for software that captures the cursor, such as game cameras
+  // and mouse steering. Units are logical on macOS and raw device counts
+  // elsewhere, where the OS pointer speed may also apply.
+  [[nodiscard]] std::expected<void, Error> moveBy(double deltaX, double deltaY);
+
   [[nodiscard]] std::expected<LogicalPoint, Error> position();
 
   [[nodiscard]] std::expected<void, Error> press(MouseButton button);

include/robot/backend/IMouseBackend.h

@@ -30,6 +30,13 @@ class IMouseBackend {
       LogicalPoint point
   ) = 0;
 
+  // Relative motion, reported to the OS as a raw delta. This is what software
+  // that captures the cursor (game cameras, mouse steering) reads; an absolute
+  // warp does not produce usable deltas there.
+  [[nodiscard]] virtual std::expected<void, Error> moveRelative(
+      double deltaX, double deltaY
+  ) = 0;
+
   // Current pointer position. ErrorCode::Unsupported where it cannot be read.
   [[nodiscard]] virtual std::expected<LogicalPoint, Error> cursorPosition() = 0;
 

src/common/Mouse.cpp

@@ -28,6 +28,12 @@ std::expected<void, Error> Mouse::move(const LogicalPoint point) {
   return backend_->warpCursor(point);
 }
 
+std::expected<void, Error> Mouse::moveBy(
+    const double deltaX, const double deltaY
+) {
+  return backend_->moveRelative(deltaX, deltaY);
+}
+
 std::expected<void, Error> Mouse::moveSmooth(
     const LogicalPoint point, const MouseMoveOptions& options
 ) {

src/platform/linux/UinputBackend.cpp

@@ -123,6 +123,17 @@ std::expected<void, Error> UinputBackend::warpCursor(LogicalPoint /*point*/) {
   ));
 }
 
+std::expected<void, Error> UinputBackend::moveRelative(
+    const double deltaX, const double deltaY
+) {
+  const auto dx = static_cast<std::int32_t>(std::lround(deltaX));
+  const auto dy = static_cast<std::int32_t>(std::lround(deltaY));
+
+  if (auto r = writeEvent(fd_, EV_REL, REL_X, dx); !r) return r;
+  if (auto r = writeEvent(fd_, EV_REL, REL_Y, dy); !r) return r;
+  return writeEvent(fd_, EV_SYN, SYN_REPORT, 0);
+}
+
 std::expected<LogicalPoint, Error> UinputBackend::cursorPosition() {
   return std::unexpected(Error::unsupported(
       "reading the global pointer position is unavailable through uinput"

src/platform/linux/UinputBackend.h

@@ -42,6 +42,9 @@ class UinputBackend final : public backend::IKeyboardBackend,
 
   // Mouse.
   std::expected<void, Error> warpCursor(LogicalPoint point) override;
+  std::expected<void, Error> moveRelative(
+      double deltaX, double deltaY
+  ) override;
   std::expected<LogicalPoint, Error> cursorPosition() override;
   std::expected<void, Error> button(
       MouseButton button, ButtonAction action, int clickCount

src/platform/linux/X11MouseBackend.cpp

@@ -33,6 +33,17 @@ std::expected<void, Error> X11MouseBackend::warpCursor(const LogicalPoint point)
   return {};
 }
 
+std::expected<void, Error> X11MouseBackend::moveRelative(
+    const double deltaX, const double deltaY
+) {
+  XTestFakeRelativeMotionEvent(
+      connection_->display(), static_cast<int>(std::lround(deltaX)),
+      static_cast<int>(std::lround(deltaY)), CurrentTime
+  );
+  XFlush(connection_->display());
+  return {};
+}
+
 std::expected<LogicalPoint, Error> X11MouseBackend::cursorPosition() {
   Window rootReturn = 0;
   Window childReturn = 0;

src/platform/linux/X11MouseBackend.h

@@ -16,6 +16,9 @@ class X11MouseBackend final : public backend::IMouseBackend {
       : connection_(&connection) {}
 
   std::expected<void, Error> warpCursor(LogicalPoint point) override;
+  std::expected<void, Error> moveRelative(
+      double deltaX, double deltaY
+  ) override;
   std::expected<LogicalPoint, Error> cursorPosition() override;
   std::expected<void, Error> button(
       MouseButton button, ButtonAction action, int clickCount

src/platform/macos/MacMouseBackend.cpp

@@ -74,6 +74,35 @@ std::expected<void, Error> MacMouseBackend::warpCursor(const LogicalPoint point)
   return {};
 }
 
+std::expected<void, Error> MacMouseBackend::moveRelative(
+    const double deltaX, const double deltaY
+) {
+  auto here = cursorPosition();
+  if (!here) return std::unexpected(here.error());
+
+  const CGPoint target = CGPointMake(here->x + deltaX, here->y + deltaY);
+  const CGEventType type =
+      pressedButton_ ? dragType(*pressedButton_) : kCGEventMouseMoved;
+  const CGMouseButton btn =
+      pressedButton_ ? cgButton(*pressedButton_) : kCGMouseButtonLeft;
+
+  CGEventRef event = CGEventCreateMouseEvent(source_, type, target, btn);
+  if (event == nullptr) {
+    return std::unexpected(Error::platformError("CGEventCreateMouseEvent"));
+  }
+
+  // Applications that captured the cursor read these fields, not the location.
+  CGEventSetIntegerValueField(
+      event, kCGMouseEventDeltaX, static_cast<int64_t>(std::lround(deltaX))
+  );
+  CGEventSetIntegerValueField(
+      event, kCGMouseEventDeltaY, static_cast<int64_t>(std::lround(deltaY))
+  );
+  CGEventPost(kCGHIDEventTap, event);
+  CFRelease(event);
+  return {};
+}
+
 std::expected<LogicalPoint, Error> MacMouseBackend::cursorPosition() {
   CGEventRef event = CGEventCreate(nullptr);
   if (event == nullptr) {

src/platform/macos/MacMouseBackend.h

@@ -21,6 +21,9 @@ class MacMouseBackend final : public backend::IMouseBackend {
   MacMouseBackend& operator=(const MacMouseBackend&) = delete;
 
   std::expected<void, Error> warpCursor(LogicalPoint point) override;
+  std::expected<void, Error> moveRelative(
+      double deltaX, double deltaY
+  ) override;
   std::expected<LogicalPoint, Error> cursorPosition() override;
   std::expected<void, Error> button(
       MouseButton button, ButtonAction action, int clickCount

src/platform/windows/WinMouseBackend.cpp

@@ -138,6 +138,17 @@ std::expected<void, Error> WinMouseBackend::warpCursor(const LogicalPoint point)
   return send(input);
 }
 
+std::expected<void, Error> WinMouseBackend::moveRelative(
+    const double deltaX, const double deltaY
+) {
+  INPUT input{};
+  input.type = INPUT_MOUSE;
+  input.mi.dx = static_cast<LONG>(std::lround(deltaX));
+  input.mi.dy = static_cast<LONG>(std::lround(deltaY));
+  input.mi.dwFlags = MOUSEEVENTF_MOVE;
+  return send(input);
+}
+
 std::expected<LogicalPoint, Error> WinMouseBackend::cursorPosition() {
   POINT p{};
   if (GetCursorPos(&p) == 0) {