### Installation (Shell)

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Command to install the D3DShot library using pip. This command fetches and installs the package and its default dependencies.

```shell
pip install d3dshot
```

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

### Manage Display Selection

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Provides examples for listing available displays, checking the current display, and switching the active display for capture operations.

```python
# List displays
d.displays

# Check current display
d.display

# Switch display
d.display = d.displays[1]
```

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

### Basic Screen Capture Control

Source: https://context7.com/serpentai/d3dshot/llms.txt

Demonstrates how to initialize the capture engine, start and stop continuous capture, and retrieve the latest frame from the buffer.

```python
import d3dshot
import time

d = d3dshot.create()
print(d.is_capturing)

d.capture(target_fps=30, region=(0, 0, 1920, 1080))
time.sleep(3)
d.stop()

latest_frame = d.get_latest_frame()
print(f"Latest frame shape: {latest_frame.shape}")
```

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

### Execute Complete Capture Pipeline

Source: https://context7.com/serpentai/d3dshot/llms.txt

A comprehensive example showing how to initialize a capture session, monitor frame buffer progress, stop the capture, and save frames to disk. This script handles directory creation and provides frame statistics.

```python
import d3dshot
import time
import os

def capture_session(duration=10, output_dir="./captures"):
    os.makedirs(output_dir, exist_ok=True)
    d = d3dshot.create(capture_output="numpy", frame_buffer_size=300)
    d.capture(target_fps=60)
    start_time = time.time()
    while time.time() - start_time < duration:
        time.sleep(0.1)
    d.stop()
    d.frame_buffer_to_disk(directory=output_dir)
    return d.frame_buffer

if __name__ == "__main__":
    capture_session(duration=5)
```

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

### Basic Screenshot to Memory (Python)

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Captures a screenshot of the primary display and returns it as a PIL Image object. This is the default and simplest way to get a screen capture.

```python
import d3dshot

d = d3dshot.create()
d.screenshot()
```

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

### Manage Displays with D3DShot

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Allows listing available displays and selecting a specific display for capture. The primary display is selected by default, but multi-monitor setups can utilize other displays from the `d.displays` list.

```python
# List detected displays
d.displays

# Select a display for capture (e.g., the second display)
d.display = d.displays[1]
```

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

### Multi-Monitor Capture to NumPy Array (Python)

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Captures frames from a secondary monitor and returns them as a stack of NumPy arrays. This example demonstrates selecting a specific monitor and configuring the capture output to NumPy.

```python
import d3dshot
import time

d = d3dshot.create(capture_output="numpy")

d.display = d.displays[1]

d.capture()
time.sleep(3)  # Capture is non-blocking so we wait explicitely
d.stop()

frame_stack = d.get_frame_stack((0, 1, 2, 3), stack_dimension="last")
frame_stack.shape
```

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

### High-Speed Continuous Capture

Source: https://context7.com/serpentai/d3dshot/llms.txt

Starts a non-blocking, threaded capture loop that continuously captures frames into a buffer at a target FPS. Use `stop()` to end capture and retrieve frames.

```APIDOC
## High-Speed Continuous Capture

### Description
Starts a non-blocking, threaded capture loop that continuously captures frames into an internal frame buffer at a target Frames Per Second (FPS). Use the `stop()` method to end the capture process. Frames can then be retrieved from the buffer.

### Method
`d3dshot.D3DShot.capture(fps: int = 60)`
`d3dshot.D3DShot.stop()`
`d3dshot.D3DShot.frames` (property to access captured frames)

### Endpoint
N/A (Instance methods)

### Parameters
#### `capture` Method Parameters
- **fps** (int) - Optional - The target frames per second for continuous capture. Defaults to 60.

### Request Example
```python
import d3dshot
import time

d = d3dshot.create(capture_output="numpy")

# Start capturing at 60 FPS (default)
d.capture()

# Capture is non-blocking, so the program continues
print("Capturing...")
time.sleep(5)  # Capture for 5 seconds

# Stop the capture loop
d.stop()
print("Capture stopped.")

# Access captured frames (if any)
# The 'frames' attribute will contain a list of captured frames
# in the format specified by capture_output during initialization.
# Example: print(f"Number of frames captured: {len(d.frames)}")
```

### Response
#### `capture` Method Response
- **None** - This method initiates a background process and does not return a value directly.

#### `stop` Method Response
- **None** - This method terminates the background capture process.

#### `frames` Property Response
- **list** - A list containing the captured frames. The type of each frame in the list depends on the `capture_output` setting during D3DShot initialization (e.g., NumPy arrays, PIL Images).

#### Response Example
```python
# After calling d.stop(), you can access frames like this:
# if d.frames:
#     first_frame = d.frames[0]
#     print(f"Type of first frame: {type(first_frame)}")
#     # Process the captured frames...
```
```

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

### Continuous Screen Capture with D3DShot

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Enables continuous screen capturing at a specified interval or a target FPS. `screenshot_every` and `screenshot_to_disk_every` capture periodically and store captures in the frame buffer or save them directly to disk, respectively. `capture` starts a high-speed capture thread. All continuous captures run in separate threads and can be stopped using `d.stop()`.

```python
# Take screenshots every X seconds
d.screenshot_every(X)

# Take screenshots every X seconds and save to disk
d.screenshot_to_disk_every(X, directory="/path/to/save")

# Start high-speed screen capture
d.capture(target_fps=60)

# Stop all capture threads
d.stop()
```

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

### Perform High-Speed Continuous Capture

Source: https://context7.com/serpentai/d3dshot/llms.txt

Starts a non-blocking threaded loop to capture frames into a buffer at a specified frame rate.

```python
import d3dshot
import time

d = d3dshot.create(capture_output="numpy")

# Start capturing at 60 FPS (default)
d.capture()
time.sleep(5)
d.stop()
```

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

### Continuous Capture and Latest Frame Retrieval (Python)

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Starts a non-blocking screen capture process, waits for a specified duration, stops the capture, and then retrieves the most recent frame captured during that period.

```python
import d3dshot
import time

d = d3dshot.create()

d.capture()
time.sleep(5)  # Capture is non-blocking so we wait explicitely
d.stop()

d.get_latest_frame()
```

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

### Initialize D3DShot Instance

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Demonstrates how to create a D3DShot instance with specific capture output formats like PyTorch tensors on GPU or NumPy arrays.

```python
import d3dshot
d = d3dshot.create(capture_output="pytorch_float_gpu")
```

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

### Initialize D3DShot Instance

Source: https://context7.com/serpentai/d3dshot/llms.txt

Demonstrates how to create a D3DShot singleton instance with various output format configurations, including PIL, NumPy, and PyTorch.

```python
import d3dshot

# Basic initialization with PIL output (default)
d = d3dshot.create()

# Initialize with NumPy array output
d = d3dshot.create(capture_output="numpy")

# Initialize with custom frame buffer size
d = d3dshot.create(capture_output="numpy", frame_buffer_size=120)
```

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

### Benchmark D3DShot Capture Performance

Source: https://context7.com/serpentai/d3dshot/llms.txt

Demonstrates how to initialize a D3DShot instance with a specific capture output format and run a performance benchmark to measure frames per second (FPS).

```python
import d3dshot
d_numpy = d3dshot.create(capture_output="numpy")
d_numpy.benchmark()
```

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

### Initialize D3DShot Instance

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Creates an instance of D3DShot using the `create` helper function. This function handles initialization and validation. Optional arguments include `capture_output` and `frame_buffer_size`.

```python
import d3dshot

d = d3dshot.create()
```

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

### D3DShot Initialization

Source: https://context7.com/serpentai/d3dshot/llms.txt

Initializes the D3DShot screen capture system. It can be configured with different output formats and frame buffer sizes. D3DShot acts as a singleton.

```APIDOC
## D3DShot Initialization

### Description
Initializes the screen capture system. Accepts optional parameters for capture output format and frame buffer size. D3DShot acts as a singleton, so subsequent calls return the existing instance.

### Method
`d3dshot.create(*, capture_output: str = 'pil', frame_buffer_size: int = 30) -> D3DShot`

### Parameters
#### Keyword Arguments
- **capture_output** (str) - Optional - Specifies the output format for captured frames. Available options: "pil", "numpy", "numpy_float", "pytorch", "pytorch_float", "pytorch_gpu", "pytorch_float_gpu". Defaults to "pil".
- **frame_buffer_size** (int) - Optional - Sets the size of the internal frame buffer for continuous capture. Defaults to 30.

### Request Example
```python
import d3dshot

# Basic initialization with PIL output (default)
d = d3dshot.create()

# Initialize with NumPy array output
d = d3dshot.create(capture_output="numpy")

# Initialize with custom frame buffer size
d = d3dshot.create(capture_output="numpy", frame_buffer_size=120)
```

### Response
#### Success Response (200)
- **D3DShot Instance** (object) - An initialized D3DShot object.

#### Response Example
```python
# Example of a returned D3DShot object (internal representation)
<d3dshot.D3DShot object at 0x...>
```
```

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

### Basic Screenshot to Disk (Python)

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Captures a screenshot of the primary display and saves it directly to a PNG file on disk. The filename is automatically generated with a timestamp.

```python
import d3dshot

d = d3dshot.create()
d.screenshot_to_disk()
```

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

### Manage and Detect Displays

Source: https://context7.com/serpentai/d3dshot/llms.txt

Shows how to list connected displays, switch the active capture display, and access specific display properties like resolution and rotation.

```python
import d3dshot

d = d3dshot.create()

# List all detected displays
print(d.displays)

# Switch to second monitor
d.display = d.displays[1]

# Access display properties
print(f"Resolution: {d.display.resolution}")

# Re-detect displays if configuration changed
d.detect_displays()
```

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

### Capture Output Configuration

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Demonstrates how to create a D3DShot instance with a specific capture output format, such as PyTorch tensors on GPU.

```APIDOC
## Create D3DShot with PyTorch Output

### Description
This example shows how to initialize D3DShot to capture screen frames directly into PyTorch tensors on the CUDA device.

### Method
`create()`

### Endpoint
N/A (Library Function)

### Parameters
#### Keyword Arguments
- **capture_output** (string) - Required - Specifies the desired output format. Use "pytorch_float_gpu" for PyTorch tensors on CUDA.

### Request Example
```python
import d3dshot

d = d3dshot.create(capture_output="pytorch_float_gpu")
```

### Response
#### Success Response
- **d** (object) - An instance of D3DShot configured for PyTorch float GPU output.

#### Response Example
```python
# Captures will be torch.Tensor of dtype float64 with normalized values in range (0.0, 1.0) on device cuda:0
d = d3dshot.create(capture_output="pytorch_float_gpu")
```
```

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

### Timed Screenshot Intervals

Source: https://context7.com/serpentai/d3dshot/llms.txt

Shows how to automate periodic screenshots using interval-based methods and saving directly to disk for timelapse creation.

```python
import d3dshot
import time

d = d3dshot.create()
d.screenshot_every(2)
time.sleep(10)
d.stop()
print(f"Frames captured: {len(d.frame_buffer)}")

d.screenshot_to_disk_every(1, directory="./timelapse")
time.sleep(60)
d.stop()
```

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

### Configure Capture Output (Python)

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Demonstrates how to configure the output format for captured images when creating a D3DShot instance. Options include PIL Images, NumPy arrays (float or uint8), and PyTorch Tensors (float or uint8), with GPU support if available.

```python
# Captures will be PIL.Image in RGB mode
d = d3dshot.create()
d = d3dshot.create(capture_output="pil")
```

```python
# Captures will be np.ndarray of dtype uint8 with values in range (0, 255)
d = d3dshot.create(capture_output="numpy")

# Captures will be np.ndarray of dtype float64 with normalized values in range (0.0, 1.0)
d = d3dshot.create(capture_output="numpy_float")
```

```python
# Captures will be torch.Tensor of dtype uint8 with values in range (0, 255)
d = d3dshot.create(capture_output="pytorch")

# Captures will be torch.Tensor of dtype float64 with normalized values in range (0.0, 1.0)
d = d3dshot.create(capture_output="pytorch_float")
```

```python
# Captures will be torch.Tensor of dtype uint8 with values in range (0, 255) on device cuda:0
d = d3dshot.create(capture_output="pytorch_gpu")
```

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

### D3DShot Initialization

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Initializes the D3DShot instance using the factory method.

```APIDOC
## D3DShot.create()

### Description
Initializes and validates a new D3DShot instance. This is the recommended way to start using the library.

### Method
Factory Function

### Parameters
#### Request Body
- **capture_output** (string) - Optional - The capture output format to use.
- **frame_buffer_size** (int) - Optional - The maximum size the frame buffer can grow to.

### Request Example
import d3dshot
d = d3dshot.create(capture_output='numpy', frame_buffer_size=100)
```

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

### Display Detection and Selection

Source: https://context7.com/serpentai/d3dshot/llms.txt

Automatically detects connected displays and allows switching between them for capture. Displays can be listed, selected, and their properties accessed.

```APIDOC
## Display Detection and Selection

### Description
Automatically detects all connected displays with their properties. The primary display is selected by default, but you can switch to any detected display for capture. Displays can be listed, their properties accessed, and the list can be re-detected if the configuration changes.

### Method
Accessing and modifying `d3dshot.D3DShot.displays` and `d3dshot.D3DShot.display` attributes.

### Endpoint
N/A (Instance methods/attributes)

### Parameters
#### Instance Attributes
- **displays** (list) - A list of `Display` objects representing all detected monitors.
- **display** (Display) - The currently selected `Display` object for capture. Can be set to switch the active display.

#### Display Object Properties
- **name** (str) - The name of the display.
- **adapter** (str) - The graphics adapter name.
- **resolution** (tuple) - The resolution of the display (width, height).
- **rotation** (int) - The rotation of the display (0, 90, 180, 270).
- **scale_factor** (float) - The display scaling factor.
- **is_primary** (bool) - Whether this is the primary display.

### Request Example
```python
import d3dshot

d = d3dshot.create()

# List all detected displays
print(d.displays)

# Switch to the second monitor
d.display = d.displays[1]

# Access display properties
print(f"Resolution: {d.display.resolution}")
print(f"Rotation: {d.display.rotation}")
print(f"Scale Factor: {d.display.scale_factor}")
print(f"Is Primary: {d.display.is_primary}")

# Re-detect displays if configuration changed
d.detect_displays()
```

### Response
#### Success Response (200)
- **Display Object** (object) - Properties of the selected or detected display.

#### Response Example
```python
# Example output for d.displays:
# [<Display name=...>, <Display name=...>] 

# Example output for d.display.resolution:
# (1920, 1080)
```
```

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

### Performance Benchmarking

Source: https://context7.com/serpentai/d3dshot/llms.txt

Utilizes the built-in benchmark method to evaluate capture performance over a 60-second window.

```python
import d3dshot

d = d3dshot.create(capture_output="pil")
d.benchmark()
```

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

### PIL Image Creation from Bytes (Python)

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

This code demonstrates how to create a PIL Image object from raw byte data. This method is used by D3DShot's default 'pil' capture output and is contrasted with the more performant NumPy approach due to the need for intermediate Python processing.

```python
PIL.Image.frombytes()
```

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

### Singleton Pattern Behavior

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Illustrates that D3DShot acts as a singleton. Subsequent calls to create() return the initial instance rather than creating a new one.

```python
d = d3dshot.create(capture_output="numpy")
d2 = d3dshot.create(capture_output="pil")
print(d == d2) # Returns True
```

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

### Taking Screenshots to Memory

Source: https://context7.com/serpentai/d3dshot/llms.txt

Captures a single frame from the selected display and returns it in the configured format (PIL Image, NumPy array, PyTorch tensor). Supports capturing specific regions.

```APIDOC
## Taking Screenshots to Memory

### Description
Captures a single frame from the selected display and returns it immediately. The return type matches the capture output format specified during initialization. Supports capturing a specified region of the screen.

### Method
`d3dshot.D3DShot.screenshot(region: tuple = None) -> Union[PIL.Image.Image, np.ndarray, torch.Tensor]`

### Endpoint
N/A (Instance method)

### Parameters
#### Keyword Arguments
- **region** (tuple) - Optional - A tuple representing the capture region in the format (left, top, right, bottom). If None, the entire display is captured. Defaults to None.

### Request Example
```python
import d3dshot

d = d3dshot.create()

# Basic screenshot - returns PIL.Image
img = d.screenshot()
print(img)

# Screenshot with region (left, top, right, bottom)
# Capture only a 200x200 pixel region offset 100px from top-left
region_img = d.screenshot(region=(100, 100, 300, 300))
print(region_img.size)

# With NumPy output
d_numpy = d3dshot.create(capture_output="numpy")
frame = d_numpy.screenshot()
print(f"Shape: {frame.shape}, Dtype: {frame.dtype}")
```

### Response
#### Success Response (200)
- **Captured Frame** (Union[PIL.Image.Image, np.ndarray, torch.Tensor]) - The captured screenshot in the format specified during D3DShot initialization.

#### Response Example
```python
# Example for PIL Image:
# <PIL.Image.Image image mode=RGB size=2560x1440 at 0x...>

# Example for NumPy array:
# Shape: (1440, 2560, 3), Dtype: uint8
```
```

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

### Take Single Screenshots with D3DShot

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Captures a single screenshot. The `screenshot` method returns the image data in a format matching the selected capture output. An optional `region` argument can specify a capture area. The `screenshot_to_disk` method saves the screenshot directly to a file with customizable directory and file name.

```python
# Take a screenshot
d.screenshot()

# Take a screenshot and save it to disk
d.screenshot_to_disk(directory="/path/to/save", file_name="my_screenshot.png")
```

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

### Frame Buffer Configuration

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Details the frame buffer, a thread-safe FIFO queue for storing captures, and how to customize its size.

```APIDOC
## Frame Buffer Configuration

### Description
D3DShot includes a frame buffer implemented as a `collections.deque` to store captures in a thread-safe, first-in, first-out manner. The size of this buffer can be customized during instance creation.

### Method
`create()`

### Endpoint
N/A (Library Function)

### Parameters
#### Keyword Arguments
- **frame_buffer_size** (integer) - Optional - Sets the maximum number of captures the frame buffer can hold. Defaults to 60.

### Request Example
```python
import d3dshot

# Create an instance with a custom frame buffer size of 100
d = d3dshot.create(frame_buffer_size=100)

# Accessing the frame buffer (for inspection, direct use not recommended)
# print(d.frame_buffer)
```

### Response
#### Success Response
- **d** (object) - An instance of D3DShot with the specified frame buffer size.

#### Response Example
```python
d = d3dshot.create(frame_buffer_size=100)
```

### Note
Be aware of potential RAM usage with large frame buffer sizes, as each capture can consume significant memory.
```

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

### Manage Frame Buffer with D3DShot

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Provides methods to interact with the frame buffer, allowing retrieval of the latest frame, specific frames by index, or multiple frames as a list or a stacked array. The `frame_buffer_to_disk` method dumps all current frames in the buffer to image files.

```python
# Get the latest frame
d.get_latest_frame()

# Get a specific frame by index
d.get_frame(X)

# Get multiple frames by indices
d.get_frames([X, Y, Z])

# Get multiple frames stacked
d.get_frame_stack([X, Y, Z], stack_dimension="first")

# Dump the entire frame buffer to disk
d.frame_buffer_to_disk()
```

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

### Capture Specific Screen Region

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Demonstrates how to capture a specific portion of the screen by providing a 4-length tuple (left, top, right, bottom) to the screenshot method.

```python
d.screenshot(region=(100, 100, 300, 300))
```

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

### Singleton Instance Behavior

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Explains that D3DShot acts as a singleton, ensuring only one instance exists per process, and subsequent calls to create() return the existing instance.

```APIDOC
## D3DShot Singleton Behavior

### Description
The D3DShot class is designed as a singleton to comply with Windows limitations on Desktop Duplication instances per process. Any attempt to create a new instance after the first one will return the existing instance.

### Method
`create()`

### Endpoint
N/A (Library Function)

### Parameters
None for demonstrating singleton behavior.

### Request Example
```python
import d3dshot

# Create the first instance
d1 = d3dshot.create(capture_output="numpy")

# Attempt to create a second instance with a different output format
d2 = d3dshot.create(capture_output="pil")

# Verify that d2 is the same instance as d1
print(d1 == d2)
print(d1.capture_output.backend)
```

### Response
#### Success Response
- **True** (boolean) - Indicates that both variables point to the same D3DShot instance.
- **numpy** (string) - The capture output backend of the existing instance (it does not change).

#### Response Example
```
True
<d3dshot.capture_outputs.numpy_capture_output.NumpyCaptureOutput object at 0x...>
```
```

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

### Display Management

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Explains how D3DShot automatically detects displays and allows selection of a specific display for capturing.

```APIDOC
## Display Management

### Description
D3DShot automatically detects all connected displays and their properties upon creation. It defaults to using the primary display but allows you to select any available display for screen captures. Rotation and scaling are handled automatically.

### Method
Attribute access and assignment

### Endpoint
N/A (Library Function)

### Properties
- **d.displays** (list) - A list of `Display` objects representing all detected monitors.
- **d.display** (object) - The currently selected `Display` object for capture. Can be set to another `Display` object from the `d.displays` list.

### Request Example
```python
import d3dshot

d = d3dshot.create()

# Get all detected displays
print(d.displays)

# Get the currently selected display
print(d.display)

# Select a different display (e.g., the second one in the list)
if len(d.displays) > 1:
    d.display = d.displays[1]
    print(d.display)
```

### Response
#### Success Response
- **d.displays** (list) - A list of `Display` objects, each with properties like name, resolution, rotation, scale factor, and primary status.
- **d.display** (object) - The selected `Display` object.

#### Response Example
```
[<Display name=BenQ XL2730Z (DisplayPort) adapter=NVIDIA GeForce GTX 1080 Ti resolution=2560x1440 rotation=0 scale_factor=1.0 primary=True>, ...]
<Display name=BenQ XL2730Z (DisplayPort) adapter=NVIDIA GeForce GTX 1080 Ti resolution=2560x1440 rotation=0 scale_factor=1.0 primary=True>
<Display name=BenQ XL2430T (HDMI) adapter=Intel(R) UHD Graphics 630 resolution=1920x1080 rotation=0 scale_factor=1.0 primary=False>
```
```

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

### PyTorch GPU Accelerated Capture

Source: https://context7.com/serpentai/d3dshot/llms.txt

Demonstrates capturing frames directly as PyTorch tensors on the GPU, bypassing CPU-GPU transfer overhead for deep learning pipelines.

```python
import d3dshot
import time
import torch

d = d3dshot.create(capture_output="pytorch_gpu")
frame = d.screenshot()

d_float = d3dshot.create(capture_output="pytorch_float_gpu")
frame_float = d_float.screenshot()

d.capture(target_fps=30)
time.sleep(1)
while d.is_capturing:
    frame = d.get_latest_frame()
    if frame is not None:
        input_tensor = frame.permute(2, 0, 1).unsqueeze(0).float() / 255.0
    time.sleep(0.033)
d.stop()
```

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

### Configure Frame Buffer Size

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Shows how to customize the size of the internal frame buffer during D3DShot initialization. The buffer is a thread-safe deque used for storing captures.

```python
d = d3dshot.create(frame_buffer_size=100)
```

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

### Region Capturing

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Explains how to capture a specific rectangular region of the screen using the `region` argument.

```APIDOC
## Region Capturing

### Description
All capture methods in D3DShot, including `screenshot()`, accept an optional `region` argument to specify a rectangular area of the screen to capture. This region is defined by a tuple of four integers: (left, top, right, bottom).

### Method
`capture()` or `screenshot()` with `region` argument

### Endpoint
N/A (Library Function)

### Parameters
#### Keyword Arguments
- **region** (tuple of 4 integers) - Optional - Defines the capture area as `(left, top, right, bottom)` in pixels.

### Request Example
```python
import d3dshot

d = d3dshot.create()

# Capture a 200x200 pixel region starting at (100, 100)
region_capture = d.screenshot(region=(100, 100, 300, 300))

# Capture the full screen (no region specified)
full_capture = d.screenshot()
```

### Response
#### Success Response
- **region_capture** (object) - The captured image data for the specified region.
- **full_capture** (object) - The captured image data for the entire screen.

#### Response Example
```
# The returned object will be in the format specified by capture_output (e.g., numpy array, PIL image, PyTorch tensor)
```

### Note
If capturing a scaled display, the `region` coordinates are relative to the non-scaled resolution. Cropping is performed after a full display capture for consistency and performance reasons.
```

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

### Direct Memory Copy with ctypes.memmove (Python)

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

This code snippet demonstrates how to directly copy byte data into a NumPy array's memory using ctypes.memmove. This bypasses much of the Python overhead, leading to significant performance gains for screen capture.

```python
ctypes.memmove(np.empty((size,), dtype=np.uint8).ctypes.data, pointer, size)
```

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

### Frame Buffer Management

Source: https://context7.com/serpentai/d3dshot/llms.txt

Explains how to access the thread-safe FIFO frame buffer, retrieve specific frames by index, and stack frames into NumPy arrays for batch processing.

```python
import d3dshot
import time

d = d3dshot.create(capture_output="numpy", frame_buffer_size=100)
d.capture(target_fps=60)
time.sleep(3)
d.stop()

latest = d.get_latest_frame()
frame_5 = d.get_frame(5)
frames = d.get_frames([0, 1, 2, 3])
frame_stack = d.get_frame_stack([0, 1, 2, 3], stack_dimension="last")
d.frame_buffer_to_disk(directory="./buffer_dump")
```

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

### Screenshot Operations

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Methods for capturing single screenshots or saving them directly to disk.

```APIDOC
## d.screenshot()

### Description
Captures a single screenshot of the selected display.

### Parameters
#### Query Parameters
- **region** (tuple) - Optional - A region tuple defining the area to capture.

### Response
- **image** (object) - A screenshot object matching the selected capture output format.

## d.screenshot_to_disk()

### Description
Captures a screenshot and saves it directly to the specified directory.

### Parameters
- **directory** (string) - Optional - Path to save the file.
- **file_name** (string) - Optional - Name of the file (e.g., image.png).
- **region** (tuple) - Optional - A region tuple defining the area to capture.

### Response
- **path** (string) - The full path to the saved image file.
```

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

### Region-Based Screen Capture

Source: https://context7.com/serpentai/d3dshot/llms.txt

Covers capturing specific screen areas by defining pixel coordinate tuples and setting default regions for subsequent capture operations.

```python
import d3dshot
import time

d = d3dshot.create(capture_output="numpy")
region = (100, 100, 740, 580)

frame = d.screenshot(region=region)
d.capture(target_fps=30, region=region)
time.sleep(2)
d.stop()

d.screenshot_to_disk(file_name="region.png", region=(0, 0, 1280, 720))
d.region = (100, 100, 500, 400)
frame = d.screenshot()
```

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

### High-Speed Capture

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Methods for threaded, non-blocking high-speed screen capture.

```APIDOC
## d.capture()

### Description
Starts a high-speed, threaded screen capture process that pushes frames to the internal buffer.

### Parameters
- **target_fps** (int) - Optional - Target frames per second (default 60).
- **region** (tuple) - Optional - A region tuple defining the area to capture.

### Response
- **success** (boolean) - Returns true if the capture thread was successfully started.
```

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

### Saving Screenshots to Disk

Source: https://context7.com/serpentai/d3dshot/llms.txt

Captures a frame and saves it directly to a file on disk. Supports PNG and JPG formats and allows specifying directory and filename.

```APIDOC
## Saving Screenshots to Disk

### Description
Captures a frame and saves it directly to a file. Supports PNG and JPG formats and returns the full path to the saved file. Allows specifying a custom directory and filename, or saving with an auto-generated timestamped filename.

### Method
`d3dshot.D3DShot.screenshot_to_disk(directory: str = '.', file_name: str = None, region: tuple = None, output_format: str = 'png') -> str`

### Endpoint
N/A (Instance method)

### Parameters
#### Keyword Arguments
- **directory** (str) - Optional - The directory where the screenshot will be saved. Defaults to the current directory (`.`).
- **file_name** (str) - Optional - The name of the file to save. If None, a timestamp-based filename (e.g., `1554298682.5632973.png`) is generated. Defaults to None.
- **region** (tuple) - Optional - A tuple representing the capture region in the format (left, top, right, bottom). If None, the entire display is captured. Defaults to None.
- **output_format** (str) - Optional - The image format to save ('png' or 'jpg'). Defaults to 'png'.

### Request Example
```python
import d3dshot

d = d3dshot.create()

# Save with auto-generated filename (timestamp.png)
file_path = d.screenshot_to_disk()
print(file_path)

# Save with custom directory and filename
file_path = d.screenshot_to_disk(
    directory="./screenshots",
    file_name="capture.png"
)
print(file_path)

# Save a specific region as JPG
file_path = d.screenshot_to_disk(
    directory="./screenshots",
    file_name="region_capture.jpg",
    region=(0, 0, 800, 600),
    output_format='jpg'
)
```

### Response
#### Success Response (200)
- **file_path** (str) - The absolute path to the saved screenshot file.

#### Response Example
```
'./screenshots/capture.png'
```
```

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

### Capture Screenshots to Memory

Source: https://context7.com/serpentai/d3dshot/llms.txt

Captures a single frame from the selected display into memory. Supports full screen or specific region capture with configurable output types.

```python
import d3dshot

d = d3dshot.create()

# Basic screenshot - returns PIL.Image
img = d.screenshot()

# Screenshot with region (left, top, right, bottom)
region_img = d.screenshot(region=(100, 100, 300, 300))

# With NumPy output
d_numpy = d3dshot.create(capture_output="numpy")
frame = d_numpy.screenshot()
```

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

### Save Screenshots to Disk

Source: https://context7.com/serpentai/d3dshot/llms.txt

Saves captured frames directly to the file system. Supports PNG and JPG formats with custom directory and filename options.

```python
import d3dshot

d = d3dshot.create()

# Save with auto-generated filename
file_path = d.screenshot_to_disk()

# Save with custom directory and filename
file_path = d.screenshot_to_disk(
    directory="./screenshots",
    file_name="capture.png"
)
```

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

### Creating PyTorch Tensor from NumPy Array (Python)

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

This code illustrates the process of converting a NumPy array, potentially created using the efficient ctypes method, into a PyTorch tensor. This is a common step when integrating NumPy-based capture with PyTorch workflows.

```python
torch.from_numpy()
```

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

### Image Rotation with NumPy (Python)

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

This code snippet shows how to rotate a NumPy array by 90 degrees. This operation is relevant when handling rotated display outputs, and its performance characteristics are discussed in relation to PyTorch's limitations with negative strides.

```python
np.rot90()
```

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

### Frame Buffer Management

Source: https://github.com/serpentai/d3dshot/blob/dev/README.md

Methods to retrieve and manipulate frames stored in the D3DShot buffer.

```APIDOC
## d.get_latest_frame()

### Description
Retrieves the most recent frame from the buffer.

### Response
- **frame** (object) - The latest frame in the selected format.

## d.get_frame(index)

### Description
Retrieves a specific frame from the buffer by index.

### Parameters
- **index** (int) - Required - The index of the desired frame.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.