dxcam 0.1.0.dev1__tar.gz → 0.1.0.dev2__tar.gz

{dxcam-0.1.0.dev1 → dxcam-0.1.0.dev2}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: dxcam
-Version: 0.1.0.dev1
+Version: 0.1.0.dev2
 Summary: A Python high-performance screenshot library for Windows using Desktop Duplication API
 Author: ra1nty
 License-Expression: MIT
 Project-URL: Source, https://github.com/ra1nty/DXcam
 Project-URL: Tracker, https://github.com/ra1nty/DXcam/issues
 Keywords: screen,screenshot,screencapture,screengrab,windows
-Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -20,7 +20,7 @@ Classifier: Operating System :: Microsoft :: Windows :: Windows 11
 Classifier: Topic :: Multimedia :: Graphics
 Classifier: Topic :: Multimedia :: Graphics :: Capture
 Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
-Requires-Python: >=3.11
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: comtypes
@@ -88,8 +88,9 @@ camera = dxcam.create()  # primary output on device 0
 ```python
 frame = camera.grab()
 ```
+`grab()` returns a `numpy.ndarray`. `None` if no new frame is available since the last capture, mainly for backward compatibility. You can use `new_frame_only=False` to change this behavior.
 
-`grab()` returns a `numpy.ndarray`. `None` if no new frame is available since the last capture.
+Use `copy=False` (or `camera.grab_view()`) for a zero-copy view.
 
 To capture a region:
 ```python
@@ -117,6 +118,9 @@ for _ in range(1000):
 Useful variants:
 - `camera.get_latest_frame(with_timestamp=True)` -> `(frame, frame_timestamp)` -> return frame timestamp
 - `camera.get_latest_frame_view()` -> zero-copy view into the frame buffer
+- `camera.grab(copy=False)` / `camera.grab_view()` -> zero-copy latest-frame snapshot
+
+** When `start()` capture is running, calling `grab()` reads from the in-memory ring buffer instead of directly polling DXGI.
 
 ## Advanced Usage and Remarks
 ### Multiple monitors / GPUs
@@ -211,14 +215,14 @@ camera.release()
 ```
 
 ## Benchmarks
-When using a similar logic (only captured newly rendered frames), ```DXCam, python-mss, D3DShot``` benchmarked as follow:
+When using a similar logic (only capture newly rendered frames) running on a 240fps output, ```DXCam, python-mss, D3DShot``` benchmarked as follow:
 
 |             | DXcam  | python-mss | D3DShot |
 |-------------|--------|------------|---------|
 | Average FPS | 239.19 :checkered_flag: | 75.87      | 118.36  |
 | Std Dev     | 1.25   | 0.5447     | 0.3224   |
 
-The benchmark is across 5 runs, with a light-moderate usage on my PC (5900X + 3090; Chrome ~30tabs, VS Code opened, etc.), I used the [Blur Buster UFO test](https://www.testufo.com/framerates#count=5&background=stars&pps=960) to constantly render 240 fps on my monitor (Zowie 2546K). DXcam captured almost every frame rendered. You will see some benchmarks online claiming 1000+fps capture while most of them is busy-spinning a for loop on a staled frame (no new frame rendered on screen in test scenario).
+The benchmark is across 5 runs, with a light-moderate usage on my PC (5900X + 3090; Chrome ~30tabs, VS Code opened, etc.), I used the [Blur Buster UFO test](https://www.testufo.com/framerates#count=5&background=stars&pps=960) to constantly render 240 fps on my monitor. DXcam captured almost every frame rendered. You will see some benchmarks online claiming 1000+fps capture while most of them is busy-spinning a for loop on a staled frame (no new frame rendered on screen in test scenario).
 
 ### For Targeting FPS:
 |   (Target)\\(mean,std)          | DXcam  | python-mss | D3DShot |

{dxcam-0.1.0.dev1 → dxcam-0.1.0.dev2}/README.md

@@ -57,8 +57,9 @@ camera = dxcam.create()  # primary output on device 0
 ```python
 frame = camera.grab()
 ```
+`grab()` returns a `numpy.ndarray`. `None` if no new frame is available since the last capture, mainly for backward compatibility. You can use `new_frame_only=False` to change this behavior.
 
-`grab()` returns a `numpy.ndarray`. `None` if no new frame is available since the last capture.
+Use `copy=False` (or `camera.grab_view()`) for a zero-copy view.
 
 To capture a region:
 ```python
@@ -86,6 +87,9 @@ for _ in range(1000):
 Useful variants:
 - `camera.get_latest_frame(with_timestamp=True)` -> `(frame, frame_timestamp)` -> return frame timestamp
 - `camera.get_latest_frame_view()` -> zero-copy view into the frame buffer
+- `camera.grab(copy=False)` / `camera.grab_view()` -> zero-copy latest-frame snapshot
+
+** When `start()` capture is running, calling `grab()` reads from the in-memory ring buffer instead of directly polling DXGI.
 
 ## Advanced Usage and Remarks
 ### Multiple monitors / GPUs
@@ -180,14 +184,14 @@ camera.release()
 ```
 
 ## Benchmarks
-When using a similar logic (only captured newly rendered frames), ```DXCam, python-mss, D3DShot``` benchmarked as follow:
+When using a similar logic (only capture newly rendered frames) running on a 240fps output, ```DXCam, python-mss, D3DShot``` benchmarked as follow:
 
 |             | DXcam  | python-mss | D3DShot |
 |-------------|--------|------------|---------|
 | Average FPS | 239.19 :checkered_flag: | 75.87      | 118.36  |
 | Std Dev     | 1.25   | 0.5447     | 0.3224   |
 
-The benchmark is across 5 runs, with a light-moderate usage on my PC (5900X + 3090; Chrome ~30tabs, VS Code opened, etc.), I used the [Blur Buster UFO test](https://www.testufo.com/framerates#count=5&background=stars&pps=960) to constantly render 240 fps on my monitor (Zowie 2546K). DXcam captured almost every frame rendered. You will see some benchmarks online claiming 1000+fps capture while most of them is busy-spinning a for loop on a staled frame (no new frame rendered on screen in test scenario).
+The benchmark is across 5 runs, with a light-moderate usage on my PC (5900X + 3090; Chrome ~30tabs, VS Code opened, etc.), I used the [Blur Buster UFO test](https://www.testufo.com/framerates#count=5&background=stars&pps=960) to constantly render 240 fps on my monitor. DXcam captured almost every frame rendered. You will see some benchmarks online claiming 1000+fps capture while most of them is busy-spinning a for loop on a staled frame (no new frame rendered on screen in test scenario).
 
 ### For Targeting FPS:
 |   (Target)\\(mean,std)          | DXcam  | python-mss | D3DShot |
@@ -200,4 +204,4 @@ The benchmark is across 5 runs, with a light-moderate usage on my PC (5900X + 30
 
 [OBS Studio](https://github.com/obsproject/obs-studio) - implementation ideas and references.
 
-[D3DShot](https://github.com/SerpentAI/D3DShot/) : DXcam borrows the ctypes header directly from the no-longer maintained D3DShot.
+[D3DShot](https://github.com/SerpentAI/D3DShot/) : DXcam borrows the ctypes header directly from the no-longer maintained D3DShot.

{dxcam-0.1.0.dev1 → dxcam-0.1.0.dev2}/dxcam/core/duplicator.py

@@ -124,7 +124,7 @@ class Duplicator:
         res = ctypes.POINTER(IDXGIResource)()
         try:
             self.duplicator.AcquireNextFrame(
-                1,
+                0,
                 ctypes.byref(info),
                 ctypes.byref(res),
             )

{dxcam-0.1.0.dev1 → dxcam-0.1.0.dev2}/dxcam/dxcam.py

@@ -87,32 +87,93 @@ class DXCamera:
         self.__frame_count = 0
         self.__capture_start_time = 0
         self.__latest_frame_ticks: int | None = None
+        self.__last_grab_entry: tuple[Region, Frame] | None = None
 
-    def grab(self, region: Region | None = None) -> Frame | None:
+    def grab(
+        self,
+        region: Region | None = None,
+        copy: bool = True,
+        new_frame_only: bool = True,
+    ) -> Frame | None:
+        """Grab one frame.
+
+        Ownership contract:
+        - ``copy=True`` returns caller-owned memory.
+        - ``copy=False`` may return internal memory reused by future grabs.
+        - ``new_frame_only=True`` returns ``None`` when no new frame is available
+          in one-shot mode.
+        - ``new_frame_only=False`` falls back to the last successfully grabbed
+          frame for the same region in one-shot mode.
+
+        When capture is running (``start()``), this reads from the ring buffer
+        instead of touching DXGI objects directly. ``new_frame_only`` does not
+        apply while capture is running.
+        """
         self._ensure_not_released()
+        if self.is_capturing:
+            if region is not None and region != self.region:
+                raise ValueError(
+                    "grab(region=...) is not supported while capture is running. "
+                    "Use start(region=...) to configure capture region."
+                )
+            return self._peek_latest_buffered_frame(copy=copy)
         if region is None:
             region = self.region
         else:
             self._validate_region(region)
-        frame = self._grab(region)
+        frame = self._grab(region, copy=copy, new_frame_only=new_frame_only)
         return frame
 
-    def _grab(self, region: Region) -> Frame | None:
+    def grab_view(self, region: Region | None = None) -> Frame | None:
+        """Zero-copy variant of ``grab()``."""
+        return self.grab(region=region, copy=False)
+
+    def _peek_latest_buffered_frame(self, copy: bool = True) -> Frame | None:
+        with self.__lock:
+            if self.__frame_buffer is None or not self.__has_frame:
+                return None
+            latest_idx = (self.__head - 1) % self.max_buffer_len
+            ret = self.__frame_buffer[latest_idx]
+        return np.array(ret, copy=True) if copy else ret
+
+    def _set_cached_grab_frame(self, region: Region, frame: Frame) -> None:
+        self.__last_grab_entry = (region, frame)
+
+    def _get_cached_grab_frame(
+        self, region: Region, copy: bool = True
+    ) -> Frame | None:
+        entry = self.__last_grab_entry
+        if entry is None:
+            return None
+        cached_region, cached = entry
+        if cached_region != region:
+            return None
+        return np.array(cached, copy=True) if copy else cached
+
+    def _grab(
+        self,
+        region: Region,
+        copy: bool = True,
+        new_frame_only: bool = True,
+    ) -> Frame | None:
         if not self._duplicator.update_frame():
             self._on_output_change()
-            return None
+            if new_frame_only:
+                return None
+            return self._get_cached_grab_frame(region=region, copy=copy)
         if not self._duplicator.updated:
-            return None
+            if new_frame_only:
+                return None
+            return self._get_cached_grab_frame(region=region, copy=copy)
 
         frame_width, frame_height = self._copy_region_to_stage(region)
         frame = self._process_staging_frame(
             frame_width=frame_width, frame_height=frame_height
         )
-
-        if not self.is_capturing:
-            self._duplicator.release_frame()
-            return np.array(frame, copy=True)
-        return frame
+        result = np.array(frame, copy=True) if copy else frame
+        if not new_frame_only:
+            self._set_cached_grab_frame(region=region, frame=result)
+        return result
 
     def _grab_into(self, region: Region, dst: Frame) -> tuple[bool, int, int, int]:
         """Capture into ``dst`` and return ``(captured, frame_ticks, width, height)``.
@@ -203,6 +264,7 @@ class DXCamera:
         time.sleep(0.1)  # Wait for Display mode change (Access Lost)
         self._duplicator.release()
         self._stagesurf.release()
+        self.__last_grab_entry = None
         self._output.update_desc()
         self.width, self.height = self._output.resolution
         if not self._region_set_by_user:
@@ -303,6 +365,7 @@ class DXCamera:
             self.__frame_time_ticks = None
             self.__frame_count = 0
             self.__latest_frame_ticks = None
+            self.__last_grab_entry = None
             self.__head = 0
             self.__tail = 0
             self.__full = False

{dxcam-0.1.0.dev1 → dxcam-0.1.0.dev2}/dxcam/util/timer.py

@@ -8,6 +8,10 @@ class _Timer:
     def __init__(self):
         self.period_s: float = 0.0
         self._next_tick: Optional[float] = None
+        # Declared on the base type so static checkers can validate both
+        # modern and legacy timer paths through a shared interface.
+        self.cancelled: bool = False
+        self._handle: Optional[int] = None
 
 
 if sys.version_info >= (3, 11):

{dxcam-0.1.0.dev1 → dxcam-0.1.0.dev2}/dxcam.egg-info/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: dxcam
-Version: 0.1.0.dev1
+Version: 0.1.0.dev2
 Summary: A Python high-performance screenshot library for Windows using Desktop Duplication API
 Author: ra1nty
 License-Expression: MIT
 Project-URL: Source, https://github.com/ra1nty/DXcam
 Project-URL: Tracker, https://github.com/ra1nty/DXcam/issues
 Keywords: screen,screenshot,screencapture,screengrab,windows
-Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -20,7 +20,7 @@ Classifier: Operating System :: Microsoft :: Windows :: Windows 11
 Classifier: Topic :: Multimedia :: Graphics
 Classifier: Topic :: Multimedia :: Graphics :: Capture
 Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
-Requires-Python: >=3.11
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: comtypes
@@ -88,8 +88,9 @@ camera = dxcam.create()  # primary output on device 0
 ```python
 frame = camera.grab()
 ```
+`grab()` returns a `numpy.ndarray`. `None` if no new frame is available since the last capture, mainly for backward compatibility. You can use `new_frame_only=False` to change this behavior.
 
-`grab()` returns a `numpy.ndarray`. `None` if no new frame is available since the last capture.
+Use `copy=False` (or `camera.grab_view()`) for a zero-copy view.
 
 To capture a region:
 ```python
@@ -117,6 +118,9 @@ for _ in range(1000):
 Useful variants:
 - `camera.get_latest_frame(with_timestamp=True)` -> `(frame, frame_timestamp)` -> return frame timestamp
 - `camera.get_latest_frame_view()` -> zero-copy view into the frame buffer
+- `camera.grab(copy=False)` / `camera.grab_view()` -> zero-copy latest-frame snapshot
+
+** When `start()` capture is running, calling `grab()` reads from the in-memory ring buffer instead of directly polling DXGI.
 
 ## Advanced Usage and Remarks
 ### Multiple monitors / GPUs
@@ -211,14 +215,14 @@ camera.release()
 ```
 
 ## Benchmarks
-When using a similar logic (only captured newly rendered frames), ```DXCam, python-mss, D3DShot``` benchmarked as follow:
+When using a similar logic (only capture newly rendered frames) running on a 240fps output, ```DXCam, python-mss, D3DShot``` benchmarked as follow:
 
 |             | DXcam  | python-mss | D3DShot |
 |-------------|--------|------------|---------|
 | Average FPS | 239.19 :checkered_flag: | 75.87      | 118.36  |
 | Std Dev     | 1.25   | 0.5447     | 0.3224   |
 
-The benchmark is across 5 runs, with a light-moderate usage on my PC (5900X + 3090; Chrome ~30tabs, VS Code opened, etc.), I used the [Blur Buster UFO test](https://www.testufo.com/framerates#count=5&background=stars&pps=960) to constantly render 240 fps on my monitor (Zowie 2546K). DXcam captured almost every frame rendered. You will see some benchmarks online claiming 1000+fps capture while most of them is busy-spinning a for loop on a staled frame (no new frame rendered on screen in test scenario).
+The benchmark is across 5 runs, with a light-moderate usage on my PC (5900X + 3090; Chrome ~30tabs, VS Code opened, etc.), I used the [Blur Buster UFO test](https://www.testufo.com/framerates#count=5&background=stars&pps=960) to constantly render 240 fps on my monitor. DXcam captured almost every frame rendered. You will see some benchmarks online claiming 1000+fps capture while most of them is busy-spinning a for loop on a staled frame (no new frame rendered on screen in test scenario).
 
 ### For Targeting FPS:
 |   (Target)\\(mean,std)          | DXcam  | python-mss | D3DShot |

{dxcam-0.1.0.dev1 → dxcam-0.1.0.dev2}/pyproject.toml

@@ -4,15 +4,15 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "dxcam"
-version = "0.1.0.dev1"
+version = "0.1.0.dev2"
 description = "A Python high-performance screenshot library for Windows using Desktop Duplication API"
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.10"
 license = "MIT"
 authors = [{ name = "ra1nty" }]
 keywords = ["screen", "screenshot", "screencapture", "screengrab", "windows"]
 classifiers = [
-    "Development Status :: 2 - Pre-Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",