# D3DShot
_D3DShot_ is a pure Python implementation of the [Windows Desktop Duplication API](https://docs.microsoft.com/en-us/windows/desktop/direct3ddxgi/desktop-dup-api). It leverages DXGI and Direct3D system libraries to enable extremely fast and robust screen capture functionality for your Python scripts and applications on Windows.
**D3DShot:**
* Is by far the fastest way to capture the screen with Python on Windows 8.1+
* Is very easy to use. If you can remember 10-ish methods, you know the entire thing.
* Covers all common scenarios and use cases:
* Screenshot to memory
* Screenshot to disk
* Screenshot to memory buffer every X seconds (threaded; non-blocking)
* Screenshot to disk every X seconds (threaded; non-blocking)
* High-speed capture to memory buffer (threaded; non-blocking)
* Captures to PIL Images out of the box. Gracefully adds output options if NumPy or PyTorch can be found.
* Detects displays in just about any configuration: Single monitor, multiple monitors on one adapter, multiple monitors on multiple adapters.
* Handles display rotation and scaling for you
* Supports capturing specific regions of the screen
* Is robust and very stable. You can run it for hours / days without performance degradation
* Is even able to capture DirectX 11 / 12 exclusive fullscreen applications and games!
### TL;DR Quick Code Samples
**Screenshot to Memory**
```python
import d3dshot
d = d3dshot.create()
d.screenshot()
```
```
Out[1]: <PIL.Image.Image image mode=RGB size=2560x1440 at 0x1AA7ECB5C88>
```
**Screenshot to Disk**
```python
import d3dshot
d = d3dshot.create()
d.screenshot_to_disk()
```
```
Out[1]: './1554298682.5632973.png'
```
**Screen Capture for 5 Seconds and Grab the Latest Frame**
```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()
```
```
Out[1]: <PIL.Image.Image image mode=RGB size=2560x1440 at 0x1AA044BCF60>
```
**Screen Capture the Second Monitor as NumPy Arrays for 3 Seconds and Grab the 4 Latest Frames as a Stack**
```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
```
```
Out[1]: (1080, 1920, 3, 4)
```
This is barely scratching the surface... Keep reading!
## Requirements
* Windows 8.1+ (64-bit)
* Python 3.6+ (64-bit)
## Installation
```
pip install d3dshot
```
_D3DShot_ leverages DLLs that are already available on your system so the dependencies are very light. Namely:
* [_comtypes_](https://github.com/enthought/comtypes): Internal use. To preserve developer sanity while working with COM interfaces.
* [_Pillow_](https://github.com/python-pillow/Pillow): Default Capture Output. Also used to save to disk as PNG and JPG.
These dependencies will automatically be installed alongside _D3DShot_; No need to worry about them!
##### Extra Step: Laptop Users
Windows has a quirk when using Desktop Duplication on hybrid-GPU systems. Please see the [wiki article](https://github.com/SerpentAI/D3DShot/wiki/Installation-Note:-Laptops) before attempting to use _D3DShot_ on your system.
## Concepts
### Capture Outputs
The desired _Capture Output_ is defined when creating a _D3DShot_ instance. It defines the type of all captured images. By default, all captures will return PIL.Image objects. This is a good option if you mostly intend to take screenshots.
```python
# Captures will be PIL.Image in RGB mode
d = d3dshot.create()
d = d3dshot.create(capture_output="pil")
```
_D3DShot_ is however quite flexible! As your environment meets certain optional sets of requirements, more options become available.
**If _NumPy_ is available**
```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")
```
**If _NumPy_ and _PyTorch_ are available**
```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")
```
**If _NumPy_ and _PyTorch_ are available + _CUDA_ is installed and _torch.cuda.is_available()_**
```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")
# 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")
```
Trying to use a Capture Output for which your environment does not meet the requirements will result in an error.
### Singleton
Windows only allows 1 instance of Desktop Duplication per process. To make sure we fall in line with that limitation to avoid issues, the _D3DShot_ class acts as a singleton. Any subsequent calls to `d3dshot.create()` will always return the existing instance.
```python
d = d3dshot.create(capture_output="numpy")
# Attempting to create a second instance
d2 = d3dshot.create(capture_output="pil")
# Only 1 instance of D3DShot is allowed per process! Returning the existing instance...
# Capture output remains 'numpy'
d2.capture_output.backend
# Out[1]: <d3dshot.capture_outputs.numpy_capture_output.NumpyCaptureOutput at 0x2672be3b8e0>
d == d2
# Out[2]: True
```
### Frame Buffer
When you create a _D3DShot_ instance, a frame buffer is also initialized. It is meant as a thread-safe, first-in, first-out way to hold a certain quantity of captures and is implemented as a `collections.deque`.
By default, the size of the frame buffer is set to 60. You can customize it when creating your _D3DShot_ object.
```python
d = d3dshot.create(frame_buffer_size=100)
```
Be mindful of RAM usage with larger values; You will be dealing with uncompressed images which use up to 100 MB each depending on the resolution.
The frame buffer can be accessed directly with `d.frame_buffer` but the usage of the utility methods instead is recommended.
The buffer is used by the following methods:
* `d.capture()`
* `d.screenshot_every()`
It is always automatically cleared before starting one of these operations.
### Displays
When you create a _D3DShot_ instance, your available displays will automatically be detected along with all their relevant properties.
```python
d.displays
```
```
Out[1]:
[<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>]
```
By default, your primary display will be selected. At all times you can verify which display is set to be used for capture.
```python
d.display
```
```
Out[1]: <Display name=BenQ XL2730Z (DisplayPort) adapter=NVIDIA GeForce GTX 1080 Ti resolution=2560x1440 rotation=0 scale_factor=1.0 primary=True>
```
Selecting another display for capture is as simple as setting `d.display` to another value from `d.displays`
```python
d.display = d.displays[1]
d.display
```
```
Out[1]: <Display name=BenQ XL2430T (HDMI) adapter=Intel(R) UHD Graphics 630 resolution=1080x1920 rotation=90 scale_factor=1.0 primary=False>
```
Display rotation and scaling is detected and handled for you by _D3DShot_:
* Captures on rotated displays will always be in the correct orientation (i.e. matching what you see on your physical displays)
* Captures on scaled displays will always be in full, non-scaled resolution (e.g. 1280x720 at 200% scaling will yield 2560x1440 captures)
### Regions
All capture methods (screenshots included) accept an optional `region` kwarg. The expected value is a 4-length tuple of integers that is to be structured like this:
```
(left, top, right, bottom) # values represent pixels
```
For example, if you want to only capture a 200px by 200px region offset by 100px from both the left and top, you would do:
```python
d.screenshot(region=(100, 100, 300, 300))
```
If you are capturing a scaled display, the region will be computed against the full, non-scaled resolution.
If you go through the source code, you will notice that the region cropping happens after a full display capture. That might seem sub-optimal but testing has revealed that copying a region of the GPU _D3D11Texture2D_ to the destination CPU _D3D11Texture2D_ using _CopySubresourceRegion_ is only faster when the region is very small. In fact, it doesn't take long for larger regions to actually start becoming slower than the full display capture using this method. To make things worse, it adds a lot of complexity by having the surface pitch not match the buffer size and treating rotated displays differently. It was therefore decided that it made more sense to stick to _CopyResource_ in all cases and crop after the fact.
## Usage
**Create a D3DShot instance**
```python
import d3dshot
d = d3dshot.create()
```
`create` accepts 2 optional kwargs:
* `capture_output`: Which capture output to use. See the _Capture Outputs_ section under _Concepts_
* `frame_buffer_size`: The maximum size the frame buffer can grow to. See the _Frame Buffer_ section under _Concepts_
Do NOT import the _D3DShot_ class directly and attempt to initialize it yourself! The `create` helper function initializes and validates a bunch of things for you behind the scenes.
Once you have a _D3DShot_ instance in scope, we can start doing stuff with it!
**List the detected displays**
```python
d.displays
```
**Select a display for capture**
Your primary display is selected by default but if you have a multi-monitor setup, you can select another entry in `d.displays`
```python
d.display = d.displays[1]
```
**Take a screenshot**
```python
d.screenshot()
```
`screenshot` accepts 1 optional kwarg:
* `region`: A region tuple. See the _Regions_ section under _Concepts_
_Returns_: A screenshot with a format that matches the capture output you selected when creating your _D3DShot_ object
**Take a screenshot and save it to disk**
```python
d.screenshot_to_disk()
```
`screenshot_to_disk` accepts 3 optional kwargs:
* `directory`: The path / directory where to write the file. If omitted, the working directory of the program will be used
* `file_name`: The file name to use. Permitted extensions are: _.png_, _.jpg_. If omitted, the file name will be `<time.time()>.png`
* `region`: A region tuple. See the _Regions_ section under _Concepts_
_Returns_: A string representing the full path to the saved image file
**Take a screenshot every X seconds**
```python
d.screenshot_every(X) # Where X is a number representing seconds
```
This operation is threaded and non-blocking. It will keep running until `d.stop()` is called. Captures are pushed to the frame buffer.
`screenshot_every` accepts 1 optional kwarg:
* `region`: A region tuple. See the _Regions_ section under _Concepts_
_Returns_: A boolean indicating whether or not the capture thread was started
**Take a screenshot every X seconds and save it to disk**
```python
d.screenshot_to_disk_every(X) # Where X is a number representing seconds
```
This operation is threaded and non-blocking. It will keep running until `d.stop()` is called.
`screenshot_to_disk_every` accepts 2 optional kwargs:
* `directory`: The path / directory where to write the file. If omitted, the working directory of the program will be used
* `region`: A region tuple. See the _Regions_ section under _Concepts_
_Returns_: A boolean indicating whether or not the capture thread was started
**Start a high-speed screen capture**
```python
d.capture()
```
This operation is threaded and non-blocking. It will keep running until `d.stop()` is called. Captures are pushed to the frame buffer.
`capture` accepts 2 optional kwargs:
* `target_fps`: How many captures per second to aim for. The effective capture rate will go under if the system can't keep up but it will never go over this target. It is recommended to set this to a reasonable value for your use case in order not to waste system resources. Default is set to 60.
* `region`: A region tuple. See the _Regions_ section under _Concepts_
_Returns_: A boolean indicating whether or not the capture thread was started
**Grab the latest frame from the buffer**
```python
d.get_latest_frame()
```
_Returns_: A frame with a format that matches the capture output you selected when creating your _D3DShot_ object
**Grab a specific frame from the buffer**
```python
d.get_frame(X) # Where X is the index of the desired frame. Needs to be < len(d.frame_buffer)
```
_Returns_: A frame with a format that matches the capture output you selected when creating your _D3DShot_ object
**Grab specific frames from the buffer**
```python
d.get_frames([X, Y, Z, ...]) # Where X, Y, Z are valid indices to desired frames
```
_Returns_: A list of frames with a format that matches the capture output you selected when creating your _D3DShot_ object
**Grab specific frames from the buffer as a stack**
```python
d.get_frame_stack([X, Y, Z, ...], stack_dimension="first|last") # Where X, Y, Z are valid indices to desired frames
```
Only has an effect on NumPy and PyTorch capture outputs.
`get_frame_stack` accepts 1 optional kwarg:
* `stack_dimension`: One of _first_, _last_. Which axis / dimension to perform the stack on
_Returns_: A single array stacked on the specified dimension with a format that matches the capture output you selected when creating your _D3DShot_ object. If the capture output is not stackable, returns a list of frames.
**Dump the frame buffer to disk**
The files will be named according to this convention: `<frame buffer index>.png`
```python
d.frame_buffer_to_disk()
```
`frame_buffer_to_disk` accepts 1 optional kwarg:
* `directory`: The path / directory where to write the files. If omitted, the working directory of the program will be used
_Returns_: None
## Performance
Measuring the exact performance of the Windows Desktop Duplication API proves to be a little complicated because it will only return new texture data if the contents of the screen has changed. This is optimal for performance but it makes it difficult to express in terms of frames per second, the measurement people tend to expect for benchmarks. Ultimately the solution ended up being to run a high FPS video game on the display to capture to make sure the screen contents is different at all times while benchmarking.
As always, remember that benchmarks are inherently flawed and highly depend on your individual hardware configuration and other circumstances. Use the numbers below as a relative indication of what to expect from _D3DShot_, not as some sort of absolute truth.
| | 2560x1440 on _NVIDIA GTX 1080 Ti_ | 1920x1080 on _Intel UHD Graphics 630_ | 1080x1920 (vertical) on _Intel UHD Graphics 630_ |
|-------------------------|-----------------------------------|---------------------------------------|--------------------------------------------------|
| **"pil"** | 29.717 FPS | 47.75 FPS | 35.95 FPS |
| **"numpy"** | **57.667 FPS** | **58.1 FPS** | **58.033 FPS** |
| **"numpy_float"** | 18.783 FPS | 29.05 FPS | 27.517 FPS |
| **"pytorch"** | **57.867 FPS** | **58.1 FPS** | 34.817 FPS |
| **"pytorch_float"** | 18.767 FPS | 28.367 FPS | 27.017 FPS |
| **"pytorch_gpu"** | 27.333 FPS | 35.767 FPS | 34.8 FPS |
| **"pytorch_float_gpu"** | 27.267 FPS | 37.383 FPS | 35.033 FPS |
The absolute fastest capture outputs appear to be _"numpy"_ and unrotated _"pytorch"_; all averaging around 58 FPS. In Python land, this is FAST!
#### How is the "numpy" capture output performance _that_ good?
NumPy arrays have a ctypes interface that can give you their raw memory address (`X.ctypes.data`). If you have the memory address and size of another byte buffer, which is what we end up with by processing what returns from the Desktop Duplication API, you can use `ctypes.memmove` to copy that byte buffer directly to the NumPy structure, effectively bypassing as much Python as possible.
In practice it ends up looking like this:
```python
ctypes.memmove(np.empty((size,), dtype=np.uint8).ctypes.data, pointer, size)
```
This low-level operation is extremely fast, leaving everything else that would normally compete with NumPy in the dust.
#### Why is the "pytorch" capture output slower on rotated displays?
Don't tell anyone but the reason it can compete with NumPy in the first place is only because... _it is_ generated from a NumPy array built from the method above! If you sniff around the code, you will indeed find `torch.from_numpy()` scattered around. This pretty much matches the speed of the "numpy" capture output 1:1, except when dealing with a rotated display. Display rotation is handled by `np.rot90()` calls which yields negative strides on that array. Negative strides are understood and perform well under NumPy but are still unsupported in PyTorch at the time of writing. To address this, an additional copy operation is needed to bring it back to a contiguous array which imposes a performance penalty.
#### Why is the "pil" capture output, being the default, not the fastest?
PIL has no ctypes interface like NumPy so a bytearray needs to be read into Python first and then fed to `PIL.Image.frombytes()`. This is still fast in Python terms, but it just cannot match the speed of the low-level NumPy method.
It remains the default capture output because:
1) PIL Image objects tend to be familiar to Python users
2) It's a way lighter / simpler dependency for a library compared to NumPy or PyTorch
#### Why are the float versions of capture outputs slower?
The data of the Direct3D textures made accessible by the Desktop Duplication API is formatted as bytes. To represent this data as normalized floats instead, a type cast and element-wise division needs to be performed on the array holding those bytes. This imposes a major performance penalty. Interestingly, you can see this performance penalty mitigated on GPU PyTorch tensors since the element-wise division can be massively parallelized on the device.
#
_Crafted with ❤ by Serpent.AI 🐍_
[Twitter](https://twitter.com/Serpent_AI) - [Twitch](https://www.twitch.tv/serpent_ai)
Raw data
{
"_id": null,
"home_page": "https://github.com/ok-oldking/D3DShot",
"name": "ok-d3dshot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "Screen Capture, Screenshot, Computer Vision, Windows",
"author": "Nicholas Brochu",
"author_email": "nicholas@serpent.ai",
"download_url": "https://files.pythonhosted.org/packages/a4/2e/4ffae25148b8e54ee8444714ef20a4cf5e3a0ce0614a489b537c42a141d1/ok_d3dshot-0.1.5.tar.gz",
"platform": null,
"description": "# D3DShot\n\n\n_D3DShot_ is a pure Python implementation of the [Windows Desktop Duplication API](https://docs.microsoft.com/en-us/windows/desktop/direct3ddxgi/desktop-dup-api). It leverages DXGI and Direct3D system libraries to enable extremely fast and robust screen capture functionality for your Python scripts and applications on Windows. \n\n**D3DShot:**\n\n* Is by far the fastest way to capture the screen with Python on Windows 8.1+\n* Is very easy to use. If you can remember 10-ish methods, you know the entire thing.\n* Covers all common scenarios and use cases:\n\t* Screenshot to memory\n\t* Screenshot to disk\n\t* Screenshot to memory buffer every X seconds (threaded; non-blocking)\n\t* Screenshot to disk every X seconds (threaded; non-blocking)\n\t* High-speed capture to memory buffer (threaded; non-blocking)\n* Captures to PIL Images out of the box. Gracefully adds output options if NumPy or PyTorch can be found.\n* Detects displays in just about any configuration: Single monitor, multiple monitors on one adapter, multiple monitors on multiple adapters.\n* Handles display rotation and scaling for you\n* Supports capturing specific regions of the screen\n* Is robust and very stable. You can run it for hours / days without performance degradation\n* Is even able to capture DirectX 11 / 12 exclusive fullscreen applications and games!\n\n\n### TL;DR Quick Code Samples\n\n**Screenshot to Memory**\n\n```python\nimport d3dshot\n\nd = d3dshot.create()\nd.screenshot()\n```\n```\nOut[1]: <PIL.Image.Image image mode=RGB size=2560x1440 at 0x1AA7ECB5C88>\n```\n\n**Screenshot to Disk**\n```python\nimport d3dshot\n\nd = d3dshot.create()\nd.screenshot_to_disk()\n```\n```\nOut[1]: './1554298682.5632973.png'\n```\n\n**Screen Capture for 5 Seconds and Grab the Latest Frame**\n```python\nimport d3dshot\nimport time\n\nd = d3dshot.create()\n\nd.capture()\ntime.sleep(5) # Capture is non-blocking so we wait explicitely\nd.stop()\n\nd.get_latest_frame()\n```\n```\nOut[1]: <PIL.Image.Image image mode=RGB size=2560x1440 at 0x1AA044BCF60>\n```\n\n**Screen Capture the Second Monitor as NumPy Arrays for 3 Seconds and Grab the 4 Latest Frames as a Stack**\n```python\nimport d3dshot\nimport time\n\nd = d3dshot.create(capture_output=\"numpy\")\n\nd.display = d.displays[1]\n\nd.capture()\ntime.sleep(3) # Capture is non-blocking so we wait explicitely\nd.stop()\n\nframe_stack = d.get_frame_stack((0, 1, 2, 3), stack_dimension=\"last\")\nframe_stack.shape\n```\n```\nOut[1]: (1080, 1920, 3, 4)\n```\n\nThis is barely scratching the surface... Keep reading!\n\n\n## Requirements\n\n* Windows 8.1+ (64-bit)\n* Python 3.6+ (64-bit)\n\n## Installation\n\n```\npip install d3dshot\n```\n\n_D3DShot_ leverages DLLs that are already available on your system so the dependencies are very light. Namely:\n\n* [_comtypes_](https://github.com/enthought/comtypes): Internal use. To preserve developer sanity while working with COM interfaces.\n* [_Pillow_](https://github.com/python-pillow/Pillow): Default Capture Output. Also used to save to disk as PNG and JPG.\n\nThese dependencies will automatically be installed alongside _D3DShot_; No need to worry about them!\n\n##### Extra Step: Laptop Users\n\nWindows has a quirk when using Desktop Duplication on hybrid-GPU systems. Please see the [wiki article](https://github.com/SerpentAI/D3DShot/wiki/Installation-Note:-Laptops) before attempting to use _D3DShot_ on your system.\n\n## Concepts\n\n### Capture Outputs\n\nThe desired _Capture Output_ is defined when creating a _D3DShot_ instance. It defines the type of all captured images. By default, all captures will return PIL.Image objects. This is a good option if you mostly intend to take screenshots.\n\n```python\n# Captures will be PIL.Image in RGB mode\nd = d3dshot.create()\nd = d3dshot.create(capture_output=\"pil\")\n```\n\n_D3DShot_ is however quite flexible! As your environment meets certain optional sets of requirements, more options become available.\n\n\n**If _NumPy_ is available**\n\n```python\n# Captures will be np.ndarray of dtype uint8 with values in range (0, 255)\nd = d3dshot.create(capture_output=\"numpy\")\n\n# Captures will be np.ndarray of dtype float64 with normalized values in range (0.0, 1.0)\nd = d3dshot.create(capture_output=\"numpy_float\") \n```\n\n**If _NumPy_ and _PyTorch_ are available**\n\n```python\n# Captures will be torch.Tensor of dtype uint8 with values in range (0, 255)\nd = d3dshot.create(capture_output=\"pytorch\")\n\n# Captures will be torch.Tensor of dtype float64 with normalized values in range (0.0, 1.0)\nd = d3dshot.create(capture_output=\"pytorch_float\")\n```\n\n**If _NumPy_ and _PyTorch_ are available + _CUDA_ is installed and _torch.cuda.is_available()_**\n\n```python\n# Captures will be torch.Tensor of dtype uint8 with values in range (0, 255) on device cuda:0\nd = d3dshot.create(capture_output=\"pytorch_gpu\")\n\n# Captures will be torch.Tensor of dtype float64 with normalized values in range (0.0, 1.0) on device cuda:0\nd = d3dshot.create(capture_output=\"pytorch_float_gpu\")\n```\n\nTrying to use a Capture Output for which your environment does not meet the requirements will result in an error.\n\n### Singleton\n\nWindows only allows 1 instance of Desktop Duplication per process. To make sure we fall in line with that limitation to avoid issues, the _D3DShot_ class acts as a singleton. Any subsequent calls to `d3dshot.create()` will always return the existing instance.\n\n```python\nd = d3dshot.create(capture_output=\"numpy\")\n\n# Attempting to create a second instance\nd2 = d3dshot.create(capture_output=\"pil\")\n# Only 1 instance of D3DShot is allowed per process! Returning the existing instance...\n\n# Capture output remains 'numpy'\nd2.capture_output.backend\n# Out[1]: <d3dshot.capture_outputs.numpy_capture_output.NumpyCaptureOutput at 0x2672be3b8e0>\n\nd == d2\n# Out[2]: True\n``` \n\n\n### Frame Buffer\n\nWhen you create a _D3DShot_ instance, a frame buffer is also initialized. It is meant as a thread-safe, first-in, first-out way to hold a certain quantity of captures and is implemented as a `collections.deque`.\n\nBy default, the size of the frame buffer is set to 60. You can customize it when creating your _D3DShot_ object.\n\n```python\nd = d3dshot.create(frame_buffer_size=100)\n```\n\nBe mindful of RAM usage with larger values; You will be dealing with uncompressed images which use up to 100 MB each depending on the resolution.\n\nThe frame buffer can be accessed directly with `d.frame_buffer` but the usage of the utility methods instead is recommended.\n\nThe buffer is used by the following methods:\n\n* `d.capture()`\n* `d.screenshot_every()`\n\nIt is always automatically cleared before starting one of these operations.\n\n### Displays\n\nWhen you create a _D3DShot_ instance, your available displays will automatically be detected along with all their relevant properties.\n\n```python\nd.displays\n```\n```\nOut[1]: \n[<Display name=BenQ XL2730Z (DisplayPort) adapter=NVIDIA GeForce GTX 1080 Ti resolution=2560x1440 rotation=0 scale_factor=1.0 primary=True>,\n <Display name=BenQ XL2430T (HDMI) adapter=Intel(R) UHD Graphics 630 resolution=1920x1080 rotation=0 scale_factor=1.0 primary=False>]\n```\n\nBy default, your primary display will be selected. At all times you can verify which display is set to be used for capture.\n\n```python\nd.display\n```\n```\nOut[1]: <Display name=BenQ XL2730Z (DisplayPort) adapter=NVIDIA GeForce GTX 1080 Ti resolution=2560x1440 rotation=0 scale_factor=1.0 primary=True>\n```\n\nSelecting another display for capture is as simple as setting `d.display` to another value from `d.displays`\n```python\nd.display = d.displays[1]\nd.display\n```\n```\nOut[1]: <Display name=BenQ XL2430T (HDMI) adapter=Intel(R) UHD Graphics 630 resolution=1080x1920 rotation=90 scale_factor=1.0 primary=False>\n```\n\nDisplay rotation and scaling is detected and handled for you by _D3DShot_:\n\n* Captures on rotated displays will always be in the correct orientation (i.e. matching what you see on your physical displays)\n* Captures on scaled displays will always be in full, non-scaled resolution (e.g. 1280x720 at 200% scaling will yield 2560x1440 captures)\n\n### Regions\n\nAll capture methods (screenshots included) accept an optional `region` kwarg. The expected value is a 4-length tuple of integers that is to be structured like this:\n\n```\n(left, top, right, bottom) # values represent pixels\n```\n\nFor example, if you want to only capture a 200px by 200px region offset by 100px from both the left and top, you would do:\n\n```python\nd.screenshot(region=(100, 100, 300, 300))\n```\n\nIf you are capturing a scaled display, the region will be computed against the full, non-scaled resolution. \n\nIf you go through the source code, you will notice that the region cropping happens after a full display capture. That might seem sub-optimal but testing has revealed that copying a region of the GPU _D3D11Texture2D_ to the destination CPU _D3D11Texture2D_ using _CopySubresourceRegion_ is only faster when the region is very small. In fact, it doesn't take long for larger regions to actually start becoming slower than the full display capture using this method. To make things worse, it adds a lot of complexity by having the surface pitch not match the buffer size and treating rotated displays differently. It was therefore decided that it made more sense to stick to _CopyResource_ in all cases and crop after the fact.\n\n## Usage\n\n**Create a D3DShot instance**\n\n```python\nimport d3dshot\n\nd = d3dshot.create()\n```\n\n`create` accepts 2 optional kwargs:\n\n* `capture_output`: Which capture output to use. See the _Capture Outputs_ section under _Concepts_\n* `frame_buffer_size`: The maximum size the frame buffer can grow to. See the _Frame Buffer_ section under _Concepts_\n\nDo NOT import the _D3DShot_ class directly and attempt to initialize it yourself! The `create` helper function initializes and validates a bunch of things for you behind the scenes.\n\nOnce you have a _D3DShot_ instance in scope, we can start doing stuff with it!\n\n**List the detected displays**\n\n```python\nd.displays\n```\n\n**Select a display for capture**\n\nYour primary display is selected by default but if you have a multi-monitor setup, you can select another entry in `d.displays` \n\n```python\nd.display = d.displays[1]\n```\n\n**Take a screenshot**\n\n```python\nd.screenshot()\n```\n\n`screenshot` accepts 1 optional kwarg:\n\n* `region`: A region tuple. See the _Regions_ section under _Concepts_\n\n_Returns_: A screenshot with a format that matches the capture output you selected when creating your _D3DShot_ object\n\n**Take a screenshot and save it to disk**\n\n```python\nd.screenshot_to_disk()\n```\n\n`screenshot_to_disk` accepts 3 optional kwargs:\n\n* `directory`: The path / directory where to write the file. If omitted, the working directory of the program will be used\n* `file_name`: The file name to use. Permitted extensions are: _.png_, _.jpg_. If omitted, the file name will be `<time.time()>.png` \n* `region`: A region tuple. See the _Regions_ section under _Concepts_\n\n_Returns_: A string representing the full path to the saved image file\n\n**Take a screenshot every X seconds**\n\n```python\nd.screenshot_every(X) # Where X is a number representing seconds\n```\n\nThis operation is threaded and non-blocking. It will keep running until `d.stop()` is called. Captures are pushed to the frame buffer.\n\n`screenshot_every` accepts 1 optional kwarg:\n\n* `region`: A region tuple. See the _Regions_ section under _Concepts_\n\n_Returns_: A boolean indicating whether or not the capture thread was started\n\n**Take a screenshot every X seconds and save it to disk**\n\n```python\nd.screenshot_to_disk_every(X) # Where X is a number representing seconds\n```\n\nThis operation is threaded and non-blocking. It will keep running until `d.stop()` is called.\n\n`screenshot_to_disk_every` accepts 2 optional kwargs:\n\n* `directory`: The path / directory where to write the file. If omitted, the working directory of the program will be used\n* `region`: A region tuple. See the _Regions_ section under _Concepts_\n\n_Returns_: A boolean indicating whether or not the capture thread was started\n\n**Start a high-speed screen capture**\n\n```python\nd.capture()\n```\n\nThis operation is threaded and non-blocking. It will keep running until `d.stop()` is called. Captures are pushed to the frame buffer.\n\n`capture` accepts 2 optional kwargs:\n\n* `target_fps`: How many captures per second to aim for. The effective capture rate will go under if the system can't keep up but it will never go over this target. It is recommended to set this to a reasonable value for your use case in order not to waste system resources. Default is set to 60.\n* `region`: A region tuple. See the _Regions_ section under _Concepts_\n\n_Returns_: A boolean indicating whether or not the capture thread was started\n\n**Grab the latest frame from the buffer**\n\n```python\nd.get_latest_frame()\n```\n\n_Returns_: A frame with a format that matches the capture output you selected when creating your _D3DShot_ object\n\n**Grab a specific frame from the buffer**\n\n```python\nd.get_frame(X) # Where X is the index of the desired frame. Needs to be < len(d.frame_buffer)\n```\n\n_Returns_: A frame with a format that matches the capture output you selected when creating your _D3DShot_ object\n\n**Grab specific frames from the buffer**\n\n```python\nd.get_frames([X, Y, Z, ...]) # Where X, Y, Z are valid indices to desired frames\n```\n\n_Returns_: A list of frames with a format that matches the capture output you selected when creating your _D3DShot_ object\n\n**Grab specific frames from the buffer as a stack**\n\n```python\nd.get_frame_stack([X, Y, Z, ...], stack_dimension=\"first|last\") # Where X, Y, Z are valid indices to desired frames\n```\n\nOnly has an effect on NumPy and PyTorch capture outputs.\n\n`get_frame_stack` accepts 1 optional kwarg:\n\n* `stack_dimension`: One of _first_, _last_. Which axis / dimension to perform the stack on\n\n_Returns_: A single array stacked on the specified dimension with a format that matches the capture output you selected when creating your _D3DShot_ object. If the capture output is not stackable, returns a list of frames.\n\n**Dump the frame buffer to disk**\n\nThe files will be named according to this convention: `<frame buffer index>.png`\n\n```python\nd.frame_buffer_to_disk()\n```\n\n`frame_buffer_to_disk` accepts 1 optional kwarg:\n\n* `directory`: The path / directory where to write the files. If omitted, the working directory of the program will be used\n\n_Returns_: None\n\n## Performance\n\nMeasuring the exact performance of the Windows Desktop Duplication API proves to be a little complicated because it will only return new texture data if the contents of the screen has changed. This is optimal for performance but it makes it difficult to express in terms of frames per second, the measurement people tend to expect for benchmarks. Ultimately the solution ended up being to run a high FPS video game on the display to capture to make sure the screen contents is different at all times while benchmarking.\n\nAs always, remember that benchmarks are inherently flawed and highly depend on your individual hardware configuration and other circumstances. Use the numbers below as a relative indication of what to expect from _D3DShot_, not as some sort of absolute truth.\n\n| | 2560x1440 on _NVIDIA GTX 1080 Ti_ | 1920x1080 on _Intel UHD Graphics 630_ | 1080x1920 (vertical) on _Intel UHD Graphics 630_ |\n|-------------------------|-----------------------------------|---------------------------------------|--------------------------------------------------|\n| **\"pil\"** | 29.717 FPS | 47.75 FPS | 35.95 FPS |\n| **\"numpy\"** | **57.667 FPS** | **58.1 FPS** | **58.033 FPS** |\n| **\"numpy_float\"** | 18.783 FPS | 29.05 FPS | 27.517 FPS |\n| **\"pytorch\"** | **57.867 FPS** | **58.1 FPS** | 34.817 FPS |\n| **\"pytorch_float\"** | 18.767 FPS | 28.367 FPS | 27.017 FPS |\n| **\"pytorch_gpu\"** | 27.333 FPS | 35.767 FPS | 34.8 FPS |\n| **\"pytorch_float_gpu\"** | 27.267 FPS | 37.383 FPS | 35.033 FPS |\n\nThe absolute fastest capture outputs appear to be _\"numpy\"_ and unrotated _\"pytorch\"_; all averaging around 58 FPS. In Python land, this is FAST! \n\n#### How is the \"numpy\" capture output performance _that_ good?\n\nNumPy arrays have a ctypes interface that can give you their raw memory address (`X.ctypes.data`). If you have the memory address and size of another byte buffer, which is what we end up with by processing what returns from the Desktop Duplication API, you can use `ctypes.memmove` to copy that byte buffer directly to the NumPy structure, effectively bypassing as much Python as possible.\n\nIn practice it ends up looking like this:\n```python\nctypes.memmove(np.empty((size,), dtype=np.uint8).ctypes.data, pointer, size)\n```\n\nThis low-level operation is extremely fast, leaving everything else that would normally compete with NumPy in the dust.\n\n#### Why is the \"pytorch\" capture output slower on rotated displays?\n\nDon't tell anyone but the reason it can compete with NumPy in the first place is only because... _it is_ generated from a NumPy array built from the method above! If you sniff around the code, you will indeed find `torch.from_numpy()` scattered around. This pretty much matches the speed of the \"numpy\" capture output 1:1, except when dealing with a rotated display. Display rotation is handled by `np.rot90()` calls which yields negative strides on that array. Negative strides are understood and perform well under NumPy but are still unsupported in PyTorch at the time of writing. To address this, an additional copy operation is needed to bring it back to a contiguous array which imposes a performance penalty.\n\n#### Why is the \"pil\" capture output, being the default, not the fastest?\n\nPIL has no ctypes interface like NumPy so a bytearray needs to be read into Python first and then fed to `PIL.Image.frombytes()`. This is still fast in Python terms, but it just cannot match the speed of the low-level NumPy method.\n\nIt remains the default capture output because:\n\n1) PIL Image objects tend to be familiar to Python users\n2) It's a way lighter / simpler dependency for a library compared to NumPy or PyTorch\n\n#### Why are the float versions of capture outputs slower?\n\nThe data of the Direct3D textures made accessible by the Desktop Duplication API is formatted as bytes. To represent this data as normalized floats instead, a type cast and element-wise division needs to be performed on the array holding those bytes. This imposes a major performance penalty. Interestingly, you can see this performance penalty mitigated on GPU PyTorch tensors since the element-wise division can be massively parallelized on the device.\n\n#\n\n_Crafted with \u2764 by Serpent.AI \ud83d\udc0d_ \n[Twitter](https://twitter.com/Serpent_AI) - [Twitch](https://www.twitch.tv/serpent_ai)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Extremely Fast and Robust Screen Capture on Windows with the Desktop Duplication API",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/ok-oldking/D3DShot",
"Repository": "https://github.com/ok-oldking/D3DShot"
},
"split_keywords": [
"screen capture",
" screenshot",
" computer vision",
" windows"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "07922734784dd8a2a2d60b9170ea4cf122ff99270cef1378191780796be62ed9",
"md5": "5eba94acaaaa91e9f8976a179398e70c",
"sha256": "a303d962f1a449571e6bb08ee5a97babf9884af4508b9b5951eb177439997f93"
},
"downloads": -1,
"filename": "ok_d3dshot-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5eba94acaaaa91e9f8976a179398e70c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 24450,
"upload_time": "2024-05-31T10:10:29",
"upload_time_iso_8601": "2024-05-31T10:10:29.190554Z",
"url": "https://files.pythonhosted.org/packages/07/92/2734784dd8a2a2d60b9170ea4cf122ff99270cef1378191780796be62ed9/ok_d3dshot-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a42e4ffae25148b8e54ee8444714ef20a4cf5e3a0ce0614a489b537c42a141d1",
"md5": "13db28f4f95f8b74e0caa44b4fceb03a",
"sha256": "51a1d56c0343d175ddf0ee6824688e05a54b26c7a39f8085aa7f1d2a7f003be7"
},
"downloads": -1,
"filename": "ok_d3dshot-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "13db28f4f95f8b74e0caa44b4fceb03a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 19604,
"upload_time": "2024-05-31T10:10:31",
"upload_time_iso_8601": "2024-05-31T10:10:31.864535Z",
"url": "https://files.pythonhosted.org/packages/a4/2e/4ffae25148b8e54ee8444714ef20a4cf5e3a0ce0614a489b537c42a141d1/ok_d3dshot-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-31 10:10:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ok-oldking",
"github_project": "D3DShot",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ok-d3dshot"
}
JSON
