rapidshot 2.2.0__tar.gz → 2.3.0__tar.gz

{rapidshot-2.2.0/rapidshot.egg-info → rapidshot-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rapidshot
-Version: 2.2.0
+Version: 2.3.0
 Summary: A high-performance screencapture library for Windows using Desktop Duplication API
 Home-page: https://github.com/Zaatra/Rapidshot
 Author: Rapidshot Contributors
@@ -149,8 +149,9 @@ built around have no column here because the other libraries have no equivalent:
 
 - **`grab_frame()`** hands back a GPU-resident frame in 0.17–0.21 ms that never
   crosses to system memory.
-- **The GPU tensor path** turns a frame into NCHW float32 in one dispatch, 2 µs of
-  calling-thread time.
+- **The GPU tensor path** turns a frame into model-ready NCHW float32 in one
+  dispatch — 0.075 ms for a 2560×1600 frame, against 3.1 ms to do the same work
+  on the CPU — and the result stays in VRAM, where CUDA or DirectML can read it.
 - **Cross-adapter transfer** moves a frame to the discrete GPU on hybrid laptops,
   which Desktop Duplication cannot capture from at all.
 - **Dirty-rect metadata**, so a consumer can skip regions that did not change.
@@ -196,6 +197,10 @@ rewritten.
   the memory system can move, and byte-identical to the pure-Python path
 - **Only process what changed**: frames carry the compositor's dirty-rect
   metadata, typically under 1% of the screen on a normal desktop
+- **Feed CUDA directly**: the GPU tensor exposes a shared NT handle, so CuPy or
+  PyTorch can read it in place via `cudaImportExternalMemory` — capture to
+  `cupy.ndarray` with no CPU round-trip. One dispatch costs **0.075 ms** at
+  2560×1600 → 640×640, against 3.1 ms for the same work on the CPU
 - **Hybrid GPU laptops**: move a frame to the discrete GPU that Desktop
   Duplication cannot capture from
 - **Multi-backend support**: NumPy, PIL, and CUDA/CuPy backends
@@ -206,8 +211,9 @@ rewritten.
 - **Flexible output formats**: RGB, RGBA, BGR, BGRA, and grayscale support
 - **Region-based capture**: Efficient capture of specific screen regions
 - **Rotation handling**: Automatic handling of rotated displays
-- **Actionable diagnostics**: headless machines and hybrid GPU setups are
-  detected and explained rather than failing opaquely
+- **Actionable diagnostics**: headless machines, hybrid GPU setups, locked
+  workstations, UAC prompts and Session 0 services are detected and named
+  rather than failing opaquely
 
 ## Installation
 
@@ -319,14 +325,24 @@ writer.release()
 ### NVIDIA GPU Acceleration
 
 ```python
-# Create a ScreenCapture instance with NVIDIA GPU acceleration
-screencapture = rapidshot.create(nvidia_gpu=True)
+# Frames come back as cupy.ndarray, converted on the device
+screencapture = rapidshot.create(output_color="RGB", nvidia_gpu=True)
 
-# Screenshots will be processed on the GPU for improved performance
-frame = screencapture.grab()
-frame.release()
+frame = screencapture.grab()        # cupy.ndarray, stays in VRAM
 ```
 
+> **Note:** unlike the CPU path, `nvidia_gpu=True` returns a bare
+> `cupy.ndarray` rather than a pooled buffer, so there is no `.release()` to
+> call — CuPy's allocator owns it. `pool_size_frames` does not apply.
+
+Colour conversion runs in CuPy on the GPU and is **byte-identical** to the CPU
+path, so turning `nvidia_gpu` on changes no pixel. OpenCV is not required.
+
+> **Fixed in 2.3.0:** before this release, any `output_color` other than
+> `"BGRA"` silently returned an unconverted 4-channel BGRA array — wrong shape
+> and wrong channel order, reported as success. Conversion went through OpenCV,
+> which is not a dependency, and the failure was swallowed.
+
 ### Cursor Capture
 
 RapidShot provides comprehensive cursor capture capabilities, allowing you to track cursor position, visibility, and shape in your screen captures.
@@ -682,6 +698,7 @@ with screencapture.grab_frame() as frame:
     print(pre.shape)                        # (1, 3, 640, 640)
     resource = pre.output_resource_address  # ID3D12Resource*
     gpu_va = pre.output_gpu_address         # GPU virtual address
+    handle = pre.shared_output_handle       # shared NT handle, for CUDA etc.
 ```
 
 `process()` resizes, normalises, converts BGRA→RGB and transposes to NCHW in a
@@ -690,6 +707,49 @@ frame**; here it is one dispatch and the result stays in VRAM. Optional
 arguments cover the usual normalisation ranges (`scale=2.0, bias=-1.0` for
 −1..1) and channel order (`bgr=True`).
 
+#### Reading the tensor from CuPy / CUDA
+
+`shared_output_handle` is a shared NT handle for the tensor, which CUDA imports
+with `cudaImportExternalMemory` — so the frame reaches a CUDA consumer without
+ever touching the CPU. **`examples/gpu_tensor_to_cupy.py` is a complete, working
+version** of the ~60 lines of `ctypes` this takes; it verifies the resulting
+`cupy.ndarray` is byte-identical to a readback of the same dispatch.
+
+`CudaTensor` is defined in `examples/gpu_tensor_to_cupy.py`, not exported by
+the package — copy it into your project rather than importing it:
+
+```python
+with CudaTensor(pre, (1, 3, 640, 640)) as view:
+    tensor = view.array                          # a cupy.ndarray in VRAM
+    while capturing:
+        with screencapture.grab_frame() as frame:   # a *new* frame each pass
+            if frame is None:
+                continue                         # nothing changed on screen
+            view.sync()                          # queued CUDA work must finish
+            pre.process(frame)                   # overwrites tensor's buffer
+        model(tensor)
+```
+
+Note the fresh `grab_frame()` inside the loop. The preprocessor and the CUDA
+import are built once and reused; the *frame* is not — a released frame raises
+`FrameReleasedError`, and reusing a live one just re-processes the same image.
+Releasing it before `model()` also matters: DXGI cannot acquire the next frame
+while a reference to the previous surface is outstanding.
+
+`sync()` is not optional. `process()` waits on the D3D12 fence but knows
+nothing about CUDA work you have queued against the same memory, so a kernel
+still reading the tensor when the next dispatch lands sees a half-overwritten
+frame — with no error, just wrong numbers.
+
+Keep the `CudaTensor` for as long as you use the array: it owns the CUDA
+import and the preprocessor that owns the VRAM. On a machine with more than
+one CUDA device, pass `device=N` — the tensor can only be imported by the
+device that owns the adapter which captured the frame.
+
+The import is paid once. After that `pre.process(frame)` overwrites the same
+buffer the CuPy array points at, so a capture loop pays nothing per frame to
+keep the view.
+
 **Where Rapidshot stops.** The output is an `ID3D12Resource` on the DirectML
 device — exactly what ONNX Runtime's DirectML provider consumes. Rapidshot
 deliberately does **not** bind it to a session: that would couple this library
@@ -826,6 +886,25 @@ What is measured, reproducibly, is the per-frame cost of RapidShot's own paths
 The first three are synthetic and deterministic: they move when the library
 changes and not otherwise, which is why they are the ones on the badges above.
 
+**Second machine, NVIDIA RTX 4060 Laptop** (`benchmarks/baseline-rtx4060.json`,
+P-core-pinned, 1920×1080 synthetic source, minimums):
+
+| Path | Per frame |
+| --- | --- |
+| Colour conversion, BGRA→RGB | 0.198 ms |
+| Colour conversion, BGRA→GRAY | 0.252 ms |
+| CPU resize + normalise + NCHW | 3.09 ms |
+| **GPU dispatch → NCHW tensor, D3D12** | **0.070 ms** (2560×1600 source) |
+| GPU dispatch + forced readback | 2.20 ms |
+| `grab_frame()` — texture stays on the GPU | 0.099–0.156 ms |
+
+Cross-machine comparison is not valid — different CPU, GPU, panel and, on two
+rows, different code. Both recordings are kept so each answers for its own
+machine.
+
+Sustained-load check: 211,726 frames of `grab_frame()` → GPU tensor in 12
+minutes, zero errors, VRAM flat, no throughput decay.
+
 **The last two are not stable measurements and should not be quoted as single
 numbers.** `grab()` converts only the parts of the frame that changed, so its
 cost tracks what is happening on screen; across seven recordings on unchanged
@@ -851,11 +930,42 @@ breakdown and how each figure is measured.
   only for the optional CuPy acceleration.
 - **RAM:** 8 GB+ (depending on the resolution and number of screencapture instances used)
 
+### Tested configurations
+
+Nothing in RapidShot branches on GPU vendor. This is what has actually been
+run, which is not the same claim:
+
+| Configuration | State |
+| --- | --- |
+| Intel iGPU, single adapter | Verified |
+| NVIDIA dGPU, single adapter, native extension built | Verified |
+| NVIDIA dGPU, single adapter, no extension | Verified |
+| Any AMD GPU | **Not tested** |
+| Hybrid / switchable graphics (Optimus, AMD) | **Not tested** |
+| Headless with a virtual display | **Not tested** |
+
+CuPy is the only NVIDIA-bound feature, because CUDA is; `nvidia_gpu=True` falls
+back to the CPU processor when CuPy is unavailable. AMD and Intel consumers
+reach the same GPU tensor through DirectML via `output_resource_address`.
+
 ### Troubleshooting
 
 - **ImportError with CuPy:** Ensure you have compatible CUDA drivers installed.
-- **Black screens when capturing:** Verify the application isn't running in exclusive fullscreen mode.
+  `pip install cupy-cuda13x[ctk]` installs no headers against `cuda-toolkit`
+  13.3.x and CuPy then fails at its first JIT; use
+  `pip install "cuda-toolkit[cudart,nvrtc]==13.2.*"` instead.
+- **"Desktop duplication was denied":** the message names the cause. A
+  non-input desktop, a locked workstation, an open UAC prompt and a Session 0
+  service cannot capture the user's screen; protected (HDCP/DRM) content is a
+  separate case and is reported as such.
+- **Black screens when capturing:** protected content is blanked by the OS —
+  check `frame.protected_content`. Exclusive fullscreen is handled: capture
+  detects the transition, rebuilds, and continues.
 - **Low performance:** Experiment with different backends (NUMPY vs. CUPY) to optimize performance.
+- **Unstable benchmark numbers:** on a hybrid P-core/E-core CPU, pin the
+  process to the performance cores. `benchmarks/perf_suite.py` does this
+  itself; unpinned it reported false regressions up to 2.57× against
+  unchanged code.
 
 ## Contributing
 

{rapidshot-2.2.0 → rapidshot-2.3.0}/README.md

@@ -83,8 +83,9 @@ built around have no column here because the other libraries have no equivalent:
 
 - **`grab_frame()`** hands back a GPU-resident frame in 0.17–0.21 ms that never
   crosses to system memory.
-- **The GPU tensor path** turns a frame into NCHW float32 in one dispatch, 2 µs of
-  calling-thread time.
+- **The GPU tensor path** turns a frame into model-ready NCHW float32 in one
+  dispatch — 0.075 ms for a 2560×1600 frame, against 3.1 ms to do the same work
+  on the CPU — and the result stays in VRAM, where CUDA or DirectML can read it.
 - **Cross-adapter transfer** moves a frame to the discrete GPU on hybrid laptops,
   which Desktop Duplication cannot capture from at all.
 - **Dirty-rect metadata**, so a consumer can skip regions that did not change.
@@ -130,6 +131,10 @@ rewritten.
   the memory system can move, and byte-identical to the pure-Python path
 - **Only process what changed**: frames carry the compositor's dirty-rect
   metadata, typically under 1% of the screen on a normal desktop
+- **Feed CUDA directly**: the GPU tensor exposes a shared NT handle, so CuPy or
+  PyTorch can read it in place via `cudaImportExternalMemory` — capture to
+  `cupy.ndarray` with no CPU round-trip. One dispatch costs **0.075 ms** at
+  2560×1600 → 640×640, against 3.1 ms for the same work on the CPU
 - **Hybrid GPU laptops**: move a frame to the discrete GPU that Desktop
   Duplication cannot capture from
 - **Multi-backend support**: NumPy, PIL, and CUDA/CuPy backends
@@ -140,8 +145,9 @@ rewritten.
 - **Flexible output formats**: RGB, RGBA, BGR, BGRA, and grayscale support
 - **Region-based capture**: Efficient capture of specific screen regions
 - **Rotation handling**: Automatic handling of rotated displays
-- **Actionable diagnostics**: headless machines and hybrid GPU setups are
-  detected and explained rather than failing opaquely
+- **Actionable diagnostics**: headless machines, hybrid GPU setups, locked
+  workstations, UAC prompts and Session 0 services are detected and named
+  rather than failing opaquely
 
 ## Installation
 
@@ -253,14 +259,24 @@ writer.release()
 ### NVIDIA GPU Acceleration
 
 ```python
-# Create a ScreenCapture instance with NVIDIA GPU acceleration
-screencapture = rapidshot.create(nvidia_gpu=True)
+# Frames come back as cupy.ndarray, converted on the device
+screencapture = rapidshot.create(output_color="RGB", nvidia_gpu=True)
 
-# Screenshots will be processed on the GPU for improved performance
-frame = screencapture.grab()
-frame.release()
+frame = screencapture.grab()        # cupy.ndarray, stays in VRAM
 ```
 
+> **Note:** unlike the CPU path, `nvidia_gpu=True` returns a bare
+> `cupy.ndarray` rather than a pooled buffer, so there is no `.release()` to
+> call — CuPy's allocator owns it. `pool_size_frames` does not apply.
+
+Colour conversion runs in CuPy on the GPU and is **byte-identical** to the CPU
+path, so turning `nvidia_gpu` on changes no pixel. OpenCV is not required.
+
+> **Fixed in 2.3.0:** before this release, any `output_color` other than
+> `"BGRA"` silently returned an unconverted 4-channel BGRA array — wrong shape
+> and wrong channel order, reported as success. Conversion went through OpenCV,
+> which is not a dependency, and the failure was swallowed.
+
 ### Cursor Capture
 
 RapidShot provides comprehensive cursor capture capabilities, allowing you to track cursor position, visibility, and shape in your screen captures.
@@ -616,6 +632,7 @@ with screencapture.grab_frame() as frame:
     print(pre.shape)                        # (1, 3, 640, 640)
     resource = pre.output_resource_address  # ID3D12Resource*
     gpu_va = pre.output_gpu_address         # GPU virtual address
+    handle = pre.shared_output_handle       # shared NT handle, for CUDA etc.
 ```
 
 `process()` resizes, normalises, converts BGRA→RGB and transposes to NCHW in a
@@ -624,6 +641,49 @@ frame**; here it is one dispatch and the result stays in VRAM. Optional
 arguments cover the usual normalisation ranges (`scale=2.0, bias=-1.0` for
 −1..1) and channel order (`bgr=True`).
 
+#### Reading the tensor from CuPy / CUDA
+
+`shared_output_handle` is a shared NT handle for the tensor, which CUDA imports
+with `cudaImportExternalMemory` — so the frame reaches a CUDA consumer without
+ever touching the CPU. **`examples/gpu_tensor_to_cupy.py` is a complete, working
+version** of the ~60 lines of `ctypes` this takes; it verifies the resulting
+`cupy.ndarray` is byte-identical to a readback of the same dispatch.
+
+`CudaTensor` is defined in `examples/gpu_tensor_to_cupy.py`, not exported by
+the package — copy it into your project rather than importing it:
+
+```python
+with CudaTensor(pre, (1, 3, 640, 640)) as view:
+    tensor = view.array                          # a cupy.ndarray in VRAM
+    while capturing:
+        with screencapture.grab_frame() as frame:   # a *new* frame each pass
+            if frame is None:
+                continue                         # nothing changed on screen
+            view.sync()                          # queued CUDA work must finish
+            pre.process(frame)                   # overwrites tensor's buffer
+        model(tensor)
+```
+
+Note the fresh `grab_frame()` inside the loop. The preprocessor and the CUDA
+import are built once and reused; the *frame* is not — a released frame raises
+`FrameReleasedError`, and reusing a live one just re-processes the same image.
+Releasing it before `model()` also matters: DXGI cannot acquire the next frame
+while a reference to the previous surface is outstanding.
+
+`sync()` is not optional. `process()` waits on the D3D12 fence but knows
+nothing about CUDA work you have queued against the same memory, so a kernel
+still reading the tensor when the next dispatch lands sees a half-overwritten
+frame — with no error, just wrong numbers.
+
+Keep the `CudaTensor` for as long as you use the array: it owns the CUDA
+import and the preprocessor that owns the VRAM. On a machine with more than
+one CUDA device, pass `device=N` — the tensor can only be imported by the
+device that owns the adapter which captured the frame.
+
+The import is paid once. After that `pre.process(frame)` overwrites the same
+buffer the CuPy array points at, so a capture loop pays nothing per frame to
+keep the view.
+
 **Where Rapidshot stops.** The output is an `ID3D12Resource` on the DirectML
 device — exactly what ONNX Runtime's DirectML provider consumes. Rapidshot
 deliberately does **not** bind it to a session: that would couple this library
@@ -760,6 +820,25 @@ What is measured, reproducibly, is the per-frame cost of RapidShot's own paths
 The first three are synthetic and deterministic: they move when the library
 changes and not otherwise, which is why they are the ones on the badges above.
 
+**Second machine, NVIDIA RTX 4060 Laptop** (`benchmarks/baseline-rtx4060.json`,
+P-core-pinned, 1920×1080 synthetic source, minimums):
+
+| Path | Per frame |
+| --- | --- |
+| Colour conversion, BGRA→RGB | 0.198 ms |
+| Colour conversion, BGRA→GRAY | 0.252 ms |
+| CPU resize + normalise + NCHW | 3.09 ms |
+| **GPU dispatch → NCHW tensor, D3D12** | **0.070 ms** (2560×1600 source) |
+| GPU dispatch + forced readback | 2.20 ms |
+| `grab_frame()` — texture stays on the GPU | 0.099–0.156 ms |
+
+Cross-machine comparison is not valid — different CPU, GPU, panel and, on two
+rows, different code. Both recordings are kept so each answers for its own
+machine.
+
+Sustained-load check: 211,726 frames of `grab_frame()` → GPU tensor in 12
+minutes, zero errors, VRAM flat, no throughput decay.
+
 **The last two are not stable measurements and should not be quoted as single
 numbers.** `grab()` converts only the parts of the frame that changed, so its
 cost tracks what is happening on screen; across seven recordings on unchanged
@@ -785,11 +864,42 @@ breakdown and how each figure is measured.
   only for the optional CuPy acceleration.
 - **RAM:** 8 GB+ (depending on the resolution and number of screencapture instances used)
 
+### Tested configurations
+
+Nothing in RapidShot branches on GPU vendor. This is what has actually been
+run, which is not the same claim:
+
+| Configuration | State |
+| --- | --- |
+| Intel iGPU, single adapter | Verified |
+| NVIDIA dGPU, single adapter, native extension built | Verified |
+| NVIDIA dGPU, single adapter, no extension | Verified |
+| Any AMD GPU | **Not tested** |
+| Hybrid / switchable graphics (Optimus, AMD) | **Not tested** |
+| Headless with a virtual display | **Not tested** |
+
+CuPy is the only NVIDIA-bound feature, because CUDA is; `nvidia_gpu=True` falls
+back to the CPU processor when CuPy is unavailable. AMD and Intel consumers
+reach the same GPU tensor through DirectML via `output_resource_address`.
+
 ### Troubleshooting
 
 - **ImportError with CuPy:** Ensure you have compatible CUDA drivers installed.
-- **Black screens when capturing:** Verify the application isn't running in exclusive fullscreen mode.
+  `pip install cupy-cuda13x[ctk]` installs no headers against `cuda-toolkit`
+  13.3.x and CuPy then fails at its first JIT; use
+  `pip install "cuda-toolkit[cudart,nvrtc]==13.2.*"` instead.
+- **"Desktop duplication was denied":** the message names the cause. A
+  non-input desktop, a locked workstation, an open UAC prompt and a Session 0
+  service cannot capture the user's screen; protected (HDCP/DRM) content is a
+  separate case and is reported as such.
+- **Black screens when capturing:** protected content is blanked by the OS —
+  check `frame.protected_content`. Exclusive fullscreen is handled: capture
+  detects the transition, rebuilds, and continues.
 - **Low performance:** Experiment with different backends (NUMPY vs. CUPY) to optimize performance.
+- **Unstable benchmark numbers:** on a hybrid P-core/E-core CPU, pin the
+  process to the performance cores. `benchmarks/perf_suite.py` does this
+  itself; unpinned it reported false regressions up to 2.57× against
+  unchanged code.
 
 ## Contributing
 

{rapidshot-2.2.0 → rapidshot-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rapidshot"
-version = "2.2.0"
+version = "2.3.0"
 description = "A high-performance screencapture library for Windows using Desktop Duplication API"
 readme = "README.md"
 requires-python = ">=3.9"

{rapidshot-2.2.0 → rapidshot-2.3.0}/rapidshot/__init__.py

@@ -539,7 +539,7 @@ def get_version_info() -> Dict[str, Any]:
     return info
 
 # Version information
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 __author__ = "Rapidshot Contributors"
 __description__ = "High-performance screencapture library for Windows using Desktop Duplication API"
 

{rapidshot-2.2.0 → rapidshot-2.3.0}/rapidshot/capture.py

@@ -610,6 +610,7 @@ class ScreenCapture:
             rotation_angle=self.rotation_angle,
             present_time_qpc=duplicator.last_present_time,
             accumulated_frames=duplicator.accumulated_frames,
+            source_id=duplicator.instance_id,
             protected_content=duplicator.protected_content_detected,
             cursor_visible=duplicator.cursor_visible,
             dirty_rects=duplicator.dirty_rects,

{rapidshot-2.2.0 → rapidshot-2.3.0}/rapidshot/core/duplicator.py

@@ -1,4 +1,5 @@
 import ctypes
+import itertools
 import logging
 import os
 import comtypes  # type: ignore[import-untyped]
@@ -33,8 +34,10 @@ from rapidshot._libs.dxgi import (
     IDXGIResource,
     RECT,
 )
+from rapidshot._libs.dxgi import E_ACCESSDENIED
 from rapidshot.core.device import Device
 from rapidshot.core.output import Output
+from rapidshot.util.desktop import describe_desktop_access
 from rapidshot.util.errors import (
     RapidShotError,
     RapidShotDXGIError,
@@ -71,6 +74,13 @@ DUPLICATE_OUTPUT1_FORMATS = (
 # pre-1.5 DuplicateOutput path if a driver misbehaves on DuplicateOutput1.
 _DUPLICATE_OUTPUT_ENV = "RAPIDSHOT_DUPLICATE_OUTPUT"
 
+# Process-unique id per Duplicator. Consumers that cache anything keyed on a
+# captured texture's address need this: COM addresses are recycled, so a
+# released surface and a later unrelated one can share a pointer. Pairing the
+# pointer with the duplicator that produced it makes the identity sound,
+# because a recycled address necessarily belongs to a different duplicator.
+_duplicator_ids = itertools.count(1)
+
 
 def _format_hresult(hresult) -> str:
     """Render an HRESULT as 0x-prefixed hex, tolerating non-integer values."""
@@ -79,6 +89,37 @@ def _format_hresult(hresult) -> str:
     return str(hresult)
 
 
+def _desktop_refusal(hresult, detail: str = "") -> Optional[RapidShotError]:
+    """Return a desktop-specific error if that is what a refusal really means.
+
+    ``DuplicateOutput`` reports both "protected content is on screen" and "you
+    are not on the input desktop" as a bare ``E_ACCESSDENIED``. Reporting the
+    second as the first is actively misleading: a locked workstation, an open
+    UAC prompt, and a Session 0 service all told the user to close a protected
+    player window that does not exist. Measured 2026-08-06 by moving a thread
+    to a fresh desktop with ``CreateDesktop``, which reproduces the HRESULT
+    exactly.
+
+    Only plain ``E_ACCESSDENIED`` is ambiguous. ``DXGI_ERROR_ACCESS_DENIED``
+    and ``DXGI_ERROR_CANNOT_PROTECT_CONTENT`` are specific to protected
+    content, so they are left alone.
+
+    Returns:
+        A ``RapidShotConfigError`` naming the real cause, or None to let the
+        caller report protected content.
+    """
+    if hresult != E_ACCESSDENIED:
+        return None
+    state = describe_desktop_access()
+    if state.blocked_reason is None:
+        return None
+    prefix = f"{detail} — " if detail else ""
+    return RapidShotConfigError(
+        f"{prefix}Desktop duplication was denied: {state.blocked_reason}",
+        hresult=hresult,
+    )
+
+
 def _legacy_duplication_forced() -> bool:
     """True if the env var asks for the pre-DuplicateOutput1 code path."""
     return os.environ.get(_DUPLICATE_OUTPUT_ENV, "").strip().lower() in (
@@ -152,6 +193,8 @@ class Duplicator:
     # True when the driver merged rects rather than reporting them individually,
     # so the regions are an over-estimate of what actually changed.
     rects_coalesced: bool = False
+    # See _duplicator_ids: identifies which duplicator a texture came from.
+    instance_id: int = field(default_factory=lambda: next(_duplicator_ids))
     _frame_acquired: bool = False
 
     def __post_init__(self, output: Output, device: Device) -> None:
@@ -232,6 +275,13 @@ class Duplicator:
                 except comtypes.COMError as ce:
                     hresult = ce.args[0] if ce.args else None
                     if hresult in DXGI_PROTECTED_CONTENT_ERRORS:
+                        # A bare E_ACCESSDENIED means one of two unrelated
+                        # things, and blaming protected content for both sends
+                        # people hunting for a player window that is not there.
+                        # Ask the window station before deciding.
+                        desktop_error = _desktop_refusal(hresult)
+                        if desktop_error is not None:
+                            raise desktop_error from ce
                         # Protected surfaces are a permanent refusal for this
                         # output, not something the legacy path can work around.
                         self.protected_content_detected = True
@@ -263,6 +313,9 @@ class Duplicator:
         detail = f"{context}: {ce}"
 
         if hresult in DXGI_PROTECTED_CONTENT_ERRORS:
+            desktop_error = _desktop_refusal(hresult, detail)
+            if desktop_error is not None:
+                return desktop_error
             self.protected_content_detected = True
             return RapidShotProtectedContentError(
                 f"{detail} (protected/HDCP content is blocking duplication)",

{rapidshot-2.2.0 → rapidshot-2.3.0}/rapidshot/frame.py

@@ -78,7 +78,7 @@ class Frame:
         "_texture", "_on_release", "_released", "_region", "_rotation_angle",
         "_present_time_qpc", "_accumulated_frames", "_protected_content",
         "_cursor_visible", "_width", "_height", "_dirty_rects",
-        "_rects_coalesced",
+        "_rects_coalesced", "_source_id",
     )
 
     def __init__(
@@ -93,6 +93,7 @@ class Frame:
         cursor_visible: bool = False,
         dirty_rects: Optional[List[Tuple[int, int, int, int]]] = None,
         rects_coalesced: bool = False,
+        source_id: int = 0,
     ) -> None:
         self._texture = texture
         self._on_release = on_release
@@ -107,6 +108,7 @@ class Frame:
         self._height = region[3] - region[1]
         self._dirty_rects = self._clip_to_region(dirty_rects)
         self._rects_coalesced = rects_coalesced
+        self._source_id = source_id
 
     def _clip_to_region(self, rects):
         """Translate desktop-coordinate rects into this frame's coordinates.
@@ -205,6 +207,17 @@ class Frame:
         """
         return self._accumulated_frames
 
+    @property
+    def source_id(self) -> int:
+        """Which duplicator produced this frame's texture.
+
+        Consumers caching anything keyed on the texture address need this too:
+        COM addresses are recycled, so a released surface and a later unrelated
+        one can share a pointer. The pair is a sound identity; the pointer
+        alone is not.
+        """
+        return self._source_id
+
     @property
     def protected_content(self) -> bool:
         """True if HDCP/DRM content was blanked out of this frame by the OS."""

{rapidshot-2.2.0 → rapidshot-2.3.0}/rapidshot/native.py

@@ -254,7 +254,10 @@ class GpuPreprocessor:
         """
         import numpy as np
 
-        flat = np.asarray(self._impl.read_back(), dtype=np.float32)
+        # The extension hands back raw bytes, not a list of floats: a list cost
+        # one Python object per element and dominated the readback benchmark it
+        # was meant to price. `frombuffer` is a reinterpret, not a conversion.
+        flat = np.frombuffer(self._impl.read_back(), dtype=np.float32)
         return flat.reshape(1, 3, self.out_height, self.out_width)
 
     @property
@@ -319,19 +322,57 @@ class GpuPreprocessor12:
     def process(self, frame, scale: float = 1.0, bias: float = 0.0,
                 bgr: bool = False) -> None:
         """Convert one frame. The result stays on the DirectML device."""
-        self._impl.process(_texture_address(frame), scale, bias, bgr)
+        # The texture address alone is not an identity -- COM addresses get
+        # recycled -- so the frame's source_id goes with it. See Frame.source_id.
+        self._impl.process(_texture_address(frame), scale, bias, bgr,
+                           source_id=getattr(frame, "source_id", 0))
 
     def read_back(self):
         """Copy the tensor to the CPU as (1, 3, H, W). Verification only."""
         import numpy as np
 
-        flat = np.asarray(self._impl.read_back(), dtype=np.float32)
+        # Raw bytes rather than a list of floats — see the note on the D3D11
+        # preprocessor's read_back.
+        flat = np.frombuffer(self._impl.read_back(), dtype=np.float32)
         return flat.reshape(1, 3, self.out_height, self.out_width)
 
     @property
     def shape(self):
         return tuple(self._impl.shape)
 
+    @property
+    def shared_output_handle(self) -> int:
+        """
+        Shared NT handle for the tensor, for a consumer on another device or API.
+
+        This is what CUDA's ``cudaImportExternalMemory`` takes with
+        ``cudaExternalMemoryHandleTypeD3D12Resource``. Pair it with
+        :attr:`output_byte_size`, which is the size such an importer must map.
+
+        **Borrowed, not owned.** It is closed when this preprocessor is dropped;
+        do not close it yourself, and do not use it after that point.
+        """
+        return int(self._impl.shared_output_handle)
+
+    @property
+    def output_byte_size(self) -> int:
+        """Size of the tensor in bytes — what an importer must map."""
+        return int(self._impl.output_byte_size)
+
+    @property
+    def adapter_luid(self) -> bytes:
+        """
+        LUID of the adapter holding the tensor, as 8 little-endian bytes.
+
+        The tensor is not cross-adapter, so only a consumer on *this* adapter
+        can import it. CUDA exposes the same identity via ``cuDeviceGetLuid``,
+        which is how a caller picks the right device — and how it finds out
+        there isn't one. That is the ordinary hybrid-laptop case: capture runs
+        on the iGPU, CUDA reports exactly one device, and it is the wrong one,
+        so counting devices cannot detect the mismatch.
+        """
+        return bytes(self._impl.adapter_luid)
+
     @property
     def output_resource_address(self) -> int:
         """