feat(controller): 添加获取真实分辨率接口 MaaControllerGetResolution (#1040)

MistEO · MistEO · commit 7fae994a819a · 2026-01-13T01:19:41.000+08:00
fix #1024
diff --git a/docs/en_us/2.2-IntegratedInterfaceOverview.md b/docs/en_us/2.2-IntegratedInterfaceOverview.md
@@ -416,6 +416,11 @@ Asynchronously scroll. This is an asynchronous operation that immediately return
 
 Asynchronously screenshot. This is an asynchronous operation that immediately returns an operation id. You can query the status via `MaaControllerStatus` and `MaaControllerWait`, and get the screenshot via `MaaControllerCachedImage`.
 
+> [!NOTE]
+>
+> The screenshot is scaled according to the screenshot target size settings (long side / short side). The resulting image dimensions may differ from the raw device resolution.
+> Use `MaaControllerGetResolution` to get the raw (unscaled) device resolution.
+
 ### MaaControllerPostShell
 
 - `cmd`: Shell command to execute
@@ -446,6 +451,24 @@ Check if connected.
 
 Get the latest screenshot, write to `buffer`.
 
+> [!NOTE]
+>
+> The returned image is scaled according to the screenshot target size settings (long side / short side). The image dimensions may differ from the raw device resolution.
+> Use `MaaControllerGetResolution` to get the raw (unscaled) device resolution.
+
+### MaaControllerGetResolution
+
+- `width [out]`: Output raw width
+- `height [out]`: Output raw height
+
+Get the raw (unscaled) device resolution.
+
+> [!NOTE]
+>
+> This returns the actual device screen resolution before any scaling.
+> The screenshot obtained via `MaaControllerCachedImage` is scaled according to the screenshot target size settings, so its dimensions may differ from this raw resolution.
+> Valid values are only available after the first screenshot is taken.
+
 ### MaaControllerGetShellOutput
 
 - `buffer [out]`: Output buffer
diff --git a/docs/zh_cn/2.2-集成接口一览.md b/docs/zh_cn/2.2-集成接口一览.md
@@ -416,6 +416,11 @@
 
 异步截图。这是一个异步操作，会立即返回一个操作 id，可通过 `MaaControllerStatus` 和 `MaaControllerWait` 查询状态，通过 `MaaControllerCachedImage` 获取截图。
 
+> [!NOTE]
+>
+> 截图会根据截图目标尺寸设置（长边/短边）进行缩放，获取到的图像尺寸可能与设备原始分辨率不同。
+> 使用 `MaaControllerGetResolution` 可获取设备的原始（未缩放）分辨率。
+
 ### MaaControllerPostShell
 
 - `cmd`: 要执行的 shell 命令
@@ -446,6 +451,24 @@
 
 获取最新一次截图，写入到 `buffer`
 
+> [!NOTE]
+>
+> 返回的图像是经过缩放的，尺寸根据截图目标尺寸设置（长边/短边）而定，可能与设备原始分辨率不同。
+> 使用 `MaaControllerGetResolution` 可获取设备的原始（未缩放）分辨率。
+
+### MaaControllerGetResolution
+
+- `width [out]`: 输出原始宽度
+- `height [out]`: 输出原始高度
+
+获取设备的原始（未缩放）分辨率。
+
+> [!NOTE]
+>
+> 返回的是设备屏幕的实际分辨率，未经任何缩放处理。
+> 而通过 `MaaControllerCachedImage` 获取的截图是经过缩放的，其尺寸可能与此原始分辨率不同。
+> 需要在首次截图后才能获取到有效值。
+
 ### MaaControllerGetShellOutput
 
 - `buffer [out]`: 输出缓冲区
diff --git a/include/MaaFramework/Instance/MaaController.h b/include/MaaFramework/Instance/MaaController.h
@@ -99,6 +99,16 @@ extern "C"
 
     MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostKeyUp(MaaController* ctrl, int32_t keycode);
 
+    /**
+     * @brief Post a screenshot request to the controller.
+     *
+     * @param ctrl The controller handle.
+     * @return The control id of the screenshot action.
+     *
+     * @note The screenshot image is scaled according to the screenshot target size settings (long side / short side).
+     *       Use MaaControllerGetResolution to get the raw (unscaled) device resolution.
+     * @see MaaControllerCachedImage, MaaControllerSetOption, MaaControllerGetResolution
+     */
     MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostScreencap(MaaController* ctrl);
 
     /**
@@ -145,10 +155,37 @@ extern "C"
 
     MAA_FRAMEWORK_API MaaBool MaaControllerConnected(const MaaController* ctrl);
 
+    /**
+     * @brief Get the cached screenshot image.
+     *
+     * @param ctrl The controller handle.
+     * @param buffer The output buffer to store the screenshot image.
+     * @return true if the screenshot is available, false otherwise.
+     *
+     * @note The returned image is scaled according to the screenshot target size settings (long side / short side).
+     *       The image dimensions may differ from the raw device resolution.
+     *       Use MaaControllerGetResolution to get the raw (unscaled) device resolution.
+     * @see MaaControllerPostScreencap, MaaControllerSetOption, MaaControllerGetResolution
+     */
     MAA_FRAMEWORK_API MaaBool MaaControllerCachedImage(const MaaController* ctrl, /* out */ MaaImageBuffer* buffer);
 
     MAA_FRAMEWORK_API MaaBool MaaControllerGetUuid(MaaController* ctrl, /* out */ MaaStringBuffer* buffer);
 
+    /**
+     * @brief Get the raw (unscaled) device resolution.
+     *
+     * @param ctrl The controller handle.
+     * @param[out] width Output parameter for the raw width.
+     * @param[out] height Output parameter for the raw height.
+     * @return true if the resolution is available, false otherwise (e.g., not connected or no screenshot taken yet).
+     *
+     * @note This returns the actual device screen resolution before any scaling.
+     *       The screenshot obtained via MaaControllerCachedImage is scaled according to the screenshot target size settings,
+     *       so its dimensions may differ from this raw resolution.
+     * @see MaaControllerCachedImage, MaaControllerPostScreencap
+     */
+    MAA_FRAMEWORK_API MaaBool MaaControllerGetResolution(const MaaController* ctrl, /* out */ int32_t* width, /* out */ int32_t* height);
+
     MAA_DEPRECATED MAA_FRAMEWORK_API MaaCtrlId MaaControllerPostPressKey(MaaController* ctrl, int32_t keycode);
 
 #ifdef __cplusplus
diff --git a/source/Common/MaaController.cpp b/source/Common/MaaController.cpp
@@ -344,3 +344,13 @@ MaaBool MaaControllerGetUuid(MaaController* ctrl, MaaStringBuffer* buffer)
     buffer->set(std::move(uuid));
     return true;
 }
+
+MaaBool MaaControllerGetResolution(const MaaController* ctrl, int32_t* width, int32_t* height)
+{
+    if (!ctrl || !width || !height) {
+        LogError << "handle or output params are null";
+        return false;
+    }
+
+    return ctrl->get_resolution(*width, *height);
+}
diff --git a/source/MaaAgentClient/Client/AgentClient.cpp b/source/MaaAgentClient/Client/AgentClient.cpp
@@ -426,6 +426,9 @@ bool AgentClient::handle_inserted_request(const json::value& j)
     else if (handle_controller_get_uuid(j)) {
         return true;
     }
+    else if (handle_controller_get_resolution(j)) {
+        return true;
+    }
     else if (handle_event_response(j)) {
         return true;
     }
@@ -2082,6 +2085,30 @@ bool AgentClient::handle_controller_get_uuid(const json::value& j)
     return true;
 }
 
+bool AgentClient::handle_controller_get_resolution(const json::value& j)
+{
+    if (!j.is<ControllerGetResolutionReverseRequest>()) {
+        return false;
+    }
+    const ControllerGetResolutionReverseRequest& req = j.as<ControllerGetResolutionReverseRequest>();
+    LogFunc << VAR(req) << VAR(ipc_addr_);
+    MaaController* controller = query_controller(req.controller_id);
+    if (!controller) {
+        LogError << "controller not found" << VAR(req.controller_id);
+        return false;
+    }
+    int32_t width = 0;
+    int32_t height = 0;
+    bool success = controller->get_resolution(width, height);
+    ControllerGetResolutionReverseResponse resp {
+        .success = success,
+        .width = width,
+        .height = height,
+    };
+    send(resp);
+    return true;
+}
+
 // FIXME: 不应该存在这个函数
 // 等 send_and_recv 支持在子线程中使用后，应该删除这个函数
 bool AgentClient::handle_event_response(const json::value& j)
diff --git a/source/MaaAgentClient/Client/AgentClient.h b/source/MaaAgentClient/Client/AgentClient.h
@@ -111,6 +111,7 @@ class AgentClient
     bool handle_controller_cached_image(const json::value& j);
     bool handle_controller_get_shell_output(const json::value& j);
     bool handle_controller_get_uuid(const json::value& j);
+    bool handle_controller_get_resolution(const json::value& j);
 
     bool handle_event_response(const json::value& j);
 
diff --git a/source/MaaAgentServer/RemoteInstance/RemoteController.cpp b/source/MaaAgentServer/RemoteInstance/RemoteController.cpp
@@ -311,6 +311,21 @@ std::string RemoteController::get_uuid()
     return resp_opt->uuid;
 }
 
+bool RemoteController::get_resolution(int32_t& width, int32_t& height) const
+{
+    ControllerGetResolutionReverseRequest req {
+        .controller_id = controller_id_,
+    };
+
+    auto resp_opt = server_.send_and_recv<ControllerGetResolutionReverseResponse>(req);
+    if (!resp_opt) {
+        return false;
+    }
+    width = resp_opt->width;
+    height = resp_opt->height;
+    return resp_opt->success;
+}
+
 MaaSinkId RemoteController::add_sink(MaaEventCallback callback, void* trans_arg)
 {
     LogError << "Can NOT add sink for remote instance, use AgentServer.add_controller_sink instead" << VAR_VOIDP(callback)
diff --git a/source/MaaAgentServer/RemoteInstance/RemoteController.h b/source/MaaAgentServer/RemoteInstance/RemoteController.h
@@ -44,6 +44,8 @@ class RemoteController : public MaaController
     virtual std::string cached_shell_output() const override;
     virtual std::string get_uuid() override;
 
+    virtual bool get_resolution(int32_t& width, int32_t& height) const override;
+
     virtual MaaSinkId add_sink(MaaEventCallback callback, void* trans_arg) override;
     virtual void remove_sink(MaaSinkId sink_id) override;
     virtual void clear_sinks() override;
diff --git a/source/MaaFramework/Controller/ControllerAgent.cpp b/source/MaaFramework/Controller/ControllerAgent.cpp
@@ -206,6 +206,17 @@ std::string ControllerAgent::get_uuid()
     return uuid_cache_;
 }
 
+bool ControllerAgent::get_resolution(int32_t& width, int32_t& height) const
+{
+    if (image_raw_width_ == 0 || image_raw_height_ == 0) {
+        return false;
+    }
+
+    width = image_raw_width_;
+    height = image_raw_height_;
+    return true;
+}
+
 MaaSinkId ControllerAgent::add_sink(MaaEventCallback callback, void* trans_arg)
 {
     return notifier_.add_sink(callback, trans_arg);
diff --git a/source/MaaFramework/Controller/ControllerAgent.h b/source/MaaFramework/Controller/ControllerAgent.h
@@ -191,6 +191,8 @@ class ControllerAgent : public MaaController
     virtual std::string cached_shell_output() const override;
     virtual std::string get_uuid() override;
 
+    virtual bool get_resolution(int32_t& width, int32_t& height) const override;
+
     virtual MaaSinkId add_sink(MaaEventCallback callback, void* trans_arg) override;
     virtual void remove_sink(MaaSinkId sink_id) override;
     virtual void clear_sinks() override;
diff --git a/source/binding/NodeJS/src/apis/controller.cpp b/source/binding/NodeJS/src/apis/controller.cpp
@@ -242,6 +242,16 @@ std::optional<std::string> ControllerImpl::get_uuid()
     return buf.str();
 }
 
+std::optional<std::tuple<int32_t, int32_t>> ControllerImpl::get_resolution()
+{
+    int32_t width = 0;
+    int32_t height = 0;
+    if (!MaaControllerGetResolution(controller, &width, &height)) {
+        return std::nullopt;
+    }
+    return std::make_tuple(width, height);
+}
+
 std::string ControllerImpl::to_string()
 {
     return std::format(" handle = {:#018x}, {} ", reinterpret_cast<uintptr_t>(controller), own ? "owned" : "rented");
@@ -311,6 +321,7 @@ void ControllerImpl::init_proto(maajs::ObjectType proto, maajs::FunctionType)
     MAA_BIND_GETTER(proto, "connected", ControllerImpl::get_connected);
     MAA_BIND_GETTER(proto, "cached_image", ControllerImpl::get_cached_image);
     MAA_BIND_GETTER(proto, "uuid", ControllerImpl::get_uuid);
+    MAA_BIND_GETTER(proto, "resolution", ControllerImpl::get_resolution);
 }
 
 maajs::ValueType load_controller(maajs::EnvType env)
diff --git a/source/binding/NodeJS/src/apis/controller.h b/source/binding/NodeJS/src/apis/controller.h
@@ -56,6 +56,7 @@ struct ControllerImpl : public maajs::NativeClassBase
     bool get_connected();
     std::optional<maajs::ArrayBufferType> get_cached_image();
     std::optional<std::string> get_uuid();
+    std::optional<std::tuple<int32_t, int32_t>> get_resolution();
 
     std::string to_string() override;
 
diff --git a/source/binding/Python/maa/controller.py b/source/binding/Python/maa/controller.py
@@ -3,7 +3,7 @@
 from ctypes import c_int32
 import os
 from pathlib import Path
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, Optional, Tuple, Union
 
 from .buffer import ImageBuffer, StringBuffer
 from .event_sink import EventSink, NotificationType
@@ -261,6 +261,14 @@ def cached_image(self) -> numpy.ndarray:
 
         Raises:
             RuntimeError: 如果获取失败
+
+        Note:
+            返回的图像是经过缩放的，尺寸根据截图目标尺寸设置（长边/短边）而定，可能与设备原始分辨率不同。
+            使用 resolution 属性可获取设备的原始（未缩放）分辨率。
+
+            The returned image is scaled according to the screenshot target size settings (long side / short side).
+            The image dimensions may differ from the raw device resolution.
+            Use the resolution property to get the raw (unscaled) device resolution.
         """
         image_buffer = ImageBuffer()
         if not Library.framework().MaaControllerCachedImage(
@@ -330,6 +338,31 @@ def uuid(self) -> str:
             raise RuntimeError("Failed to get UUID.")
         return buffer.get()
 
+    @property
+    def resolution(self) -> Tuple[int, int]:
+        """获取设备原始（未缩放）分辨率 / Get the raw (unscaled) device resolution
+
+        Returns:
+            Tuple[int, int]: (宽度, 高度)，获取失败时返回 (0, 0) / (width, height), returns (0, 0) on failure
+
+        Note:
+            返回的是设备屏幕的实际分辨率，未经任何缩放处理。
+            而通过 cached_image 获取的截图是经过缩放的，其尺寸可能与此原始分辨率不同。
+            需要在首次截图后才能获取到有效值，否则返回 (0, 0)。
+
+            This returns the actual device screen resolution before any scaling.
+            The screenshot obtained via cached_image is scaled according to the screenshot target size settings,
+            so its dimensions may differ from this raw resolution.
+            Valid values are only available after the first screenshot is taken, otherwise returns (0, 0).
+        """
+        width = ctypes.c_int32()
+        height = ctypes.c_int32()
+        if not Library.framework().MaaControllerGetResolution(
+            self._handle, ctypes.byref(width), ctypes.byref(height)
+        ):
+            return (0, 0)
+        return (width.value, height.value)
+
     def set_screenshot_target_long_side(self, long_side: int) -> bool:
         """设置截图缩放长边到指定长度 / Set screenshot scaling long side to specified length
 
@@ -582,6 +615,13 @@ def _set_api_properties():
             MaaStringBufferHandle,
         ]
 
+        Library.framework().MaaControllerGetResolution.restype = MaaBool
+        Library.framework().MaaControllerGetResolution.argtypes = [
+            MaaControllerHandle,
+            ctypes.POINTER(ctypes.c_int32),
+            ctypes.POINTER(ctypes.c_int32),
+        ]
+
         Library.framework().MaaControllerAddSink.restype = MaaSinkId
         Library.framework().MaaControllerAddSink.argtypes = [
             MaaControllerHandle,
diff --git a/source/include/Common/MaaTypes.h b/source/include/Common/MaaTypes.h
@@ -101,6 +101,8 @@ struct MaaController : public IMaaEventDispatcher
     virtual cv::Mat cached_image() const = 0;
     virtual std::string cached_shell_output() const = 0;
     virtual std::string get_uuid() = 0;
+
+    virtual bool get_resolution(int32_t& width, int32_t& height) const = 0;
 };
 
 struct MaaTasker : public IMaaEventDispatcher
diff --git a/source/include/MaaAgent/Message.hpp b/source/include/MaaAgent/Message.hpp
@@ -1383,6 +1383,24 @@ struct ControllerGetUuidReverseResponse
     MEO_JSONIZATION(uuid, _ControllerGetUuidReverseResponse);
 };
 
+struct ControllerGetResolutionReverseRequest
+{
+    std::string controller_id;
+
+    MessageTypePlaceholder _ControllerGetResolutionReverseRequest = 1;
+    MEO_JSONIZATION(controller_id, _ControllerGetResolutionReverseRequest);
+};
+
+struct ControllerGetResolutionReverseResponse
+{
+    bool success = false;
+    int32_t width = 0;
+    int32_t height = 0;
+
+    MessageTypePlaceholder _ControllerGetResolutionReverseResponse = 1;
+    MEO_JSONIZATION(success, width, height, _ControllerGetResolutionReverseResponse);
+};
+
 struct ImageHeader
 {
     std::string uuid;
diff --git a/source/modules/MaaFramework.cppm b/source/modules/MaaFramework.cppm
@@ -136,6 +136,7 @@ export using ::MaaControllerWait;
 export using ::MaaControllerConnected;
 export using ::MaaControllerCachedImage;
 export using ::MaaControllerGetUuid;
+export using ::MaaControllerGetResolution;
 
 // Instance/MaaCustomController.h
 
