Expose custom overlay painting to tasks

Author: ok-oldking

docs/api_doc/README.md

@@ -777,9 +777,45 @@ def clear_box(self)
 def get_overlay_view(self)
 ```
 
-返回覆盖在捕获窗口上的 Qt overlay widget。`BaseTask` 和 `CustomTab` 可直接调用此方法；配置的
-`my_app` 实例也会获得同名方法。无界面运行时返回 `None`。自定义内容绘制完成后可调用
-`overlay_view.request_show()` 令 overlay 在窗口上显示。
+返回覆盖在捕获窗口上的原始 Qt overlay widget。`BaseTask` 和 `CustomTab` 可直接调用此方法；
+配置的 `my_app` 实例也会获得同名方法。无界面运行时返回 `None`。
+
+任务线程需要通过 `overlay_view.draw(key, callback, duration=None)` 注册自定义绘制。回调会在
+Qt 绘制线程中执行，参数为 `(painter, overlay_view)`，可使用 `QPainter` 绘制任意内容。存在
+自定义绘制内容时 overlay 会自动显示，不受 `Enable Boxes` 开关影响。`duration` 为秒数；不传
+时持续显示，直到调用 `overlay_view.clear_draw(key)` 或 `overlay_view.clear_draw()`：
+
+```python
+from PySide6.QtGui import QColor, QFont, QPen
+from ok import TriggerTask
+
+
+class StatusOverlayTask(TriggerTask):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.default_config = {'_enabled': True}
+        self.trigger_interval = 0.5
+
+    def run(self):
+        overlay = self.get_overlay_view()
+        if overlay is None:
+            return
+
+        status = "Tracking"
+
+        def paint(painter, view):
+            painter.setPen(QPen(QColor(0, 255, 120), 2))
+            painter.drawRect(30, 30, 240, 64)
+            painter.setFont(QFont("Arial", 16))
+            painter.drawText(48, 70, status)
+
+        overlay.draw("status", paint, duration=1)
+
+    def on_destroy(self):
+        overlay = self.get_overlay_view()
+        if overlay is not None:
+            overlay.clear_draw("status")
+```
 
 应用配置可提供 `blur_area(width, height)` 回调，返回一个 `Box` 或 `list[Box]`，用于遮挡
 游戏 UID 等静态区域：

ok/gui/debug/OverlayWidget.py

@@ -170,6 +170,7 @@ def paintEvent(self, event):
             self.paint_alt_overlay(painter)
             if og.config.get('debug_cover_uid'):
                 self.paint_uid_cover(painter)
+        self.paint_custom(painter)
 
     def set_blur_patches(self, patches):
         images = []
@@ -197,6 +198,16 @@ def paint_blur(self, painter):
             painter.drawImage(QRectF(x * frame_ratio, y * frame_ratio,
                                      width * frame_ratio, height * frame_ratio), image)
 
+    def paint_custom(self, painter):
+        for key, callback in list(getattr(self, 'custom_painters', {}).items()):
+            painter.save()
+            try:
+                callback(painter, self)
+            except Exception as e:
+                logger.warning(f'custom overlay painter {key} failed: {e}')
+            finally:
+                painter.restore()
+
     def paint_alt_overlay(self, painter):
         if not getattr(self, '_is_alt_down', False):
             return

ok/gui/overlay/OverlayWindow.py

@@ -16,6 +16,9 @@ class Communicate(QObject):
 
 
 class OverlayWindow(OverlayWidget):
+    custom_draw_requested = Signal(str, object, object)
+    custom_clear_requested = Signal(object)
+
     def __init__(self, hwnd_window: HwndWindow):
         super().__init__()
         self._source_visible = False
@@ -27,6 +30,8 @@ def __init__(self, hwnd_window: HwndWindow):
         self._boxes_until = 0
         self._custom_drawing_active = False
         self._custom_drawing_until = 0
+        self.custom_painters = {}
+        self._custom_painter_until = {}
         # Set translucent background
         self.setAttribute(Qt.WA_TranslucentBackground)
 
@@ -39,6 +44,8 @@ def __init__(self, hwnd_window: HwndWindow):
         communicate.clear_box.connect(self.clear_drawing)
         communicate.blur_overlay.connect(self.update_blur_patches)
         communicate.clear_blur_overlay.connect(self.clear_blur_overlay)
+        self.custom_draw_requested.connect(self._set_custom_draw, Qt.QueuedConnection)
+        self.custom_clear_requested.connect(self._clear_custom_draw, Qt.QueuedConnection)
 
         # self.update_overlay(hwnd_window.visible, hwnd_window.x, hwnd_window.y, hwnd_window.window_width,
         #                     hwnd_window.window_height, hwnd_window.width, hwnd_window.height, hwnd_window.scaling)
@@ -65,6 +72,46 @@ def request_show(self, duration=4.0):
         self.update()
         QTimer.singleShot(int(duration * 1000) + 10, self.expire_custom_drawing)
 
+    def draw(self, key, callback, duration=None):
+        """Schedule arbitrary painting with callback(QPainter, OverlayWindow)."""
+        if not callable(callback):
+            raise TypeError('callback must be callable')
+        self.custom_draw_requested.emit(str(key), callback, duration)
+
+    def clear_draw(self, key=None):
+        """Remove one custom painter, or all painters when key is None."""
+        self.custom_clear_requested.emit(key)
+
+    def _set_custom_draw(self, key, callback, duration):
+        self.custom_painters[key] = callback
+        if duration is None:
+            self._custom_painter_until.pop(key, None)
+        else:
+            duration = max(0.0, float(duration))
+            self._custom_painter_until[key] = time.monotonic() + duration
+            QTimer.singleShot(int(duration * 1000) + 10, lambda: self._expire_custom_draw(key))
+        self.refresh_visibility()
+        self.update()
+
+    def _clear_custom_draw(self, key):
+        if key is None:
+            self.custom_painters.clear()
+            self._custom_painter_until.clear()
+        else:
+            key = str(key)
+            self.custom_painters.pop(key, None)
+            self._custom_painter_until.pop(key, None)
+        self.refresh_visibility()
+        self.update()
+
+    def _expire_custom_draw(self, key):
+        until = self._custom_painter_until.get(key)
+        if until is not None and time.monotonic() >= until:
+            self.custom_painters.pop(key, None)
+            self._custom_painter_until.pop(key, None)
+            self.refresh_visibility()
+            self.update()
+
     def on_draw_box(self, key, boxes, color, frame, debug):
         if boxes and self._boxes_enabled:
             self._boxes_active = True
@@ -100,7 +147,8 @@ def clear_blur_overlay(self):
         self.refresh_visibility()
 
     def refresh_visibility(self):
-        required = self._boxes_active or self._custom_drawing_active or bool(self.blur_images)
+        required = (self._boxes_active or self._custom_drawing_active
+                    or bool(self.blur_images) or bool(self.custom_painters))
         if self._source_visible and required and not self.isVisible():
             self.show()
             return

ok/task/task.py

@@ -118,7 +118,7 @@ def start_device(self):
         self._app.start_controller.start_device()
 
     def get_overlay_view(self):
-        """Return the shared overlay widget when running with the GUI."""
+        """Return the raw shared overlay widget when running with the GUI."""
         if hasattr(self._app, 'get_overlay_view'):
             return self._app.get_overlay_view()
         return None

tests/test_overlay_custom_draw.py

@@ -0,0 +1,65 @@
+import os
+import threading
+import unittest
+from types import SimpleNamespace
+
+os.environ.setdefault('QT_QPA_PLATFORM', 'offscreen')
+
+from PySide6.QtGui import QColor, QPen
+from PySide6.QtWidgets import QApplication
+
+from ok import og
+from ok.gui.overlay.OverlayWindow import OverlayWindow
+
+
+class TestOverlayCustomDraw(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.qt_app = QApplication.instance() or QApplication([])
+
+    def setUp(self):
+        self.original_app = getattr(og, 'app', None)
+        self.original_device_manager = getattr(og, 'device_manager', None)
+        self.original_ok = getattr(og, 'ok', None)
+        self.original_config = getattr(og, 'config', None)
+        og.app = SimpleNamespace(ok_config={'use_overlay': False})
+        og.device_manager = SimpleNamespace(width=100, height=100)
+        og.ok = SimpleNamespace(screenshot=SimpleNamespace(ui_dict={}))
+        og.config = {}
+        self.view = OverlayWindow(None)
+        self.view.update_overlay(True, 0, 0, 100, 100, 100, 100, 1)
+
+    def tearDown(self):
+        self.view.close()
+        self.view.deleteLater()
+        QApplication.processEvents()
+        og.app = self.original_app
+        og.device_manager = self.original_device_manager
+        og.ok = self.original_ok
+        og.config = self.original_config
+
+    def test_custom_painter_controls_visibility_without_boxes_enabled(self):
+        painted = []
+
+        def paint(painter, view):
+            painted.append(view)
+            painter.setPen(QPen(QColor('green'), 2))
+            painter.drawRect(2, 2, 20, 20)
+
+        self.assertFalse(self.view.isVisible())
+
+        worker = threading.Thread(target=lambda: self.view.draw('status', paint))
+        worker.start()
+        worker.join()
+        QApplication.processEvents()
+        self.view.repaint()
+
+        self.assertTrue(self.view.isVisible())
+        self.assertIn(self.view, painted)
+
+        worker = threading.Thread(target=lambda: self.view.clear_draw('status'))
+        worker.start()
+        worker.join()
+        QApplication.processEvents()
+
+        self.assertFalse(self.view.isVisible())