DXcam: grab() can return None, and BGRA is the only default
A Python high-performance screen capture library for Windows using Desktop Duplication API - Updated 2026
At a glance
- What is it?
- DXcam is a Windows screen capture library built on the Desktop Duplication API with two backends. The minimal install produces only BGRA frames, grab() returns None when nothing new was rendered, release() is terminal, and the one performance figure in the README carries no method.
- Who is it for?
- DXcam suits someone building a capture loop on Windows who needs a modern alternative to a screen-grab wrapper and who is willing to read the backend and processor notes before choosing options. It does not suit someone who wants RGB frames out of a two-dependency install, because the lean path is BGRA only and every other colour mode pulls in OpenCV or compiled kernels.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 60 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- ra1nty/DXcam800 ★ · -3
| Repository | 2026-09-11 | 2026-11-21 |
|---|---|---|
| ra1nty/DXcam | 803 | 800 |
-3 Stars in the last 71 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
grab() can return None, and release() is a one-way door
Two lifecycle facts sit at opposite ends of the API and both are stated plainly. At the read end, `grab()` returns a `numpy.ndarray`, and also returns `None` when no new frame has been rendered since the last capture. That behaviour is marked as kept for backward compatibility, and the escape is `camera.grab(new_frame_only=False)` to always take the latest frame. A pipeline that assumes an array on every call will fault on a quiet desktop. At the disposal end, `release()` stops capture, frees buffers, and releases capture resources, and the instance cannot be reused afterwards. The example makes the consequence explicit:
camera = dxcam.create(output_idx=0, output_color="BGR")
camera.release()
# camera.start() # raises RuntimeErrorA context manager is offered as the tidy alternative, and it releases automatically on exit.
BGRA is the only colour mode the minimal install can produce
The supported output modes are RGB, RGBA, BGR, BGRA and GRAY, and the notes under them are not symmetrical. `BGRA` does not require OpenCV and is called the leanest dependency path. Every other mode requires a conversion step, and the conversion is done either by `cv2` or by a compiled `numpy` backend. The base install has two dependencies, comtypes and numpy, so out of the box the only mode that works is the one nobody asks for. A user who writes `output_color="RGB"` on a minimal install has to add the OpenCV extra or build the compiled kernels, and the mode is set at creation time, so the camera has to be recreated to change it. This is the single most likely reason a first attempt at this library appears to fail.
The compiled kernels sit behind a build variable and fast-math flags
The alternative to OpenCV is a Cython extension, and it is not built by default. setup.py defines a helper that returns an empty extension list unless `DXCAM_BUILD_CYTHON` equals 1, and the error it raises when the variable is set but the toolchain is missing is explicit: DXCAM_BUILD_CYTHON=1 requires Cython and NumPy to be available in the build environment. The extension is `dxcam.processor._numpy_kernels`, built from `_numpy_kernels.pyx` with `language_level="3"`, and the Cython extra is pinned to exactly 3.1.1. The compile flags are worth reading:
if sys.platform.startswith("win"):
return ["/O2", "/fp:fast", "/openmp"]
return ["-O3", "-ffast-math", "-fopenmp"]`/fp:fast` and `-ffast-math` both permit reassociation and other relaxations of floating point semantics, and OpenMP is enabled on both platforms.
The full-feature install omits the kernels it offers as the alternative
The README names two install shapes. The minimal one is `pip install dxcam`. The other is labelled full feature, described as including OpenCV-based colour conversion and WinRT capture backend support, and written as `pip install "dxcam[cv2,winrt]"`. The extras declared in the packaging metadata are three: `cv2` with a single package, `cython` pinned to one version, and `winrt` with nine separate winrt runtime and namespace packages. So the command advertised as full feature requests two of the three and leaves out the one that provides the alternative to OpenCV. Nothing in the wording says so, and the alternative is mentioned in the processor notes as a peer of `cv2` rather than as something the full install already gave you. Published wheels ship the kernels already built, so this gap only bites source installs.
The cursor renders on winrt and not on the default backend
Two capture backends are supported. `dxgi` is the default and is described as the Desktop Duplication path with broad compatibility. `winrt` is the Windows Graphics Capture path. The choice is not just about performance, because the guidance includes one hard functional rule: if you need cursor rendering, use `winrt`. Everything else is softer, starting with `dxgi` for most workloads and especially for one-shot grab, and trying `winrt` if it performs better or fits application constraints. So the default backend silently omits the mouse pointer from captured frames, which matters for any recording, tutorial capture, or computer vision pipeline that expects a visible pointer. The two backends are selected at creation time:
camera = dxcam.create(backend="dxgi")
camera = dxcam.create(backend="winrt")Both first acquire a BGRA frame, and the processor backend then does rotation, cropping and colour conversion.
Frame timestamps come from different clocks on each backend
Timestamps are read as seconds from the most recent frame, and the example retrieves them as a pair:
camera.start(target_fps=60)
frame, ts = camera.get_latest_frame(with_timestamp=True)
camera.stop()Where the number comes from depends on the backend. For `dxgi` the value comes from `DXGI_OUTDUPL_FRAME_INFO.LastPresentTime`. For `winrt` it is derived from the WinRT `SystemRelativeTime` property. The documentation does not state that values from the two backends are on the same time base, and they are named differently, which means a pipeline that switches backends has to decide for itself whether the timestamps can be compared across a switch. A second version split is documented alongside: on Python 3.11 and later the pacing relies on the Windows high-resolution timer behaviour that `time.sleep()` already uses, while on older versions the library calls WinAPI waitable timers directly.
The ring buffer holds eight frames, and video_mode repeats them
Capture that runs in the background uses a fixed-size in-memory ring buffer, and new frames overwrite old ones when it fills. The size is set at creation:
camera = dxcam.create(max_buffer_len=120) # default is 8Eight frames is a small default, and `get_latest_frame()` blocks until one is available. A second behaviour changes what the data means. With `video_mode=True`, the buffer is filled at the target frame rate by reusing the previous frame when no new one was rendered, so a consumer counting frames is counting ticks rather than distinct captures. Pacing is separate again, with a default target of 60 and an explicit note that anything above 120 is resource heavy:
camera.start(target_fps=120) # default to 60, greater than 120 is resource heavyWhile `start()` capture is running, calling `grab()` reads from the ring buffer instead of polling DXGI directly, so the same method means two different things depending on state. Zero-copy variants exist for both entry points, `grab_view()` and `get_latest_frame_view()`, and the warning attached to them applies to both: the view is faster but the underlying buffer can be overwritten by a later capture. Devices and outputs are addressed by index, so a multi-GPU machine takes one camera per device and output pair, and the enumeration helpers `device_info()` and `output_info()` return the adapter name, dedicated VRAM, vendor id, per output resolution, rotation and whether the output is primary.
One throughput figure, no method, and a benchmarks folder nobody links
The introduction lists five things DXcam focuses on against common Python alternatives. Four of them are qualitative claims about throughput, stability on full-screen exclusive Direct3D applications, frame pacing and backend support. The fifth carries the only hard number in the document: 240+fps on 1080p. No processor, no graphics card, no resolution beyond the one, and no description of what was measured or how. The alternatives are never named. The root of the repository does contain a benchmarks directory, and it is not linked or mentioned anywhere in the visible text, so a reader who wants the evidence behind that figure has to find the folder and read it. The claim and the pacing note also pull in opposite directions, since a target above 120 is described as resource heavy. Two further signals sit outside the README. The packaging classifiers declare Development Status 4 - Beta, a status the document never mentions. And the release history is compressed: v0.1.0, v0.2.0 and v0.3.0 landed on three consecutive days in March 2026, after which the metadata still reads 0.3.0 while the last push is dated 2026-09-23.
Editorial conclusion
DXcam suits someone building a capture loop on Windows who needs a modern alternative to a screen-grab wrapper and who is willing to read the backend and processor notes before choosing options. It does not suit someone who wants RGB frames out of a two-dependency install, because the lean path is BGRA only and every other colour mode pulls in OpenCV or compiled kernels. Check three things before building on it. Check that you handle grab() returning None, since that default is kept deliberately for backward compatibility. Check whether you need the cursor, because it renders on the winrt backend and not on the default dxgi one. And check which clock your frame timestamps come from, because the two backends derive them from different Windows time sources.
Frequently asked questions
Why does DXcam's grab() sometimes return None?
grab() returns None when no new frame has been rendered since the last capture, and the README says that is kept for backward compatibility. Passing new_frame_only=False makes it always return the latest frame.
Which output colour modes does DXcam support without OpenCV?
Only BGRA. The supported modes are RGB, RGBA, BGR, BGRA and GRAY, and the notes say BGRA does not require OpenCV while the other four need conversion through cv2 or the compiled numpy backend.
How do I get the mouse cursor into DXcam frames?
Use the winrt backend. The guidance says that if cursor rendering is needed, winrt is the one to use, while dxgi is the default and is recommended for most workloads and especially one-shot grabs.
Which Python versions does DXcam support and what does the full install include?
Official Windows wheels are built for CPython 3.10 to 3.14. The full-feature command is pip install "dxcam[cv2,winrt]", which covers OpenCV colour conversion and the WinRT backend, while the cython extra that builds the compiled numpy kernels is separate.
Can a DXcam camera instance be reused after release()?
No. release() stops capture, frees buffers and releases capture resources, and the same instance cannot be reused, so calling start() afterwards raises RuntimeError. A context manager is offered so the release happens automatically.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/ra1nty-dxcam)Star history chart for your README
[](https://hysenlabs.com/projects/ra1nty-dxcam)Was this useful?