RapidShot

https://github.com/zaatra/rapidshot
Admin
RapidShot is a high-performance screencapture library for Windows using the Desktop Duplication API,...
Tokens:49,416
Snippets:418
Trust Score:4.4
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Set up development environment and run tests

Source: https://github.com/zaatra/rapidshot/blob/main/CONTRIBUTING.md

Installs the package in editable mode with development dependencies and runs the test suite quietly. This is the complete setup for all development except the optional Rust extension.

```bash
pip install -e ".[dev]"
python -m pytest tests/ -q
```

--------------------------------

### start() with video_mode

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/screencapture.md

Start background capture with start(). video_mode=True re-queues the last frame when no new content exists, giving a constant frame rate.

```python
camera.start(target_fps=60, video_mode=True)
```

--------------------------------

### start(region=None, target_fps=60, video_mode=False, delay=0)

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/screencapture.md

Starts background capture into a ring buffer; use `get_latest_frame()` to read. `video_mode=True` re-queues the last frame when no new content exists (constant frame rate). No-op if already capturing.

```APIDOC
## start(region=None, target_fps=60, video_mode=False, delay=0)

### Description
Starts background capture into a ring buffer; use `get_latest_frame()` to read. `video_mode=True` re-queues the last frame when no new content exists (constant frame rate). No-op if already capturing.

### Method
N/A (Python method)

### Endpoint
N/A (Python method)

### Parameters
#### Parameters
- **region** (Optional[Tuple[int,int,int,int]]) - Optional - Region to capture.
- **target_fps** (int) - Optional - Target frame rate.
- **video_mode** (bool) - Optional - Duplicate last frame on no-new-content ticks.
- **delay** (int) - Optional - MS to sleep before starting.

### Usage Example
```python
camera.start(target_fps=60, video_mode=True)
```

```

--------------------------------

### Example - creating a device

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/core-device.md

Enumerates DXGI adapters, creates a Device from the first adapter, prints its description and feature level, and enumerates its outputs.

```python
from rapidshot.util.io import enum_dxgi_adapters
from rapidshot.core.device import Device

adapters = enum_dxgi_adapters()
device = Device(adapters[0])
print(device.description, device.feature_level_to_str(device.feature_level))
outputs = device.enum_outputs()
```

--------------------------------

### GpuPreprocessor usage example

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/native.md

Usage example for GpuPreprocessor: creates a preprocessor for 640x640 input and processes a grabbed frame, keeping the conversion on the GPU.

```python
import rapidshot.native as native

pre = native.GpuPreprocessor(frame, 640, 640)
with camera.grab_frame() as frame:
    pre.process(frame)          # stays on GPU
```

--------------------------------

### Backend selection example

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/processor.md

Example of selecting a processing backend using the Processor class and accessing backend properties.

```APIDOC
## Backend selection example

### Description
Example of selecting a processing backend using the Processor class and accessing backend properties.

### Code
```python
from rapidshot.processor import Processor
from rapidshot.processor.base import ProcessorBackends

proc = Processor(backend=ProcessorBackends.NUMPY, output_color="GRAY")
channels = proc.output_channels        # 1
print(proc.active_backend)             # ProcessorBackends.NUMPY
```
```

--------------------------------

### StageSurface map/unmap/release example

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/core-stagesurf.md

Example usage of StageSurface: create with output and device, map to get a DXGI_MAPPED_RECT, read pixels from pBits/Pitch, then unmap and release.

```python
from rapidshot.core.stagesurf import StageSurface

surf = StageSurface(output=out, device=device)
rect = surf.map()
# read pixels from rect.pBits / rect.Pitch
surf.unmap()
surf.release()
```

--------------------------------

### Build and install the optional native extension

Source: https://github.com/zaatra/rapidshot/blob/main/CONTRIBUTING.md

Builds the optional native extension in release mode and installs it for development. Requires Rust and the MSVC C++ build tools.

```bash
(cd native && cargo build --release) && python native/install_dev.py
```

--------------------------------

### Install RapidShot core

Source: https://github.com/zaatra/rapidshot/blob/main/README.md

Installs the core RapidShot library for CPU and D3D11 capture, including grab(), grab_frame(), regions, colour conversion, dirty rects, and video recording. No toolchain, compiler, or GPU requirement.

```bash
pip install rapidshot
```

--------------------------------

### Install rapidshot-native with pip

Source: https://github.com/zaatra/rapidshot/blob/main/native/README.md

Install the prebuilt native GPU-interop extension for RapidShot. This is the only installation step needed to enable GPU paths without a Rust toolchain.

```bash
pip install rapidshot rapidshot-native
```

--------------------------------

### Output usage example

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/core-output.md

Creates an Output instance from a DXGI output pointer, prints its device name, resolution, and rotation angle, then re-reads the description after a mode change.

```python
from rapidshot.core.output import Output

out = Output(output_pointer)
print(out.devicename, out.resolution, out.rotation_angle)
out.update_desc()          # re-read after mode change
```

--------------------------------

### Device

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/core-device.md

Documentation for the Device class, including its constructor, methods, properties, and usage example.

```APIDOC
## Device

### Description
A Direct3D 11 device created from a DXGI adapter, with feature-level negotiation and multi-fallback creation. It is a `@dataclass`; its fields are set by construction, and all low-level COM work happens in `__post_init__`.

### Signature
```python
@dataclass
class Device:
    adapter: ctypes.POINTER(IDXGIAdapter1)
    device: ctypes.POINTER(ID3D11Device) = None
    context: ctypes.POINTER(ID3D11DeviceContext) = None
    im_context: ctypes.POINTER(ID3D11DeviceContext) = None
    desc: DXGI_ADAPTER_DESC1 = None
    feature_level: int = 0
```

### Fields
| Field | Type | Description |
|-------|------|-------------|
| `adapter` | `ctypes.POINTER(IDXGIAdapter1)` | The DXGI adapter pointer (required). |
| `device` | `POINTER(ID3D11Device)` | Created D3D11 device. |
| `context` | `POINTER(ID3D11DeviceContext)` | Device context. |
| `im_context` | `POINTER(ID3D11DeviceContext)` | Immediate (IGPU) context used for capture. |
| `desc` | `DXGI_ADAPTER_DESC1` | Adapter description read via `GetDesc1`. |
| `feature_level` | `int` | Negotiated D3D feature level. |

### Constructor
Construct with a pointer to `IDXGIAdapter1`:
```python
from rapidshot.core.device import Device
device = Device(adapter_pointer)   # desc is populated; D3D11 device created
```

### Methods

#### `__post_init__(self) -> None`
Reads the adapter description and calls `_create_device_with_multiple_fallbacks()`.

#### `_create_device_with_multiple_fallbacks(self) -> None`
Attempts D3D11 device creation across feature levels (`D3D_FEATURE_LEVEL_11_1` down to `9_1`), driver types (`UNKNOWN`, `HARDWARE`, `WARP`, `REFERENCE`, `SOFTWARE`), and flag combinations. **Raises `RuntimeError`** if every combination fails.

#### `enum_outputs(self) -> List[ctypes.POINTER(IDXGIOutput1)]`
Source: `device.py:222`. Enumerates the adapter's outputs via `EnumOutputs`. Stops when `DXGI_ERROR_NOT_FOUND` is returned. Re-raises other COM errors.

#### `release(self)`
Source: `device.py:306`. Releases `im_context`, `context`, `device`, then `adapter` COM interfaces.

#### `feature_level_to_str(self, FeatureLevel)` → `str`
Source: `device.py:216`. Formats the packed feature level as e.g. `"11.0"`.

#### `create(cls, adapter_idx=0)` — class method
Source: `device.py:282`. Enumerates DXGI adapters and creates a `Device` for `adapter_idx`. Raises `RuntimeError` if no adapters, `IndexError` if `adapter_idx` out of range.

### Properties
| Property | Type | Description |
|----------|------|-------------|
| `description` | `str` | `desc.Description`, or `"Unknown"`. |
| `vram_size` | `int` | `desc.DedicatedVideoMemory`, or `0`. |
| `vendor_id` | `int` | `desc.VendorId`, or `0`. |

`__repr__` renders `Device Name:<...> Dedicated VRAM:<...>Mb VendorId:<...>`.

### Example — creating a device
```python
from rapidshot.util.io import enum_dxgi_adapters
from rapidshot.core.device import Device

adapters = enum_dxgi_adapters()
device = Device(adapters[0])
print(device.description, device.feature_level_to_str(device.feature_level))
outputs = device.enum_outputs()
```
```

--------------------------------

### Install RapidShot native extension

Source: https://github.com/zaatra/rapidshot/blob/main/README.md

Installs the prebuilt native extension for GPU tensor features. This installs rapidshot-native >= 0.2.0, the minimum version that exports GpuConverter and TensorTransfer.

```bash
pip install "rapidshot[native]"
```

--------------------------------

### Probe and describe GPU topology

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/topology.md

Example usage of the public API: probe the topology, print its multi-line description, and check whether the machine is a hybrid laptop.

```python
import rapidshot

topo = rapidshot.probe_topology()
print(topo.describe())
print("hybrid laptop?", topo.is_hybrid)
```

--------------------------------

### Direct use example: Duplicator

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/core-duplicator.md

Creates a Duplicator instances with output and device, updates the frame, and retrieves dirty rectangles. Assumes the texture is available after a successful update.

```python
from rapidshot.core.duplicator import Duplicator

dup = Duplicator(output=out, device=device)
if dup.update_frame() and dup.updated:
    # texture available in dup.texture
    dirty = dup.get_frame_dirty_rects(info)
    dup.release_frame()
```

--------------------------------

### get_version_info() return structure

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/top-level-api.md

Returns a nested dictionary describing the library version, system information, and dependency status. Missing dependencies report "not installed" (or "version unknown" for comtypes).

```python
{
    "rapidshot": {"version", "author", "description"},
    "system":   {"python", "platform", "processor"},
    "dependencies": {"numpy", "cupy", "pillow", "opencv", "comtypes"},
}
```

--------------------------------

### Continuous capture with camera.start() and get_latest_frame()

Source: https://github.com/zaatra/rapidshot/blob/main/README.md

Starts continuous capture on a background thread at 60 FPS, retrieves the latest frame in a loop, then stops. One camera per output; create several for several monitors. rapidshot.create() returns the same camera for the same output if called twice.

```python
camera.start(target_fps=60, video_mode=True)
for _ in range(120):
    frame = camera.get_latest_frame()
    ...
camera.stop()
```

--------------------------------

### CrossAdapterTransfer usage example

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/native.md

Creates a transfer object, grabs a frame from the camera, transfers it across adapters, and retrieves the destination resource address. The transfer blocks until the source GPU finishes.

```python
transfer = native.cross_adapter_transfer(frame)
with camera.grab_frame() as frame:
    transfer.transfer(frame)
    dst_addr = transfer.destination_resource_address
```

--------------------------------

### Cross-adapter tensor transfer with GpuConverter and TensorTransfer

Source: https://github.com/zaatra/rapidshot/blob/main/README.md

Python example showing how to use GpuConverter and TensorTransfer to convert a frame to a float16 tensor and transfer it across adapters. This is the answer to the CrossAdapterRequired error from the quick start.

```python
converter = rapidshot.GpuConverter(frame, (640, 640), dtype="float16")
transfer  = rapidshot.TensorTransfer(converter)
converter.process(frame)
transfer.transfer()
```

--------------------------------

### RapidshotFactory.__init__

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/top-level-api.md

Initializes the RapidshotFactory by probing GPU topology and enumerating DXGI adapters.

```APIDOC
## RapidshotFactory.__init__

### Description
Initializes the factory by probing GPU topology, enumerating DXGI adapters, and wrapping each in a Device and Output. Raises HeadlessError if no capture-capable device is found, or RapidshotError on failure.

### Method
Constructor

### Signature
`RapidshotFactory.__init__(self) -> None`

### Parameters
None

### Returns
None

### Raises
- **HeadlessError** - No capture-capable device available
- **RapidshotError** - Initialization failure
```

--------------------------------

### Run live cross-adapter verification

Source: https://github.com/zaatra/rapidshot/blob/main/RELEASING.md

Run the live suite on real hardware because CI runners have no desktop session and live tests skip there.

```bash
python examples/verify_cross_adapter.py
```

--------------------------------

### Reproduce benchmarks with perf_suite.py

Source: https://github.com/zaatra/rapidshot/blob/main/docs/BENCHMARKS.md

Run the benchmark suite with 5 rounds and 25 reps, comparing against a baseline recorded on your machine. `--compare auto` fails if no baseline exists, and `--self-test` should be run first to check noise floor.

```bash
python benchmarks/perf_suite.py --rounds 5 --reps 25 --compare auto
```

--------------------------------

### Example — metadata + error handling

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/frame.md

Example of handling frame metadata and errors. Checks protected_content, rects_coalesced, and dirty_rects to decide processing. The frame is released on exit.

```python
with camera.grab_frame() as frame:
    if frame.protected_content:
        skip(frame)                    # HDCP blanked this frame
    elif frame.rects_coalesced:
        process_everything(frame)      # don't trust dirty_rects to skip
    else:
        for (l, t, r, b) in frame.dirty_rects:
            process_rect(frame.d3d11_texture, l, t, r, b)
# released on exit
```

--------------------------------

### Diagnose rapidshot installation and GPU sharing

Source: https://github.com/zaatra/rapidshot/blob/main/README.md

Use to verify the installation and inspect available adapters, outputs, native extension, and dependencies. With probe_gpu=True, also probes D3D12 sharing capabilities. The output is printed to the console.

```python
import rapidshot
print(rapidshot.diagnose())                 # adapters, outputs, extension, deps
print(rapidshot.diagnose(probe_gpu=True))   # also probe D3D12 sharing
```

--------------------------------

### Reproduce section7 benchmark with YOLO11n

Source: https://github.com/zaatra/rapidshot/blob/main/docs/BENCHMARKS.md

Commands to build the latency source, run the section7 benchmark, prepare the model, and run the AI pipeline. Requires the test source built and the model exported first.

```bash
cargo build --release --bin latency_source --manifest-path native/Cargo.toml
python benchmarks/section7.py --seconds 5 --out results.json
python benchmarks/prepare_model.py
python benchmarks/ai_pipeline.py --seconds 8 --model build/section7/model/yolo11n.onnx --model-sha256 <sha256 printed by prepare_model.py>
```

--------------------------------

### Processor.__init__

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/processor.md

Initializes a Processor instance with a specified backend, output color, and optional CUDA preference. Raises ValueError for unsupported output colors.

```APIDOC
## Processor.__init__

### Description
Initializes a Processor instance with a specified backend, output color, and optional CUDA preference. Raises ValueError for unsupported output colors.

### Method
Constructor

### Signature
```python
Processor(backend: Optional[ProcessorBackends] = None, output_color: str = "RGB", nvidia_gpu: bool = False)
```

### Parameters
- **backend** (Optional[ProcessorBackends]) - Optional - Backend; auto-selected (CUPY if nvidia_gpu, else NUMPY).
- **output_color** (str) - Optional - Color format. Default: "RGB".
- **nvidia_gpu** (bool) - Optional - Prefer CUDA backend. Default: False.

### Raises
- **ValueError** - On unsupported output_color.
```

--------------------------------

### Construct Device with adapter pointer

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/core-device.md

Creates a Device instance from a pointer to IDXGIAdapter1. The description is populated and a D3D11 device is created during post-initialization.

```python
from rapidshot.core.device import Device
device = Device(adapter_pointer)   # desc is populated; D3D11 device created
```

--------------------------------

### get_latest_frame() loop

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/screencapture.md

Start capture, read the latest frame repeatedly with get_latest_frame(), then stop. The loop runs 300 iterations.

```python
stop_event, frame_queue = Event(), Queue()
camera.start(target_fps=60)
for i in range(300):
    frame = camera.get_latest_frame()
camera.stop()
```

--------------------------------

### Run library comparison benchmark

Source: https://github.com/zaatra/rapidshot/blob/main/docs/BENCHMARKS.md

Run the library comparison benchmark with motion detection enabled. Each library runs in its own process because all three DXGI libraries declare the same COM interfaces and whichever imports first breaks the others.

```bash
python benchmarks/compare_libraries.py --motion --with-motion
```

--------------------------------

### Frame constructor signature

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/frame.md

Constructor for the Frame class. Most consumers never construct a Frame directly; they get one from camera.grab_frame().

```python
def __init__(
    self,
    texture,
    on_release,
    region: Tuple[int, int, int, int],
    rotation_angle: int = 0,
    present_time_qpc: int = 0,
    accumulated_frames: int = 0,
    protected_content: bool = False,
    cursor_visible: bool = False,
    dirty_rects: Optional[List[Tuple[int, int, int, int]]] = None,
    rects_coalesced: bool = False,
    source_id: int = 0,
) -> None
```

--------------------------------

### Use to_nchw with BGRA and output buffer

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/preprocess.md

Example of using to_nchw with BGRA source order and an output buffer, catching ValueError for invalid inputs.

```python
from rapidshot import to_nchw

try:
    tensor = to_nchw(frame, (640, 640), "BGRA", out=reuse_buf)
except ValueError as e:
    print("invalid input:", e)
```

--------------------------------

### get_version_info

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/top-level-api.md

Returns version, system, and dependency information as a nested dictionary.

```APIDOC
## get_version_info

### Description
Returns a nested dictionary with version, system, and dependency information. Missing dependencies report "not installed" (or "version unknown" for comtypes).

### Method
Module-level function

### Signature
`get_version_info() -> Dict[str, Any]`

### Parameters
None

### Returns
- **Dict[str, Any]** - Nested dictionary with keys: rapidshot, system, dependencies
```

--------------------------------

### Handling PoolExhaustedError on grab()

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/memory-pool.md

Shows how to catch PoolExhaustedError when calling camera.grab(). The exception is raised when the pool has no available buffers, and the example suggests increasing pool_size_frames on the camera.

```python
try:
    frame = camera.grab()
except rapidshot.memory_pool.PoolExhaustedError:
    print("pool exhausted; raise pool_size_frames on the camera")
```

--------------------------------

### ScreenCapture.__init__

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/screencapture.md

Constructor for the ScreenCapture class, which initializes the capture pipeline for a given output and device.

```APIDOC
## ScreenCapture.__init__

### Description
Initializes a ScreenCapture instance for capturing frames from a Direct3D 11 output device. This constructor sets up the duplicator, staging surface, processor, and memory pool, and releases resources if initialization fails.

### Method
Constructor

### Endpoint
ScreenCapture.__init__(output, device, region=None, output_color="RGB", nvidia_gpu=False, max_buffer_len=64, pool_size_frames=4, pool_output=True, timeout_ms=10)

### Parameters
#### Parameters
- **output** (Output) - Required - Output device to capture from.
- **device** (Device) - Required - Direct3D 11 device interface.
- **region** (Optional[Tuple[int,int,int,int]]) - Optional - Region `(left, top, right, bottom)`; `None` = full output.
- **output_color** (str) - Optional - `RGB`, `RGBA`, `BGR`, `BGRA`, or `GRAY`.
- **nvidia_gpu** (bool) - Optional - Use CuPy GPU acceleration.
- **max_buffer_len** (int) - Optional - Continuous-mode ring buffer length.
- **pool_size_frames** (int) - Optional - Buffers kept for `grab()`; each is a full frame.
- **pool_output** (bool) - Optional - Reuse converted-frame buffers; `grab()` returns a `PooledBuffer`.
- **timeout_ms** (int) - Optional - Time each acquire waits for a new frame.

### Request Example
```python
from rapidshot.capture import ScreenCapture
capture = ScreenCapture(output=my_output, device=my_device, region=(0, 0, 1920, 1080), output_color="RGB", nvidia_gpu=False, max_buffer_len=64, pool_size_frames=4, pool_output=True, timeout_ms=10)
```

### Response
#### Success Response
- No return value (None).

#### Error Handling
- **ValueError** - `timeout_ms` is negative or non-int; `pool_size_frames` is `< 1`.
- **RapidShotError** - Initial resource initialization failed.

### Notes
- Construction initializes the duplicator, staging surface, processor, and memory pool; any failure triggers `release()` before re-raising.
```

--------------------------------

### RuntimeError for outdated rapidshot-native

Source: https://github.com/zaatra/rapidshot/blob/main/README.md

Error message shown when an older rapidshot-native extension (0.1.0) is installed. It indicates that GpuConverter12 requires rapidshot-native >= 0.2.0 and suggests upgrading the prebuilt wheel.

```text
RuntimeError: GpuConverter12 requires rapidshot-native >= 0.2.0; the installed
extension is version 0.1.0, from rapidshot-native wheel.

Upgrade the prebuilt wheel:
    pip install --upgrade 'rapidshot-native>=0.2.0'
```

--------------------------------

### Convert frame to tensor with RGB order

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/preprocess.md

Example of converting a captured frame to a tensor with RGB source order. The output shape is asserted to be (1, 3, 640, 640).

```python
camera = rapidshot.create(output_color="RGB")
frame = camera.grab()
# reuse one output buffer across the capture loop
tensor = rapidshot.to_nchw(frame, (640, 640), "RGB")
assert tensor.shape == (1, 3, 640, 640)
```

--------------------------------

### create()

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/top-level-api.md

Creates a ScreenCapture instance. This is the primary factory entry point for the RapidShot library.

```APIDOC
## create()

### Description
Creates a ScreenCapture instance. This is the primary factory entry point for the RapidShot library.

### Method
create

### Endpoint
rapidshot.create

### Parameters
#### Parameters
- **device_idx** (int) - Optional - Device index. Validated against the enumerated devices. Default: 0.
- **output_idx** (int / None) - Optional - Output index; None auto-selects the primary monitor. Default: None.
- **region** (tuple / None) - Optional - Region to capture (left, top, right, bottom). None = full output. Default: None.
- **output_color** (str) - Optional - One of RGB, RGBA, BGR, BGRA, GRAY. Default: "RGB".
- **nvidia_gpu** (bool) - Optional - Use NVIDIA GPU acceleration (requires CuPy). Default: False.
- **max_buffer_len** (int) - Optional - Ring-buffer length for continuous-mode capture. Default: 64.
- **prefer_integrated** (bool) - Optional - Search for an integrated (Intel) GPU and select it. Default: False.
- **pool_output** (bool) - Optional - Reuse converted-frame buffers; grab() returns a PooledBuffer the caller releases. Default: True.
- **timeout_ms** (int) - Optional - How long each acquire waits for a new frame. 0 polls. Default: 10.
- **pool_size_frames** (int) - Optional - Buffers kept for grab() to hand out. Default: 4.

### Returns
A configured ScreenCapture instance (or an existing singleton for the same (device_idx, output_idx)).

### Raises
- **RapidshotError** - DXGI enumeration unavailable on this platform; or instance creation failed.
- **HeadlessError** - no adapter drives a display.
- **DeviceError** - device_idx out of range.
- **OutputError** - output_idx out of range.
- **ConfigurationError** - output_color is not one of the five valid formats.

### Request Example
```python
import rapidshot

camera = rapidshot.create(output_color="BGR", timeout_ms=0, pool_output=False)
frame = camera.grab()
# frame is a freshly allocated numpy array; no release needed (pool_output=False)
```

```python
import rapidshot
from rapidshot import HeadlessError

try:
    camera = rapidshot.create(device_idx=0, output_idx=0)
except HeadlessError as e:
    print("No display to duplicate")
    print(e.topology.help_text())   # actionable guidance
```

### Response
#### Success Response
- **ScreenCapture** - A configured ScreenCapture instance.

#### Error Response
- **RapidshotError** - DXGI enumeration unavailable or instance creation failed.
- **HeadlessError** - no adapter drives a display.
- **DeviceError** - device_idx out of range.
- **OutputError** - output_idx out of range.
- **ConfigurationError** - output_color is not one of the five valid formats.
```

--------------------------------

### PillowProcessor.__init__

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/processor.md

Initializes a PillowProcessor instance with a specified color mode, defaulting to RGB.

```APIDOC
## PillowProcessor.__init__(self, color_mode: str = "RGB")

### Description
Initializes a PillowProcessor instance with the given color mode. Defaults to "RGB".

### Method
Constructor

### Parameters
- **color_mode** (str) - Optional - The color mode to use. Defaults to "RGB".
```

--------------------------------

### grab() with and without memory pool

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/screencapture.md

Use the first block when pool_output=True to release the PooledBuffer in a finally block. Use the second block when pool_output=False to get a freshly allocated array that requires no release.

```python
frame = camera.grab()
try:
    do_gpu_work(frame)          # np.asarray(frame) is a zero-cost view
finally:
    frame.release()
```

```python
camera = rapidshot.create(pool_output=False)
frame = camera.grab()           # freshly allocated array; no release needed
```

--------------------------------

### CupyProcessor.__init__

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/processor.md

Initializes a CupyProcessor instance with a specified color mode. Raises ImportError if CuPy is missing and ValueError for unsupported color modes.

```APIDOC
## CupyProcessor.__init__(self, color_mode)

### Description
Initializes a CupyProcessor instance with the given color mode. Raises ImportError with platform-specific install instructions if CuPy is missing, and ValueError for unsupported color modes.

### Method
Constructor

### Parameters
- **color_mode** (str) - Required - The color mode to use for processing.

### Exceptions
- **ImportError** - Raised if CuPy is not installed.
- **ValueError** - Raised if the color mode is unsupported.
```

--------------------------------

### Using PooledBuffer with grab() and copy()

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/memory-pool.md

Shows typical usage of a PooledBuffer obtained from camera.grab() with pool_output=True. np.asarray(frame) creates a zero-cost view, frame.copy() returns an owned copy that survives release, and frame.release() checks the buffer back into the pool.

```python
frame = camera.grab()          # PooledBuffer (pool_output=True)
arr = np.asarray(frame)        # zero-cost view
np_frame = frame.copy()        # owned copy that outlives release
frame.release()
```

--------------------------------

### High-resolution timer API constants and functions

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/util.md

Windows waitable high-resolution timer API used by continuous-mode capture. All functions raise ctypes.WinError on failure. Use create_high_resolution_timer to get a handle, set_periodic_timer to schedule, and wait_for_timer/cancel_timer for waiting and cancellation.

```python
INFINITE = 0xFFFFFFFF
WAIT_FAILED = 0xFFFFFFFF
create_high_resolution_timer()                              # handle
set_periodic_timer(handle, period: int)                    # True / raises ctypes.WinError
wait_for_timer = kernel32.WaitForSingleObject              # result int
cancel_timer = kernel32.CancelWaitableTimer                # result int
close_timer(handle)                                       # True / raises ctypes.WinError
```

--------------------------------

### Stream GPU tensors with rapidshot.TensorStream

Source: https://github.com/zaatra/rapidshot/blob/main/README.md

Use TensorStream to get a model-ready FP16 tensor on the GPU without CPU copies. Requires rapidshot[native]. TensorStream handles pitfalls like held frames, buffer races, None semantics, and adapter changes.

```python
import rapidshot

camera = rapidshot.create()
stream = rapidshot.TensorStream(camera, size=(640, 640),
                                dtype="float16", layout="NCHW")

for tensor in stream:
    prediction = model(tensor.to_torch())
```

--------------------------------

### create() factory signature

Source: https://github.com/zaatra/rapidshot/blob/main/_autodocs/api-reference/top-level-api.md

Signature of the primary factory entry point. Creates a ScreenCapture instance with configurable device, output, region, color format, GPU acceleration, and buffer pooling.

```python
def create(
    device_idx: int = 0,
    output_idx: int = None,
    region: tuple = None,
    output_color: str = "RGB",
    nvidia_gpu: bool = False,
    max_buffer_len: int = 64,
    prefer_integrated: bool = False,
    pool_output: bool = True,
    timeout_ms: int = 10,
    pool_size_frames: int = 4,
) -> "ScreenCapture":
```

--------------------------------

### Capture to NumPy with rapidshot.create() and grab()

Source: https://github.com/zaatra/rapidshot/blob/main/README.md

Creates a camera with BGR output and grabs a frame from a specified region. grab() returns None when nothing has changed because Desktop Duplication reports only changed content.

```python
camera = rapidshot.create(output_color="BGR")          # RGB, BGR, RGBA, BGRA, GRAY
frame  = camera.grab(region=(0, 0, 1920, 1080))        # left, top, right, bottom
```
Tokens:
Raw