dxcam 0.1.0.dev2__tar.gz → 0.2.0__tar.gz

dxcam-0.2.0/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include dxcam/processor *.pyx

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dxcam
-Version: 0.1.0.dev2
+Version: 0.2.0
 Summary: A Python high-performance screenshot library for Windows using Desktop Duplication API
 Author: ra1nty
 License-Expression: MIT
@@ -11,9 +11,11 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: Microsoft :: Windows
 Classifier: Operating System :: Microsoft :: Windows :: Windows 10
 Classifier: Operating System :: Microsoft :: Windows :: Windows 11
@@ -27,6 +29,18 @@ Requires-Dist: comtypes
 Requires-Dist: numpy
 Provides-Extra: cv2
 Requires-Dist: opencv-python; extra == "cv2"
+Provides-Extra: cython
+Requires-Dist: Cython==3.1.1; extra == "cython"
+Provides-Extra: winrt
+Requires-Dist: winrt-runtime>=3.2.1; extra == "winrt"
+Requires-Dist: winrt-Windows.Foundation>=3.2.1; extra == "winrt"
+Requires-Dist: winrt-Windows.Foundation.Collections>=3.2.1; extra == "winrt"
+Requires-Dist: winrt-Windows.Graphics>=3.2.1; extra == "winrt"
+Requires-Dist: winrt-Windows.Graphics.Capture>=3.2.1; extra == "winrt"
+Requires-Dist: winrt-Windows.Graphics.Capture.Interop>=3.2.1; extra == "winrt"
+Requires-Dist: winrt-Windows.Graphics.DirectX>=3.2.1; extra == "winrt"
+Requires-Dist: winrt-Windows.Graphics.DirectX.Direct3D11>=3.2.1; extra == "winrt"
+Requires-Dist: winrt-Windows.Graphics.DirectX.Direct3D11.Interop>=3.2.1; extra == "winrt"
 Dynamic: license-file
 
 # **DXcam**
@@ -39,42 +53,41 @@ camera = dxcam.create()
 frame = camera.grab()
 ```
 
+> **Live API Docs:** [https://ra1nty.github.io/DXcam/](https://ra1nty.github.io/DXcam/)
+
 ## Introduction
 DXcam is a high-performance python screenshot and capture library for Windows based on the Desktop Duplication API.
 It is designed for low-latency, high-FPS capture pipelines (including full-screen Direct3D applications).
 
 Compared with common Python alternatives, DXcam focuses on:
-- Higher capture throughput
+- Higher capture throughput (240+fps on 1080p)
 - Stable capture for full-screen exclusive Direct3D apps
-- Correct handling of scaled/stretched outputs
-- Better FPS pacing for continuous/video capture
+- Better FPS pacing for continuous video capture
+- Support DXGI / Windows Graphics Capture dual backend
+- Seamless integration for AI Agent / Computer Vision use cases.
 
 ## Installation
 ### From PyPI (pip)
-Recommended (with OpenCV):
-```bash
-pip install "dxcam[cv2]"
-```
-
 Minimal install:
 ```bash
 pip install dxcam
 ```
 
-### From source (uv)
+Full feature: (includes OpenCV-based color conversion, WinRT capture backend support:):
 ```bash
-uv sync
-# include OpenCV
-uv sync --extra cv2
+pip install "dxcam[cv2,winrt]"
 ```
 
-### Dev environment (uv + ruff + ty)
-```bash
-uv venv --python 3.11 .venv
-uv sync --dev
-uv run ruff check dxcam
-uv run ty check dxcam
-```
+Notes:
+- Official Windows wheels are built for CPython `3.10` to `3.14`.
+- Binary wheels include the Cython kernels used by processor backends.
+
+### From source
+Please refer to [CONTRIBUTING](CONTRIBUTING.md).
+
+### Contributing / Dev
+Contributions are welcome!
+Development setup and contributor workflow are documented in [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Usage
 Each output (monitor) is associated with one `DXCamera` instance.
@@ -84,13 +97,21 @@ import dxcam
 camera = dxcam.create()  # primary output on device 0
 ```
 
+To specify backend:
+```python
+camera = dxcam.create(
+    backend="dxgi", # default Desktop Duplication backend
+    processor_backend="cv2" # default OpenCV processor
+)
+```
+
 ### Screenshot
 ```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 (for backward compatibility); 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.
+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.
 
 To capture a region:
 ```python
@@ -113,14 +134,16 @@ 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 polling the rendered new frames and store in an in-memory frame buffer. The blocking / video_mode behavior is designed with downstream video recording / machine learning applications in mind. 
+>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.
 
 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.
+> When `start()` capture is running, calling `grab()` reads from the in-memory ring buffer instead of directly polling DXGI.
+
+**Full API Docs:** [https://ra1nty.github.io/DXcam/](https://ra1nty.github.io/DXcam/)
 
 ## Advanced Usage and Remarks
 ### Multiple monitors / GPUs
@@ -153,8 +176,8 @@ Supported modes: `"RGB"`, `"RGBA"`, `"BGR"`, `"BGRA"`, `"GRAY"`.
 
 Notes:
 - Data is returned as `numpy.ndarray`.
-- `BGRA` does not require OpenCV.
-- Other color modes conversion require OpenCV (`dxcam[cv2]`).
+- `BGRA` does not require OpenCV and is the leanest dependency path.
+- `RGB`, `BGR`, `RGBA`, `GRAY` require conversion (`cv2` or compiled `numpy` backend).
 
 ### Frame Buffer
 DXcam uses a fixed-size ring buffer in-memory. New frames overwrite old frames when full.
@@ -181,7 +204,8 @@ frame, ts = camera.get_latest_frame(with_timestamp=True)
 camera.stop()
 ```
 
-This value is directly from `DXGI_OUTDUPL_FRAME_INFO.LastPresentTime`, which can be used to calculate PTS / achieve VFR in video capture.
+For `backend="dxgi"`, this value comes from `DXGI_OUTDUPL_FRAME_INFO.LastPresentTime`.
+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.
@@ -204,8 +228,52 @@ camera.stop()
 writer.release()
 ```
 
+### Capture Backend
+DXcam supports two capture backends:
+- `dxgi` (default): Desktop Duplication API path with broad compatibility.
+- `winrt`: Windows Graphics Capture path.
+
+Use it like this:
+```python
+camera = dxcam.create(backend="dxgi")
+camera = dxcam.create(backend="winrt")
+```
+
+Guideline:
+- If you need cursor rendering, use `winrt`.
+- Start with `dxgi` for most workloads, especially one-shot grab.
+- 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:
+- 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)
+
+Use it like this:
+```python
+camera = dxcam.create(processor_backend="cv2")
+camera = dxcam.create(processor_backend="numpy")
+```
+
+Official Windows wheels already include the compiled NumPy kernels.
+
+Only for source installs:
+```bash
+set DXCAM_BUILD_CYTHON=1
+pip install -e .[cython] --no-build-isolation
+```
+
+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.
+
 ### Safely Releasing Resources
-`release()` stops capture, frees buffers, and releases DXGI resources.
+`release()` stops capture, frees buffers, and releases capture resources.
 After `release()`, the same instance cannot be reused.
 
 ```python
@@ -230,6 +298,13 @@ The benchmark is across 5 runs, with a light-moderate usage on my PC (5900X + 30
 | 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  |
 
+Processor backend comparison helper:
+```bash
+python benchmarks/dxcam_processor_compare.py --backend dxgi --target-fps 120 --target-frames 1000
+python benchmarks/dxcam_capture.py --backend dxgi --processor-backend numpy
+python benchmarks/numpy_processor_micro.py --width 3840 --height 2160 --modes RGB --variants process into --processor-backends cv2 numpy
+```
+
 
 ## Work Referenced
 

dxcam-0.1.0.dev2/PKG-INFO → dxcam-0.2.0/README.md

@@ -1,34 +1,3 @@
-Metadata-Version: 2.4
-Name: dxcam
-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 :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Operating System :: Microsoft :: Windows
-Classifier: Operating System :: Microsoft :: Windows :: Windows 10
-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.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: comtypes
-Requires-Dist: numpy
-Provides-Extra: cv2
-Requires-Dist: opencv-python; extra == "cv2"
-Dynamic: license-file
-
 # **DXcam**
 > ***Fast Python Screen Capture for Windows - Updated 2026***
 
@@ -39,42 +8,41 @@ camera = dxcam.create()
 frame = camera.grab()
 ```
 
+> **Live API Docs:** [https://ra1nty.github.io/DXcam/](https://ra1nty.github.io/DXcam/)
+
 ## Introduction
 DXcam is a high-performance python screenshot and capture library for Windows based on the Desktop Duplication API.
 It is designed for low-latency, high-FPS capture pipelines (including full-screen Direct3D applications).
 
 Compared with common Python alternatives, DXcam focuses on:
-- Higher capture throughput
+- Higher capture throughput (240+fps on 1080p)
 - Stable capture for full-screen exclusive Direct3D apps
-- Correct handling of scaled/stretched outputs
-- Better FPS pacing for continuous/video capture
+- Better FPS pacing for continuous video capture
+- Support DXGI / Windows Graphics Capture dual backend
+- Seamless integration for AI Agent / Computer Vision use cases.
 
 ## Installation
 ### From PyPI (pip)
-Recommended (with OpenCV):
-```bash
-pip install "dxcam[cv2]"
-```
-
 Minimal install:
 ```bash
 pip install dxcam
 ```
 
-### From source (uv)
+Full feature: (includes OpenCV-based color conversion, WinRT capture backend support:):
 ```bash
-uv sync
-# include OpenCV
-uv sync --extra cv2
+pip install "dxcam[cv2,winrt]"
 ```
 
-### Dev environment (uv + ruff + ty)
-```bash
-uv venv --python 3.11 .venv
-uv sync --dev
-uv run ruff check dxcam
-uv run ty check dxcam
-```
+Notes:
+- Official Windows wheels are built for CPython `3.10` to `3.14`.
+- Binary wheels include the Cython kernels used by processor backends.
+
+### From source
+Please refer to [CONTRIBUTING](CONTRIBUTING.md).
+
+### Contributing / Dev
+Contributions are welcome!
+Development setup and contributor workflow are documented in [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Usage
 Each output (monitor) is associated with one `DXCamera` instance.
@@ -84,13 +52,21 @@ import dxcam
 camera = dxcam.create()  # primary output on device 0
 ```
 
+To specify backend:
+```python
+camera = dxcam.create(
+    backend="dxgi", # default Desktop Duplication backend
+    processor_backend="cv2" # default OpenCV processor
+)
+```
+
 ### Screenshot
 ```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 (for backward compatibility); 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.
+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.
 
 To capture a region:
 ```python
@@ -113,14 +89,16 @@ 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 polling the rendered new frames and store in an in-memory frame buffer. The blocking / video_mode behavior is designed with downstream video recording / machine learning applications in mind. 
+>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.
 
 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.
+> When `start()` capture is running, calling `grab()` reads from the in-memory ring buffer instead of directly polling DXGI.
+
+**Full API Docs:** [https://ra1nty.github.io/DXcam/](https://ra1nty.github.io/DXcam/)
 
 ## Advanced Usage and Remarks
 ### Multiple monitors / GPUs
@@ -153,8 +131,8 @@ Supported modes: `"RGB"`, `"RGBA"`, `"BGR"`, `"BGRA"`, `"GRAY"`.
 
 Notes:
 - Data is returned as `numpy.ndarray`.
-- `BGRA` does not require OpenCV.
-- Other color modes conversion require OpenCV (`dxcam[cv2]`).
+- `BGRA` does not require OpenCV and is the leanest dependency path.
+- `RGB`, `BGR`, `RGBA`, `GRAY` require conversion (`cv2` or compiled `numpy` backend).
 
 ### Frame Buffer
 DXcam uses a fixed-size ring buffer in-memory. New frames overwrite old frames when full.
@@ -181,7 +159,8 @@ frame, ts = camera.get_latest_frame(with_timestamp=True)
 camera.stop()
 ```
 
-This value is directly from `DXGI_OUTDUPL_FRAME_INFO.LastPresentTime`, which can be used to calculate PTS / achieve VFR in video capture.
+For `backend="dxgi"`, this value comes from `DXGI_OUTDUPL_FRAME_INFO.LastPresentTime`.
+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.
@@ -204,8 +183,52 @@ camera.stop()
 writer.release()
 ```
 
+### Capture Backend
+DXcam supports two capture backends:
+- `dxgi` (default): Desktop Duplication API path with broad compatibility.
+- `winrt`: Windows Graphics Capture path.
+
+Use it like this:
+```python
+camera = dxcam.create(backend="dxgi")
+camera = dxcam.create(backend="winrt")
+```
+
+Guideline:
+- If you need cursor rendering, use `winrt`.
+- Start with `dxgi` for most workloads, especially one-shot grab.
+- 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:
+- 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)
+
+Use it like this:
+```python
+camera = dxcam.create(processor_backend="cv2")
+camera = dxcam.create(processor_backend="numpy")
+```
+
+Official Windows wheels already include the compiled NumPy kernels.
+
+Only for source installs:
+```bash
+set DXCAM_BUILD_CYTHON=1
+pip install -e .[cython] --no-build-isolation
+```
+
+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.
+
 ### Safely Releasing Resources
-`release()` stops capture, frees buffers, and releases DXGI resources.
+`release()` stops capture, frees buffers, and releases capture resources.
 After `release()`, the same instance cannot be reused.
 
 ```python
@@ -230,6 +253,13 @@ The benchmark is across 5 runs, with a light-moderate usage on my PC (5900X + 30
 | 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  |
 
+Processor backend comparison helper:
+```bash
+python benchmarks/dxcam_processor_compare.py --backend dxgi --target-fps 120 --target-frames 1000
+python benchmarks/dxcam_capture.py --backend dxgi --processor-backend numpy
+python benchmarks/numpy_processor_micro.py --width 3840 --height 2160 --modes RGB --variants process into --processor-backends cv2 numpy
+```
+
 
 ## Work Referenced
 

{dxcam-0.1.0.dev2 → dxcam-0.2.0}/dxcam/__init__.py

@@ -1,3 +1,20 @@
+"""Public DXcam API.
+
+Quick start:
+    >>> import dxcam
+    >>> cam = dxcam.create()
+    >>> frame = cam.grab()
+    >>> cam.release()
+
+Threaded capture:
+    >>> import dxcam
+    >>> cam = dxcam.create(backend="dxgi")
+    >>> cam.start(target_fps=60)
+    >>> frame = cam.get_latest_frame()
+    >>> cam.stop()
+    >>> cam.release()
+"""
+
 from __future__ import annotations
 
 import logging
@@ -7,8 +24,10 @@ import weakref
 from types import FrameType
 from typing import Any, Callable, cast
 
+from dxcam.core.backend import normalize_backend_name
 from dxcam.dxcam import DXCamera, Output, Device
-from dxcam.types import ColorMode, Region
+from dxcam.processor import normalize_processor_backend_name
+from dxcam.types import CaptureBackend, ColorMode, ProcessorBackend, Region
 from dxcam.util.io import (
     enum_dxgi_adapters,
     get_output_metadata,
@@ -18,6 +37,27 @@ logger = logging.getLogger(__name__)
 _sigterm_handler_installed = False
 _previous_sigterm_handler: int | Callable[[int, FrameType | None], Any] | None = None
 
+__all__ = [
+    "DXCamera",
+    "CaptureBackend",
+    "ColorMode",
+    "ProcessorBackend",
+    "Region",
+    "create",
+    "device_info",
+    "output_info",
+]
+
+# Hide internal factory/signal plumbing from pdoc output.
+__pdoc__: dict[str, bool] = {
+    "Singleton": False,
+    "DXFactory": False,
+    "_configure_comtypes_logging": 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.
@@ -42,7 +82,7 @@ class Singleton(type):
 class DXFactory(metaclass=Singleton):
     """Factory that owns device/output discovery and camera singletons."""
 
-    _camera_instances: weakref.WeakValueDictionary[tuple[int, int], DXCamera] = (
+    _camera_instances: weakref.WeakValueDictionary[tuple[int, int, CaptureBackend], DXCamera] = (
         weakref.WeakValueDictionary()
     )
 
@@ -65,7 +105,11 @@ class DXFactory(metaclass=Singleton):
         region: Region | None = None,
         output_color: ColorMode = "RGB",
         max_buffer_len: int = 64,
+        backend: CaptureBackend = "dxgi",
+        processor_backend: ProcessorBackend = "cv2",
     ) -> DXCamera:
+        backend = normalize_backend_name(str(backend))
+        processor_backend = normalize_processor_backend_name(str(processor_backend))
         device = self.devices[device_idx]
         if output_idx is None:
             # Select Primary Output
@@ -80,23 +124,25 @@ class DXFactory(metaclass=Singleton):
             if not primary_output_indices:
                 raise RuntimeError(f"No primary output found for device index {device_idx}")
             output_idx = primary_output_indices[0]
-        instance_key = (device_idx, output_idx)
+        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.",
+                "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; "
+                "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,
             )
             return existing_camera
 
@@ -108,6 +154,8 @@ class DXFactory(metaclass=Singleton):
             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
@@ -178,7 +226,36 @@ def create(
     region: Region | None = None,
     output_color: ColorMode = "RGB",
     max_buffer_len: int = 64,
+    backend: CaptureBackend = "dxgi",
+    processor_backend: ProcessorBackend = "cv2",
 ) -> DXCamera:
+    """Create or return a singleton camera for a device/output/backend tuple.
+
+    Args:
+        device_idx: DXGI adapter index.
+        output_idx: Output index on the selected adapter. ``None`` chooses
+            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.
+
+    Returns:
+        A :class:`dxcam.dxcam.DXCamera` instance.
+
+    Example:
+        >>> import dxcam
+        >>> cam = dxcam.create(
+        ...     output_color="BGR",
+        ...     backend="winrt",
+        ...     processor_backend="cv2",
+        ... )
+        >>> frame = cam.grab()
+        >>> cam.release()
+    """
     _install_sigterm_handler()
     return __factory.create(
         device_idx=device_idx,
@@ -186,12 +263,26 @@ def create(
         region=region,
         output_color=output_color,
         max_buffer_len=max_buffer_len,
+        backend=backend,
+        processor_backend=processor_backend,
     )
 
 
 def device_info() -> str:
+    """Return a formatted list of detected DXGI adapters.
+
+    Example:
+        >>> import dxcam
+        >>> print(dxcam.device_info())
+    """
     return __factory.device_info()
 
 
 def output_info() -> str:
+    """Return a formatted list of detected outputs for each adapter.
+
+    Example:
+        >>> import dxcam
+        >>> print(dxcam.output_info())
+    """
     return __factory.output_info()

{dxcam-0.1.0.dev2 → dxcam-0.2.0}/dxcam/_libs/d3d11.py

@@ -212,6 +212,16 @@ class ID3D11DeviceContext(ID3D11DeviceChild):
     ]
 
 
+class ID3D11Multithread(comtypes.IUnknown):
+    _iid_ = comtypes.GUID("{9b7e4e00-342c-4106-a19f-4f2704f689f0}")
+    _methods_ = [
+        comtypes.STDMETHOD(None, "Enter"),
+        comtypes.STDMETHOD(None, "Leave"),
+        comtypes.STDMETHOD(wintypes.BOOL, "SetMultithreadProtected", [wintypes.BOOL]),
+        comtypes.STDMETHOD(wintypes.BOOL, "GetMultithreadProtected"),
+    ]
+
+
 class ID3D11Device(comtypes.IUnknown):
     _iid_ = comtypes.GUID("{db6f6ddb-ac77-4e88-8253-819df9bbf140}")
     _methods_ = [

{dxcam-0.1.0.dev2 → dxcam-0.2.0}/dxcam/_libs/dxgi.py

@@ -101,6 +101,17 @@ class IDXGISurface(IDXGIDeviceSubObject):
     ]
 
 
+class IDXGIDevice(IDXGIObject):
+    _iid_ = comtypes.GUID("{54ec77fa-1377-44e6-8c32-88fd5f44c84c}")
+    _methods_ = [
+        comtypes.STDMETHOD(comtypes.HRESULT, "GetAdapter"),
+        comtypes.STDMETHOD(comtypes.HRESULT, "CreateSurface"),
+        comtypes.STDMETHOD(comtypes.HRESULT, "QueryResourceResidency"),
+        comtypes.STDMETHOD(comtypes.HRESULT, "SetGPUThreadPriority"),
+        comtypes.STDMETHOD(comtypes.HRESULT, "GetGPUThreadPriority"),
+    ]
+
+
 class IDXGIOutputDuplication(IDXGIObject):
     _iid_ = comtypes.GUID("{191cfac3-a341-470d-b26e-a864f428319c}")
     _methods_ = [