dxcam 0.3.0.dev1__tar.gz → 0.4.0.dev1__tar.gz

{dxcam-0.3.0.dev1/dxcam.egg-info → dxcam-0.4.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dxcam
-Version: 0.3.0.dev1
+Version: 0.4.0.dev1
 Summary: A Python high-performance screenshot library for Windows using Desktop Duplication API
 Author: ra1nty
 License-Expression: MIT
@@ -104,14 +104,16 @@ camera = dxcam.create(
     processor_backend="cv2" # default OpenCV processor
 )
 ```
+Note:
+- From 0.4.0 the `dxcam.create(max_buffer_len=...)` is deprecated, screen capture now always uses a tripple buffer.
 
 ### Screenshot
 ```python
 frame = camera.grab()
 ```
-`grab()` returns a `numpy.ndarray`. `None` if no new frame is available since the last capture (for backward compatibility); use `camera.grab(new_frame_only=False)` to make dxcam always return the latest frame.
+`grab()` returns a `numpy.ndarray`. `None` if no new frame is available since the last capture; use `camera.grab(new_frame_only=False)` to make dxcam always return the latest frame.
 
-Use `copy=False` (or `camera.grab_view()`) for a zero-copy view. This is faster, but the returned buffer can be overwritten by later captures.
+Use `camera.grab_into(dst)` to reuse caller-managed memory.
 
 To capture a region:
 ```python
@@ -134,14 +136,13 @@ camera.is_capturing  # False
 for _ in range(1000):
     frame = camera.get_latest_frame()  # blocks until a frame is available
 ```
->The screen capture mode spins up a thread that polls newly rendered frames and stores them in an in-memory ring buffer. The blocking and `video_mode` behavior is designed for downstream video recording and machine learning workloads.
+>The screen capture mode spins up a thread that polls newly rendered frames and publishes them into a latest-only in-memory frame buffer. The blocking and `video_mode` behavior is designed for downstream video recording and machine learning workloads.
 
 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
+- `camera.get_latest_frame_into(dst)` -> write latest frame into caller-provided array
 
-> When `start()` capture is running, calling `grab()` reads from the in-memory ring buffer instead of directly polling DXGI.
+> When `start()` capture is running, calling `grab()` reads from the in-memory frame buffer instead of directly polling the capture backend.
 
 ### Safely Releasing Resources
 `release()` stops capture, frees buffers, and releases capture resources.
@@ -193,13 +194,13 @@ Supported modes: `"RGB"`, `"RGBA"`, `"BGR"`, `"BGRA"`, `"GRAY"`.
 Notes:
 - Data is returned as `numpy.ndarray`.
 - `BGRA` does not require OpenCV and is the leanest dependency path.
-- `RGB`, `BGR`, `RGBA`, `GRAY` require conversion (`cv2` or compiled `numpy` backend).
+- `RGB`, `BGR`, `RGBA`, `GRAY` require conversion (`cv2`, `cython`, or compiled `numpy` backend).
 
 ### Frame Buffer
-DXcam uses a fixed-size ring buffer in-memory. New frames overwrite old frames when full.
+DXcam uses a fixed three-slot latest-only frame buffer in-memory. Readers always consume the newest published frame, and older staged frames may be overwritten once they are no longer leased.
 
 ```python
-camera = dxcam.create(max_buffer_len=120)  # default is 8
+camera = dxcam.create()  # max_buffer_len is accepted but ignored
 ```
 
 ### Target FPS
@@ -224,7 +225,7 @@ For `backend="dxgi"`, this value comes from `DXGI_OUTDUPL_FRAME_INFO.LastPresent
 For `backend="winrt"`, this value is derived from WinRT `SystemRelativeTime`.
 
 ### Video Mode
-With `video_mode=True`, DXcam fills the buffer at target FPS, reusing the previous frame if needed, even if no new frame is rendered.
+With `video_mode=True`, DXcam continues publishing at target FPS, reusing the previous frame when no new frame is rendered.
 
 ```python
 import cv2
@@ -261,22 +262,22 @@ Guideline:
 - Try `winrt` if it performs better on your machine or fits your app constraints.
 
 ### Processor Backend
-DXcam capture backends (`dxgi`/`winrt`) first acquire a BGRA frame.  
-The processor backend then handles post-processing:
+DXcam capture backends (`dxgi`/`winrt`) acquire raw BGRA frame. The processor backend then handles post-processing:
 - optional rotation/cropping preparation
 - color conversion to your `output_color`
 
 Recommended backend choice:
 - OpenCV installed: use `cv2` (default)
-- No OpenCV installed: use `numpy` (Cython kernels)
+- No OpenCV installed: use `numpy`/`cython`
 
 Use it like this:
 ```python
 camera = dxcam.create(processor_backend="cv2")
+camera = dxcam.create(processor_backend="cython")
 camera = dxcam.create(processor_backend="numpy")
 ```
 
-Official Windows wheels already include the compiled NumPy kernels.
+Official Windows wheels already include the compiled Cython processor kernels.
 
 Only for source installs:
 ```bash
@@ -288,6 +289,10 @@ If `processor_backend="numpy"` is selected but compiled kernels are unavailable,
 DXcam logs a warning and falls back to `cv2` behavior. In that fallback path,
 install OpenCV for non-`BGRA` output modes.
 
+If `processor_backend="cython"` is selected but compiled kernels are unavailable,
+DXcam raises a runtime error because that backend is explicitly the direct
+Cython path.
+
 ## Benchmarks
 When using a similar logic (only capture newly rendered frames) running on a 240fps output, ```DXCam, python-mss, D3DShot``` benchmarked as follow:
 
@@ -299,10 +304,10 @@ When using a similar logic (only capture newly rendered frames) running on a 240
 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 |
+|   (Target)\\(mean,std)          | DXcam (4k)  | python-mss | D3DShot (1080p) |
 |-------------  |--------                 |------------|---------|
-| 60fps         | 61.71, 0.26 :checkered_flag: | N/A     | 47.11, 1.33  |
-| 30fps         | 30.08, 0.02 :checkered_flag:  | N/A     | 21.24, 0.17  |
+| 60fps         | 59.99, 0.04 :checkered_flag: | N/A     | 47.11, 1.33  |
+| 30fps         | 30.00, 0.00 :checkered_flag:  | N/A     | 21.24, 0.17  |
 
 
 ## Work Referenced

{dxcam-0.3.0.dev1 → dxcam-0.4.0.dev1}/README.md

@@ -59,14 +59,16 @@ camera = dxcam.create(
     processor_backend="cv2" # default OpenCV processor
 )
 ```
+Note:
+- From 0.4.0 the `dxcam.create(max_buffer_len=...)` is deprecated, screen capture now always uses a tripple buffer.
 
 ### Screenshot
 ```python
 frame = camera.grab()
 ```
-`grab()` returns a `numpy.ndarray`. `None` if no new frame is available since the last capture (for backward compatibility); use `camera.grab(new_frame_only=False)` to make dxcam always return the latest frame.
+`grab()` returns a `numpy.ndarray`. `None` if no new frame is available since the last capture; use `camera.grab(new_frame_only=False)` to make dxcam always return the latest frame.
 
-Use `copy=False` (or `camera.grab_view()`) for a zero-copy view. This is faster, but the returned buffer can be overwritten by later captures.
+Use `camera.grab_into(dst)` to reuse caller-managed memory.
 
 To capture a region:
 ```python
@@ -89,14 +91,13 @@ camera.is_capturing  # False
 for _ in range(1000):
     frame = camera.get_latest_frame()  # blocks until a frame is available
 ```
->The screen capture mode spins up a thread that polls newly rendered frames and stores them in an in-memory ring buffer. The blocking and `video_mode` behavior is designed for downstream video recording and machine learning workloads.
+>The screen capture mode spins up a thread that polls newly rendered frames and publishes them into a latest-only in-memory frame buffer. The blocking and `video_mode` behavior is designed for downstream video recording and machine learning workloads.
 
 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
+- `camera.get_latest_frame_into(dst)` -> write latest frame into caller-provided array
 
-> When `start()` capture is running, calling `grab()` reads from the in-memory ring buffer instead of directly polling DXGI.
+> When `start()` capture is running, calling `grab()` reads from the in-memory frame buffer instead of directly polling the capture backend.
 
 ### Safely Releasing Resources
 `release()` stops capture, frees buffers, and releases capture resources.
@@ -148,13 +149,13 @@ Supported modes: `"RGB"`, `"RGBA"`, `"BGR"`, `"BGRA"`, `"GRAY"`.
 Notes:
 - Data is returned as `numpy.ndarray`.
 - `BGRA` does not require OpenCV and is the leanest dependency path.
-- `RGB`, `BGR`, `RGBA`, `GRAY` require conversion (`cv2` or compiled `numpy` backend).
+- `RGB`, `BGR`, `RGBA`, `GRAY` require conversion (`cv2`, `cython`, or compiled `numpy` backend).
 
 ### Frame Buffer
-DXcam uses a fixed-size ring buffer in-memory. New frames overwrite old frames when full.
+DXcam uses a fixed three-slot latest-only frame buffer in-memory. Readers always consume the newest published frame, and older staged frames may be overwritten once they are no longer leased.
 
 ```python
-camera = dxcam.create(max_buffer_len=120)  # default is 8
+camera = dxcam.create()  # max_buffer_len is accepted but ignored
 ```
 
 ### Target FPS
@@ -179,7 +180,7 @@ For `backend="dxgi"`, this value comes from `DXGI_OUTDUPL_FRAME_INFO.LastPresent
 For `backend="winrt"`, this value is derived from WinRT `SystemRelativeTime`.
 
 ### Video Mode
-With `video_mode=True`, DXcam fills the buffer at target FPS, reusing the previous frame if needed, even if no new frame is rendered.
+With `video_mode=True`, DXcam continues publishing at target FPS, reusing the previous frame when no new frame is rendered.
 
 ```python
 import cv2
@@ -216,22 +217,22 @@ Guideline:
 - Try `winrt` if it performs better on your machine or fits your app constraints.
 
 ### Processor Backend
-DXcam capture backends (`dxgi`/`winrt`) first acquire a BGRA frame.  
-The processor backend then handles post-processing:
+DXcam capture backends (`dxgi`/`winrt`) acquire raw BGRA frame. The processor backend then handles post-processing:
 - optional rotation/cropping preparation
 - color conversion to your `output_color`
 
 Recommended backend choice:
 - OpenCV installed: use `cv2` (default)
-- No OpenCV installed: use `numpy` (Cython kernels)
+- No OpenCV installed: use `numpy`/`cython`
 
 Use it like this:
 ```python
 camera = dxcam.create(processor_backend="cv2")
+camera = dxcam.create(processor_backend="cython")
 camera = dxcam.create(processor_backend="numpy")
 ```
 
-Official Windows wheels already include the compiled NumPy kernels.
+Official Windows wheels already include the compiled Cython processor kernels.
 
 Only for source installs:
 ```bash
@@ -243,6 +244,10 @@ If `processor_backend="numpy"` is selected but compiled kernels are unavailable,
 DXcam logs a warning and falls back to `cv2` behavior. In that fallback path,
 install OpenCV for non-`BGRA` output modes.
 
+If `processor_backend="cython"` is selected but compiled kernels are unavailable,
+DXcam raises a runtime error because that backend is explicitly the direct
+Cython path.
+
 ## Benchmarks
 When using a similar logic (only capture newly rendered frames) running on a 240fps output, ```DXCam, python-mss, D3DShot``` benchmarked as follow:
 
@@ -254,10 +259,10 @@ When using a similar logic (only capture newly rendered frames) running on a 240
 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 |
+|   (Target)\\(mean,std)          | DXcam (4k)  | python-mss | D3DShot (1080p) |
 |-------------  |--------                 |------------|---------|
-| 60fps         | 61.71, 0.26 :checkered_flag: | N/A     | 47.11, 1.33  |
-| 30fps         | 30.08, 0.02 :checkered_flag:  | N/A     | 21.24, 0.17  |
+| 60fps         | 59.99, 0.04 :checkered_flag: | N/A     | 47.11, 1.33  |
+| 30fps         | 30.00, 0.00 :checkered_flag:  | N/A     | 21.24, 0.17  |
 
 
 ## Work Referenced

{dxcam-0.3.0.dev1 → dxcam-0.4.0.dev1}/dxcam/__init__.py

@@ -24,7 +24,7 @@ import weakref
 from types import FrameType
 from typing import Any, Callable, cast
 
-from dxcam.core.backend import normalize_backend_name
+from dxcam.runtime.backend import normalize_backend_name
 from dxcam.dxcam import DXCamera, Output, Device
 from dxcam.processor import normalize_processor_backend_name
 from dxcam.types import CaptureBackend, ColorMode, ProcessorBackend, Region
@@ -140,8 +140,8 @@ class DXFactory(metaclass=Singleton):
         if existing_camera is not None:
             logger.warning(
                 "DXCamera instance already exists for device=%s output=%s backend=%s; "
-                "returning existing instance. Delete the old object with `del obj` "
-                "to recreate it with new parameters.",
+                "returning the existing instance. Call release() before "
+                "recreating it with new parameters.",
                 device_idx,
                 output_idx,
                 backend,
@@ -239,11 +239,14 @@ def create(
             the primary output.
         region: Optional capture region as ``(left, top, right, bottom)``.
         output_color: Output pixel format.
-        max_buffer_len: Ring-buffer size used in threaded capture mode.
+        max_buffer_len: Kept for API compatibility. Threaded capture uses a
+            fixed three-slot latest-only frame buffer.
         backend: Capture backend, ``"dxgi"`` or ``"winrt"``.
-        processor_backend: Post-processing backend, ``"cv2"`` (default)
-            or ``"numpy"``. The ``"numpy"`` backend uses compiled Cython
-            kernels when available and falls back to cv2 behavior otherwise.
+        processor_backend: Post-processing backend, ``"cv2"`` (default),
+            ``"cython"``, or ``"numpy"``. The ``"cython"`` backend uses the
+            direct compiled Cython processor, while ``"numpy"`` uses compiled
+            conversion kernels when available and falls back to cv2 behavior
+            otherwise.
 
     Returns:
         A :class:`dxcam.dxcam.DXCamera` instance.

{dxcam-0.3.0.dev1 → dxcam-0.4.0.dev1}/dxcam/_libs/d3d11.py

@@ -19,6 +19,9 @@ D3D11_USAGE_IMMUTABLE = 1
 D3D11_USAGE_DYNAMIC = 2
 D3D11_USAGE_STAGING = 3
 
+D3D11_MAP_READ = 1
+D3D11_MAP_FLAG_DO_NOT_WAIT = 0x100000
+
 DXGI_FORMAT_B8G8R8A8_UNORM = 87
 
 
@@ -55,6 +58,14 @@ class D3D11_TEXTURE2D_DESC(ctypes.Structure):
     ]
 
 
+class D3D11_MAPPED_SUBRESOURCE(ctypes.Structure):
+    _fields_ = [
+        ("pData", ctypes.c_void_p),
+        ("RowPitch", wintypes.UINT),
+        ("DepthPitch", wintypes.UINT),
+    ]
+
+
 class ID3D11DeviceChild(comtypes.IUnknown):
     _iid_ = comtypes.GUID("{1841e5c8-16b0-489b-bcc8-44cfb0d5deae}")
     _methods_ = [

{dxcam-0.3.0.dev1 → dxcam-0.4.0.dev1}/dxcam/_libs/dxgi.py

@@ -10,6 +10,7 @@ DXGI_ERROR_NOT_FOUND = 0x887A0002
 DXGI_ERROR_SESSION_DISCONNECTED = 0x887A0028
 DXGI_ERROR_UNSUPPORTED = 0x887A0004
 DXGI_ERROR_WAIT_TIMEOUT = 0x887A0027
+DXGI_ERROR_WAS_STILL_DRAWING = 0x887A000A
 
 DXGI_OUTDUPL_FLAG_NONE = 0x0
 DXGI_OUTDUPL_FLAG_COMPOSITED_UI_CAPTURE_ONLY = 0x1

dxcam-0.4.0.dev1/dxcam/core/__init__.py

@@ -0,0 +1,6 @@
+__all__ = ["Device", "Output", "StageSurface"]
+
+
+from dxcam.core.device import Device
+from dxcam.core.output import Output
+from dxcam.core.stagesurf import StageSurface

dxcam-0.4.0.dev1/dxcam/core/com_ptr.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import ctypes
+from typing import Any
+
+
+def clear_com_pointer(pointer: Any) -> None:
+    """Set a COM pointer value to NULL in-place without calling Release()."""
+    if pointer is None:
+        return
+    try:
+        raw = ctypes.cast(ctypes.byref(pointer), ctypes.POINTER(ctypes.c_void_p))
+        raw[0] = None
+    except Exception:
+        # Best-effort cleanup helper; callers may still overwrite the attribute.
+        return
+
+
+def release_com_pointer(pointer: Any) -> None:
+    """Release a COM pointer once, then null it to avoid late double-Release."""
+    if pointer is None or not pointer:
+        return
+    try:
+        pointer.Release()
+    finally:
+        clear_com_pointer(pointer)

dxcam-0.4.0.dev1/dxcam/core/duplicator_protocol.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Any, ContextManager, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class FrameDuplicator(Protocol):
+    """Minimal capture backend contract consumed by DXCamera/runtime."""
+
+    texture: Any
+
+    def acquire_frame(
+        self, wait_for_frame: bool = False
+    ) -> ContextManager[tuple[bool, bool, int]]: ...
+
+    def ticks_to_seconds(self, ticks: int) -> float: ...
+
+    def release(self) -> None: ...

{dxcam-0.3.0.dev1 → dxcam-0.4.0.dev1}/dxcam/core/dxgi_duplicator.py

@@ -3,8 +3,9 @@ from __future__ import annotations
 import ctypes
 import logging
 import os
+from contextlib import contextmanager
 from dataclasses import InitVar, dataclass, field
-from typing import Any, cast
+from typing import Any, Iterator, cast
 
 import comtypes
 
@@ -17,6 +18,7 @@ from dxcam._libs.dxgi import (
     IDXGIOutput5,
     IDXGIResource,
 )
+from dxcam.core.com_ptr import release_com_pointer
 from dxcam.core.device import Device
 from dxcam.core.dxgi_errors import (
     DXGITransientContext,
@@ -40,7 +42,6 @@ class DXGIDuplicator:
     """Desktop Duplication API wrapper for acquiring frame textures."""
 
     texture: Any = field(default_factory=lambda: ctypes.POINTER(ID3D11Texture2D)())
-    early_release_frame: bool = True
     duplicator: Any = None
     updated: bool = False
     output: InitVar[Output | None] = None
@@ -51,6 +52,10 @@ class DXGIDuplicator:
     performance_frequency: int = 0
     _frame_held: bool = False
 
+    def _drop_texture_reference(self) -> None:
+        release_com_pointer(self.texture)
+        self.texture = ctypes.POINTER(ID3D11Texture2D)()
+
     def __post_init__(self, output: Output | None, device: Device | None) -> None:
         if output is None or device is None:
             raise ValueError(
@@ -126,60 +131,77 @@ class DXGIDuplicator:
             self.duplicator = ctypes.POINTER(IDXGIOutputDuplication)()
             return False
 
-    def update_frame(self, wait_for_frame: bool = False) -> bool:
+    def _update_frame(self, wait_for_frame: bool = False) -> bool:
         del wait_for_frame  # DXGI path does not use extra wait logic.
         if self._frame_held:
-            if not self.release_frame():
+            if not self._release_frame():
                 self.updated = False
                 return False
 
         info = DXGI_OUTDUPL_FRAME_INFO()
         res = ctypes.POINTER(IDXGIResource)()
         try:
-            self.duplicator.AcquireNextFrame(
-                0,
-                ctypes.byref(info),
-                ctypes.byref(res),
-            )
-        except comtypes.COMError as ce:
-            hresult = com_error_hresult_u32(ce)
-            if hresult == DXGI_ERROR_WAIT_TIMEOUT_U32:
-                self.updated = False
-                self.accumulated_frames = 0
-                return True
-            if is_transient_hresult(
-                hresult,
-                DXGITransientContext.FRAME_INFO,
-                DXGITransientContext.SYSTEM_TRANSITION,
-            ):
-                logger.warning(
-                    "Desktop duplication access loss/system transition detected "
-                    "(HRESULT=0x%08X). Triggering output-change recovery.",
-                    hresult,
+            try:
+                self.duplicator.AcquireNextFrame(
+                    0,
+                    ctypes.byref(info),
+                    ctypes.byref(res),
                 )
+            except comtypes.COMError as ce:
+                hresult = com_error_hresult_u32(ce)
+                if hresult == DXGI_ERROR_WAIT_TIMEOUT_U32:
+                    self.updated = False
+                    self.accumulated_frames = 0
+                    return True
+                if is_transient_hresult(
+                    hresult,
+                    DXGITransientContext.FRAME_INFO,
+                    DXGITransientContext.SYSTEM_TRANSITION,
+                ):
+                    logger.warning(
+                        "Desktop duplication access loss/system transition detected "
+                        "(HRESULT=0x%08X). Triggering output-change recovery.",
+                        hresult,
+                    )
+                    self.updated = False
+                    self._frame_held = False
+                    return False
+                raise
+            self._frame_held = True
+            try:
+                resource = cast(Any, res)
+                self._drop_texture_reference()
+                self.texture = resource.QueryInterface(ID3D11Texture2D)
+            except comtypes.COMError:
+                self._release_frame()
+                self.texture = ctypes.POINTER(ID3D11Texture2D)()
                 self.updated = False
-                self._frame_held = False
-                return False
-            raise
-        self._frame_held = True
-        try:
-            resource = cast(Any, res)
-            self.texture = resource.QueryInterface(ID3D11Texture2D)
-        except comtypes.COMError:
-            self.release_frame()
-            self.texture = ctypes.POINTER(ID3D11Texture2D)()
-            self.updated = False
+                return True
+            present_ticks = int(info.LastPresentTime)
+            self.accumulated_frames = int(info.AccumulatedFrames)
+            if present_ticks > 0:
+                self.latest_frame_ticks = present_ticks
+            else:
+                mouse_ticks = int(info.LastMouseUpdateTime)
+                if mouse_ticks > 0:
+                    self.latest_frame_ticks = mouse_ticks
+            self.updated = True
             return True
-        present_ticks = int(info.LastPresentTime)
-        self.accumulated_frames = int(info.AccumulatedFrames)
-        if present_ticks > 0:
-            self.latest_frame_ticks = present_ticks
-        else:
-            mouse_ticks = int(info.LastMouseUpdateTime)
-            if mouse_ticks > 0:
-                self.latest_frame_ticks = mouse_ticks
-        self.updated = True
-        return True
+        finally:
+            release_com_pointer(res)
+
+    @contextmanager
+    def acquire_frame(
+        self, wait_for_frame: bool = False
+    ) -> Iterator[tuple[bool, bool, int]]:
+        ok = self._update_frame(wait_for_frame=wait_for_frame)
+        updated = ok and self.updated
+        frame_ticks = self.latest_frame_ticks
+        try:
+            yield ok, updated, frame_ticks
+        finally:
+            if ok and updated:
+                self._finish_frame()
 
     @property
     def latest_frame_time(self) -> float:
@@ -190,7 +212,7 @@ class DXGIDuplicator:
             return 0.0
         return ticks / self.performance_frequency
 
-    def release_frame(self) -> bool:
+    def _release_frame(self) -> bool:
         """Per Microsoft Doc
         https://learn.microsoft.com/en-us/windows/win32/api/dxgi1_2/nf-dxgi1_2-idxgioutputduplication-releaseframe#remarks
         This should be called just before AquireNextFrame, but we found audio artifacts
@@ -203,6 +225,7 @@ class DXGIDuplicator:
         """
         if self.duplicator is None or not self._frame_held:
             return True
+        self._drop_texture_reference()
         try:
             self.duplicator.ReleaseFrame()
         except comtypes.COMError as ce:
@@ -223,11 +246,16 @@ class DXGIDuplicator:
         self._frame_held = False
         return True
 
+    def _finish_frame(self) -> bool:
+        # DXGI path releases immediately after staging copy for better pacing.
+        return self._release_frame()
+
     def release(self) -> None:
+        self._drop_texture_reference()
         if self.duplicator is not None:
-            self.release_frame()
+            self._release_frame()
             try:
-                self.duplicator.Release()
+                release_com_pointer(self.duplicator)
             except comtypes.COMError:
                 logger.debug(
                     "Ignoring COMError while releasing duplicator.", exc_info=True