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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dxcam
-Version: 0.3.0.dev1
+Version: 0.4.0.dev2
 Summary: A Python high-performance screenshot library for Windows using Desktop Duplication API
 Author: ra1nty
 License-Expression: MIT
@@ -104,14 +104,18 @@ camera = dxcam.create(
     processor_backend="cv2" # default OpenCV processor
 )
 ```
+Note:
+- Version 0.4 uses a fixed three-slot frame buffer; `max_buffer_len` has been removed.
+- Device discovery happens on the first `create()`, `device_info()`, or `output_info()` call.
+- Upgrading from 0.3? See the [0.4 migration guide](https://github.com/ra1nty/DXcam/blob/dev/docs/migration-0.4.md).
 
 ### 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`. In one-shot mode it returns `None` if no new frame is available; `camera.grab(new_frame_only=False)` can reuse the last cached frame. During threaded capture, it reads the latest published frame and ignores `new_frame_only`.
 
-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
@@ -132,20 +136,20 @@ camera.is_capturing  # False
 #### Consume the Screen Capture Data
 ```python
 for _ in range(1000):
-    frame = camera.get_latest_frame()  # blocks until a frame is available
+    frame = camera.get_latest_frame()  # waits for the first available frame
 ```
->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 capture thread publishes into a latest-only frame buffer. Once a frame is available, reads return immediately and can return the same timestamp repeatedly. Consumers control their own pacing; compare timestamps when you need only fresh frames. `target_fps` controls the producer, not the frequency of consumer reads.
 
 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.
 After `release()`, the same instance cannot be reused.
+In-flight readers retain their staging surfaces until readout completes, including across stop or output recovery.
 
 ```python
 camera = dxcam.create(output_idx=0, output_color="BGR")
@@ -193,13 +197,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 consume the newest published frame. A surface being read is never overwritten; if no safe write slot is available, capture skips that cycle. Older surfaces are released only after their readers finish.
 
 ```python
-camera = dxcam.create(max_buffer_len=120)  # default is 8
+camera = dxcam.create()
 ```
 
 ### Target FPS
@@ -224,26 +228,37 @@ 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
 import dxcam
+import time
 
 target_fps = 30
 camera = dxcam.create(output_color="BGR")
 camera.start(target_fps=target_fps, video_mode=True)
 
 writer = cv2.VideoWriter(
-    "video.mp4", cv2.VideoWriter_fourcc(*"mp4v"), target_fps, (1920, 1080)
+    "video.mp4", cv2.VideoWriter_fourcc(*"mp4v"), target_fps,
+    (camera.width, camera.height),
 )
-for _ in range(600):
-    writer.write(camera.get_latest_frame())
-
-camera.stop()
-writer.release()
+try:
+    next_frame = time.perf_counter()
+    for _ in range(600):
+        time.sleep(max(0, next_frame - time.perf_counter()))
+        next_frame = time.perf_counter() + 1 / target_fps
+        frame = camera.get_latest_frame()
+        if frame is not None:
+            writer.write(frame)
+finally:
+    camera.release()
+    writer.release()
 ```
 
+Latest-frame reads return immediately once a frame exists. Pace the consumer as
+above to avoid filling the video with repeated reads as fast as Python can run.
+
 ### Capture Backend
 DXcam supports two capture backends:
 - `dxgi` (default): Desktop Duplication API path with broad compatibility.
@@ -261,22 +276,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,7 +303,14 @@ 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
+See the [0.4 development comparison against PyPI 0.3.0](https://github.com/ra1nty/DXcam/blob/dev/benchmarks/capture_comparison.md)
+for measured fresh-frame throughput, frame age, CPU use, and reproducible steps.
+
 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 |
@@ -299,10 +321,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.dev2}/README.md

@@ -59,14 +59,18 @@ camera = dxcam.create(
     processor_backend="cv2" # default OpenCV processor
 )
 ```
+Note:
+- Version 0.4 uses a fixed three-slot frame buffer; `max_buffer_len` has been removed.
+- Device discovery happens on the first `create()`, `device_info()`, or `output_info()` call.
+- Upgrading from 0.3? See the [0.4 migration guide](https://github.com/ra1nty/DXcam/blob/dev/docs/migration-0.4.md).
 
 ### 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`. In one-shot mode it returns `None` if no new frame is available; `camera.grab(new_frame_only=False)` can reuse the last cached frame. During threaded capture, it reads the latest published frame and ignores `new_frame_only`.
 
-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
@@ -87,20 +91,20 @@ camera.is_capturing  # False
 #### Consume the Screen Capture Data
 ```python
 for _ in range(1000):
-    frame = camera.get_latest_frame()  # blocks until a frame is available
+    frame = camera.get_latest_frame()  # waits for the first available frame
 ```
->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 capture thread publishes into a latest-only frame buffer. Once a frame is available, reads return immediately and can return the same timestamp repeatedly. Consumers control their own pacing; compare timestamps when you need only fresh frames. `target_fps` controls the producer, not the frequency of consumer reads.
 
 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.
 After `release()`, the same instance cannot be reused.
+In-flight readers retain their staging surfaces until readout completes, including across stop or output recovery.
 
 ```python
 camera = dxcam.create(output_idx=0, output_color="BGR")
@@ -148,13 +152,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 consume the newest published frame. A surface being read is never overwritten; if no safe write slot is available, capture skips that cycle. Older surfaces are released only after their readers finish.
 
 ```python
-camera = dxcam.create(max_buffer_len=120)  # default is 8
+camera = dxcam.create()
 ```
 
 ### Target FPS
@@ -179,26 +183,37 @@ 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
 import dxcam
+import time
 
 target_fps = 30
 camera = dxcam.create(output_color="BGR")
 camera.start(target_fps=target_fps, video_mode=True)
 
 writer = cv2.VideoWriter(
-    "video.mp4", cv2.VideoWriter_fourcc(*"mp4v"), target_fps, (1920, 1080)
+    "video.mp4", cv2.VideoWriter_fourcc(*"mp4v"), target_fps,
+    (camera.width, camera.height),
 )
-for _ in range(600):
-    writer.write(camera.get_latest_frame())
-
-camera.stop()
-writer.release()
+try:
+    next_frame = time.perf_counter()
+    for _ in range(600):
+        time.sleep(max(0, next_frame - time.perf_counter()))
+        next_frame = time.perf_counter() + 1 / target_fps
+        frame = camera.get_latest_frame()
+        if frame is not None:
+            writer.write(frame)
+finally:
+    camera.release()
+    writer.release()
 ```
 
+Latest-frame reads return immediately once a frame exists. Pace the consumer as
+above to avoid filling the video with repeated reads as fast as Python can run.
+
 ### Capture Backend
 DXcam supports two capture backends:
 - `dxgi` (default): Desktop Duplication API path with broad compatibility.
@@ -216,22 +231,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,7 +258,14 @@ 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
+See the [0.4 development comparison against PyPI 0.3.0](https://github.com/ra1nty/DXcam/blob/dev/benchmarks/capture_comparison.md)
+for measured fresh-frame throughput, frame age, CPU use, and reproducible steps.
+
 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 |
@@ -254,10 +276,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.dev2}/dxcam/__init__.py

@@ -22,9 +22,10 @@ import signal
 import time
 import weakref
 from types import FrameType
+from threading import Lock, RLock
 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
@@ -50,43 +51,22 @@ __all__ = [
 
 # Hide internal factory/signal plumbing from pdoc output.
 __pdoc__: dict[str, bool] = {
-    "Singleton": False,
     "DXFactory": False,
-    "_configure_comtypes_logging": False,
+    "_get_factory": False,
     "_handle_sigterm": False,
     "_install_sigterm_handler": False,
     "__factory": False,
 }
 
 
-def _configure_comtypes_logging() -> None:
-    # Suppress noisy per-frame COM Release debug logs from comtypes internals.
-    logging.getLogger("comtypes").setLevel(logging.INFO)
-    logging.getLogger("comtypes._post_coinit.unknwn").setLevel(logging.INFO)
-
-
-class Singleton(type):
-    """Metaclass that allows exactly one instance per class."""
-
-    _instances = {}
-
-    def __call__(cls, *args: Any, **kwargs: Any) -> Any:
-        if cls not in cls._instances:
-            cls._instances[cls] = super(Singleton, cls).__call__(*args, **kwargs)
-        else:
-            logger.warning("Only 1 instance of %s is allowed.", cls.__name__)
-
-        return cls._instances[cls]
-
-
-class DXFactory(metaclass=Singleton):
+class DXFactory:
     """Factory that owns device/output discovery and camera singletons."""
 
-    _camera_instances: weakref.WeakValueDictionary[
-        tuple[int, int, CaptureBackend], DXCamera
-    ] = weakref.WeakValueDictionary()
-
     def __init__(self) -> None:
+        self._camera_instances: weakref.WeakValueDictionary[
+            tuple[int, int, CaptureBackend], DXCamera
+        ] = weakref.WeakValueDictionary()
+        self._camera_lock = RLock()
         p_adapters = enum_dxgi_adapters()
         self.devices: list[Device] = []
         self.outputs: list[list[Output]] = []
@@ -104,7 +84,7 @@ class DXFactory(metaclass=Singleton):
         output_idx: int | None = None,
         region: Region | None = None,
         output_color: ColorMode = "RGB",
-        max_buffer_len: int = 8,
+        *,
         backend: CaptureBackend = "dxgi",
         processor_backend: ProcessorBackend = "cv2",
     ) -> DXCamera:
@@ -127,41 +107,32 @@ class DXFactory(metaclass=Singleton):
                 )
             output_idx = primary_output_indices[0]
         instance_key = (device_idx, output_idx, backend)
-        existing_camera = self._camera_instances.get(instance_key)
-        if existing_camera is not None and existing_camera.is_released:
-            logger.info(
-                "Dropping released DXCamera instance for device=%s output=%s backend=%s.",
-                device_idx,
-                output_idx,
-                backend,
-            )
-            del self._camera_instances[instance_key]
-            existing_camera = None
-        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.",
-                device_idx,
-                output_idx,
-                backend,
+        with self._camera_lock:
+            existing_camera = self._camera_instances.get(instance_key)
+            if existing_camera is not None and not existing_camera.is_released:
+                logger.warning(
+                    "DXCamera instance already exists for device=%s output=%s "
+                    "backend=%s; returning the existing instance. Call release() "
+                    "before recreating it with new parameters.",
+                    device_idx,
+                    output_idx,
+                    backend,
+                )
+                return existing_camera
+
+            output = self.outputs[device_idx][output_idx]
+            output.update_desc()
+            camera = DXCamera(
+                output=output,
+                device=device,
+                region=region,
+                output_color=output_color,
+                backend=backend,
+                processor_backend=processor_backend,
             )
-            return existing_camera
-
-        output = self.outputs[device_idx][output_idx]
-        output.update_desc()
-        camera = DXCamera(
-            output=output,
-            device=device,
-            region=region,
-            output_color=output_color,
-            max_buffer_len=max_buffer_len,
-            backend=backend,
-            processor_backend=processor_backend,
-        )
-        self._camera_instances[instance_key] = camera
-        time.sleep(0.1)  # Fix for https://github.com/ra1nty/DXcam/issues/31
-        return camera
+            self._camera_instances[instance_key] = camera
+            time.sleep(0.1)  # Fix for https://github.com/ra1nty/DXcam/issues/31
+            return camera
 
     def device_info(self) -> str:
         ret = ""
@@ -181,18 +152,30 @@ class DXFactory(metaclass=Singleton):
         return ret
 
     def clean_up(self) -> None:
-        for _, camera in list(self._camera_instances.items()):
+        with self._camera_lock:
+            cameras = list(self._camera_instances.values())
+        for camera in cameras:
             camera.release()
 
 
-__factory = DXFactory()
-_configure_comtypes_logging()
+__factory: DXFactory | None = None
+_factory_lock = Lock()
+
+
+def _get_factory() -> DXFactory:
+    global __factory
+
+    with _factory_lock:
+        if __factory is None:
+            __factory = DXFactory()
+        return __factory
 
 
 def _handle_sigterm(signum: int, frame: FrameType | None) -> None:
     logger.info("Received SIGTERM; releasing active DXCamera instances.")
     try:
-        __factory.clean_up()
+        if __factory is not None:
+            __factory.clean_up()
     except Exception:
         logger.exception("Failed during DXCamera SIGTERM cleanup.")
 
@@ -213,8 +196,9 @@ def _install_sigterm_handler() -> None:
     if _sigterm_handler_installed:
         return
     try:
-        _previous_sigterm_handler = signal.getsignal(signal.SIGTERM)
+        previous = signal.getsignal(signal.SIGTERM)
         signal.signal(signal.SIGTERM, _handle_sigterm)
+        _previous_sigterm_handler = previous
         _sigterm_handler_installed = True
     except (ValueError, AttributeError):
         # ValueError: called outside the main thread.
@@ -227,7 +211,7 @@ def create(
     output_idx: int | None = None,
     region: Region | None = None,
     output_color: ColorMode = "RGB",
-    max_buffer_len: int = 8,
+    *,
     backend: CaptureBackend = "dxgi",
     processor_backend: ProcessorBackend = "cv2",
 ) -> DXCamera:
@@ -239,11 +223,12 @@ 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.
         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.
@@ -259,12 +244,11 @@ def create(
         >>> cam.release()
     """
     _install_sigterm_handler()
-    return __factory.create(
+    return _get_factory().create(
         device_idx=device_idx,
         output_idx=output_idx,
         region=region,
         output_color=output_color,
-        max_buffer_len=max_buffer_len,
         backend=backend,
         processor_backend=processor_backend,
     )
@@ -277,7 +261,7 @@ def device_info() -> str:
         >>> import dxcam
         >>> print(dxcam.device_info())
     """
-    return __factory.device_info()
+    return _get_factory().device_info()
 
 
 def output_info() -> str:
@@ -287,4 +271,4 @@ def output_info() -> str:
         >>> import dxcam
         >>> print(dxcam.output_info())
     """
-    return __factory.output_info()
+    return _get_factory().output_info()

{dxcam-0.3.0.dev1 → dxcam-0.4.0.dev2}/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.dev2}/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.dev2/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.dev2/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)