DXcam - High-Performance Windows Screenshot Library

Common errors

• RuntimeError: DXcam only supports Windows.

  cause Attempting to run DXcam on a non-Windows operating system.
  fix DXcam is explicitly designed for Windows. Use a Windows environment or consider cross-platform alternatives for other operating systems.

• AttributeError: 'NoneType' object has no attribute 'grab'

  cause The `dxcam.create()` call returned `None`, indicating that a DXcam instance could not be initialized (e.g., no suitable display output found, or an underlying COM error).
  fix Check if `camera` is `None` after `dxcam.create()` and handle the case. Ensure DirectX drivers are up to date and that a display is connected and active. Restarting the application or the system might resolve transient issues.

• ImportError: DLL load failed while importing _dxcam_backend: The specified module could not be found.

  cause This usually indicates missing runtime dependencies (e.g., specific Visual C++ redistributables or DirectX components) or an issue with the Python environment.
  fix Ensure your Windows system is up to date and has the latest Visual C++ Redistributable. Reinstalling DXcam might also help: `pip uninstall dxcam && pip install dxcam`.

• cv2.error: OpenCV(4.x.x) error: ...

  cause If you are using a processor that relies on OpenCV (e.g., default or explicit `processor='cv2'`) and `opencv-python` is not installed or configured correctly.
  fix Install `opencv-python` alongside `dxcam`: `pip install dxcam opencv-python numpy`. Ensure the installed version is compatible with your Python environment.

Warnings

• gotcha DXcam is a Windows-only library. Attempting to import or use it on other operating systems will result in a RuntimeError.
  Fix: Ensure your development and deployment environment is Windows. Consider conditional imports or platform checks if your application needs to support multiple OS.
• breaking Version 0.1.0 introduced a 'Major overhaul', switching the default capture path to `IDXGIOutput5.DuplicateOutput1` and changing frame transfer from `CopyResource` to `CopySubresourceRegion`. This may alter performance characteristics or reveal new issues if upgrading from pre-0.1.0 versions, especially for applications sensitive to low-level capture behavior.
  Fix: Thoroughly test performance and stability when migrating from versions prior to 0.1.0. Monitor for `DXGI_ERROR_DEVICE_REMOVED` or unexpected frame drops.
• gotcha Version 0.2.0 introduced a WinRT backend and new processor splits (cv2 backend / numpy Cython-kernel backend). While this adds flexibility, users relying on specific performance profiles from earlier versions might need to re-evaluate their chosen backend/processor for optimal results.
  Fix: Consult the DXcam documentation to understand the different backends and processors. Experiment with `processor='numpy_kernels'` or `processor='cv2'` (if `opencv-python` is installed) and different `backend` options to find the best fit for your use case.
• gotcha DXcam relies on the Desktop Duplication API, which can encounter 'device lost' scenarios (e.g., monitor unplugged, GPU driver reset, display mode change). While DXcam attempts to recover, persistent issues can lead to `None` frames or crashes.
  Fix: Implement robust error handling for `None` frames returned by `grab()`. Consider re-initializing the DXcam instance if errors persist or if the display configuration changes significantly. Version 0.3.0 improved handling of DXGI mode switches, but device removal remains a challenge.

Install

• pip install dxcam Basic Install
• pip install dxcam opencv-python numpy Install with common dependencies for image processing

Imports

• create
  wrong:

  from dxcam import DXcam
  camera = DXcam()

  correct:

  import dxcam
  camera = dxcam.create()

  While DXcam class exists, dxcam.create() is the recommended factory function for convenience and proper initialization.

Quickstart

This quickstart initializes DXcam, starts capturing, grabs a single frame, and displays it using OpenCV (if installed). It includes error handling for non-Windows environments and initialization failures.

import dxcam
import cv2

# dxcam is Windows-only, so this example will only run there.
# On other OS, it will raise a RuntimeError.

try:
    # Create a DXcam instance, auto-detecting the primary display output.
    # Optionally specify output_idx, region, or device_idx.
    camera = dxcam.create()

    if camera is None:
        print("Failed to create DXcam instance. Ensure a display is connected and drivers are up to date.")
    else:
        # Start capturing frames. By default, it captures the full screen.
        camera.start(target_fps=30)

        # Grab a single frame
        frame = camera.grab()

        if frame is not None:
            print(f"Captured frame with shape: {frame.shape}, dtype: {frame.dtype}")
            # Example: Display the frame using OpenCV (requires opencv-python)
            cv2.imshow('DXcam Frame', frame)
            cv2.waitKey(1000) # Display for 1 second
            cv2.destroyAllWindows()
        else:
            print("Failed to grab a frame.")

        # Stop capturing frames when done
        camera.stop()

except RuntimeError as e:
    print(f"Error initializing DXcam: {e}. DXcam is a Windows-only library.")
except ImportError as e:
    print(f"Missing required dependency for quickstart: {e}. Try 'pip install dxcam opencv-python numpy'.")