wgc_python

English | 简体中文

🚀 Window Capture Library Built for Python Automation
180+ FPS Performance · Zero-Resource Standby · Capture Behind Windows · Minimalist API

Why wgc_python?

🎯 Designed for Automation Scenarios

Are you struggling with these problems?

mss/BitBlt: Cannot capture occluded or background windows
PrintWindow: Performance bottleneck, fixed 26ms+ latency
Other WGC wrappers: Continuous resource consumption, huge overhead for frequent start/stop (50ms+)

wgc_python solves this dilemma with its innovative Pause/Resume mechanism:

# Traditional approach: Either waste resources or suffer latency
start_capture()  # 50ms overhead
get_frame()      # Get screenshot
stop_capture()   # Destroy session (50ms)

# wgc_python approach: One-time init, on-demand capture, zero-overhead standby
with WindowCapture("Window", "Class") as cap:
    while running:
        frame = cap.capture_one()  # auto Resume → wait → copy → Pause
        # Process image...

📊 Performance Comparison

Solution	FPS	Background Capture	CPU Usage	Toggle Overhead	GPU When Paused
python-mss / BitBlt	~60	❌	High	Low	N/A (no pause)
PrintWindow	~38	✅	Medium	Low	N/A (per-call)
Other WGC wrappers	180+	✅	High (continuous)	Very High (50ms+)	High (can't truly pause)
wgc_python	180+	✅	Near Zero (when paused)	<1μs (atomic flag)	Zero (no D3D ops)

✨ Core Advantages

1. Extreme Performance

180+ FPS high frame rate capture, 5x faster than PrintWindow
Double-buffered Staging Texture: GPU async copy, read/write non-blocking
Zero-copy path: np.ndarray(strides=...) directly from GPU-mapped memory

2. Smart Resource Management

Pause/Resume <1μs soft-pause: Atomic flag only, no WGC session teardown
capture_one() auto management: Resume → wait → copy → Pause, zero GPU driver overhead between captures
Session Reuse: No frequent D3D device creation/destruction

3. Minimalist API

capture_one(): One-line on-demand capture, returns numpy array
get_frame(): Zero-copy raw pointer path (advanced)
Thread safe: C++ handles all multi-threading complexity

4. Multi-Instance Capture

Create multiple capture sessions simultaneously within one process
Each session has its own D3D11 device, staging textures, and WinRT session — fully isolated
Supports concurrent capture of the same window

5. Client Area Precision (No Title Bar by Default)

Default client_area_only=True: captures only window client area, automatically crops title bar and borders
Set client_area_only=False: captures entire window including title bar and borders, for UI recording
DPI-aware: automatic high-DPI scaling correction for pixel-perfect cropping
GPU-level cropping via CopySubresourceRegion, no wasted bandwidth or CPU

6. Capture Behind Windows

Supports capturing occluded, minimized, and background windows
Perfect for games, desktop apps, and various scenarios

Quick Start

Installation

pip install wgc-python

Basic Usage

from wgc_python import WindowCapture, enumerate_windows

# Enumerate all windows
for title, class_name in enumerate_windows():
    print(f"{title} ({class_name})")

# On-demand capture (recommended — zero-resource standby)
with WindowCapture("Window Title", "WindowClass") as cap:
    frame = cap.capture_one()     # BGRA numpy array, shape (h, w, 4)
    if frame is not None:
        print(f"Captured: {frame.shape}")

# Client area demo
# Default client_area_only=True: content only, no title bar/borders
cap_client = WindowCapture("Notepad", "Notepad")                       # content only
cap_full  = WindowCapture("Notepad", "Notepad", client_area_only=False) # with title bar
frame_client = cap_client.capture_one()  # edit area only
frame_full  = cap_full.capture_one()    # title bar + menu + edit area
cap_client.close()
cap_full.close()

Best Practice for Automation

from wgc_python import WindowCapture

cap = WindowCapture("Game Window", "UnityWndClass")

while True:
    frame = cap.capture_one(timeout=1.0)
    if frame is not None:
        # frame is BGRA numpy array, ready for OpenCV/template matching
        pass
    time.sleep(1)

cap.close()

Zero-Copy Advanced Usage

from wgc_python import WindowCapture
import numpy as np
import ctypes

with WindowCapture("Window", "Class") as cap:
    cap.resume()
    r = cap.get_frame()  # (ptr, w, h, row_pitch) — GPU mapped pointer
    if r:
        ptr, w, h, rp = r
        arr = np.ndarray((h, w, 4), dtype=np.uint8,
                         buffer=(ctypes.c_ubyte * (h * rp)).from_address(ptr),
                         strides=(rp, 4, 1))
        # arr is a zero-copy view into GPU-mapped memory
        cap.release_frame()
    cap.pause()

Real-time Display

from wgc_python import WindowCapture
import cv2

with WindowCapture("Window Title", "WindowClass") as cap:
    while True:
        frame = cap.capture_one()
        if frame is not None:
            cv2.imshow("Capture", cv2.cvtColor(frame, cv2.COLOR_BGRA2BGR))
        if cv2.waitKey(1) & 0xFF == ord('q'):
            break
    cv2.destroyAllWindows()

API Reference

from wgc_python import (
    WindowCapture,             # Window capture class (context manager support)
    enumerate_windows,         # Enumerate all visible windows
    get_last_error,            # Get last error message (thread-safe)
    get_active_capture_count,  # Get active capture count
)

# WindowCapture methods:
#   cap = WindowCapture(title, class_name, client_area_only=True)
#
#   cap.capture_one(timeout=0.5)  -> np.ndarray | None  ★ recommended
#      Auto Resume → wait for frame → copy to numpy → Pause
#      WGC fully dormant between captures, zero GPU driver overhead
#
#   cap.get_frame()              -> (ptr, w, h, row_pitch) | None
#   cap.release_frame()           # Release GPU mapping
#   cap.pause()                   # Pause capture (zero-resource standby)
#   cap.resume()                  # Resume capture
#   cap.stop()                    # Stop frame arrival
#   cap.close()                   # Destroy session
#   cap.is_capturing()  -> bool
#   cap.is_paused()     -> bool
#   cap.get_frame_count()  -> int
#   cap.handle             -> int (DLL handle)

Technical Architecture

WGC Capture → GPU Surface Texture
                   │
         ┌─────────▼──────────┐
         │   FrameArrived     │
         │  if pausing → ↑   │  ← Paused: return directly, zero D3D ops
         └─────────┬──────────┘
                   │
              CopyResource (GPU async copy)
                   │
     ┌─────────────────────────────┐
     │  Double-buffered Staging    │
     │  [0] Write ←→ [1] Read      │
     │  m_textureInUse anti-collide │
     └─────────────────────────────┘
                   │
              Map (permanently mapped GPU memory)
                   │
     ┌────── Zero-Copy Output ────┐
     │ get_frame()                 │
     │ raw ptr → numpy zero-copy   │
     │ requires release_frame()    │
     └─────────────────────────────┘

     ┌────── One-Click Capture ───┐
     │ capture_one()               │
     │ auto Pause/Resume           │
     │ returns numpy array         │
     │ zero GPU overhead when idle │
     └─────────────────────────────┘

How Pause/Resume Works

  User calls cap.pause()
         │
    m_isPaused = true   ◄──── atomic flag, <1μs
    m_readableStagingIndex = -1
         │
    ┌────▼────────────────────────────────────────────┐
    │           FrameArrived Callback (WGC still fires)│
    │                                                  │
    │  lock(mutex);                                    │
    │  if (m_isPaused) return;     // ← pure CPU, skip│
    │  // ↓ below runs only after resume ↓             │
    │  CopyResource(staging, frame);                   │
    │  m_readableStagingIndex = idx;                   │
    │  unlock(mutex);                                  │
    └────▲────────────────┬───────────────────────────┘
         │                │
  User calls cap.resume()  MapFrame checks readableStagingIndex
  m_isPaused = false       <0 → no frame ready → returns false

  No WGC session destroy / no D3D device recreate / no callback re-register
  → zero-latency resume, no spikes

File Structure

wgc_python/
├── wgc_python/                   # Python package
│   ├── __init__.py               # Python API (ctypes FFI)
│   └── wgc_python.dll            # Compiled DLL
├── wgc_python_dll/               # C++ DLL Project
│   ├── WGCWindowCapture.h/cpp    # Capture core (double-buffered + zero-copy)
│   ├── WGCExport.h/cpp           # DLL exports (thread-safe error handling)
│   ├── D3DInterop.cpp            # D3D11 device interop
│   ├── WindowEnumerator.h/cpp    # Window enumeration
│   ├── pch.h                     # Precompiled header
│   └── packages/                 # NuGet packages
├── test.py                       # Functional tests
├── test_mt.py                    # Multi-threaded on-demand capture example
├── pyproject.toml                # pip build config
├── BUILD.md / BUILD_EN.md        # Build instructions (CN/EN)
├── README.md / README_EN.md      # Usage docs (CN/EN)
├── CONTRIBUTING.md               # Contributing guide
├── CODE_OF_CONDUCT.md            # Code of conduct
├── LICENSE                       # MIT License
└── requirements.txt              # Python dependencies

Build DLL

See BUILD.md

Troubleshooting

Issue	Solution
DLL not found	Ensure `wgc_python.dll` is in the correct location
Capture failed	Check if window is visible, Windows version >= 1903
Non-ASCII path save failed	Use `cv2.imencode` + `open().write()` instead of `cv2.imwrite`
Missing dependencies	`pip install numpy opencv-python`

Use Cases

✅ Game AI / Automation Scripts
✅ RPA Process Automation
✅ Screen Recording / Streaming
✅ UI Automation Testing
✅ Computer Vision Applications

Acknowledgments

This project is based on robmikh/Win32CaptureSample.

License

MIT License

FilesExpand file tree

README_EN.md

Latest commit

History

README_EN.md

File metadata and controls

wgc_python

Why wgc_python?

🎯 Designed for Automation Scenarios

📊 Performance Comparison

✨ Core Advantages

1. Extreme Performance

2. Smart Resource Management

3. Minimalist API

4. Multi-Instance Capture

5. Client Area Precision (No Title Bar by Default)

6. Capture Behind Windows

Quick Start

Installation

Basic Usage

Best Practice for Automation

Zero-Copy Advanced Usage

Real-time Display

API Reference

Technical Architecture

How Pause/Resume Works

File Structure

Build DLL

Troubleshooting

Use Cases

Acknowledgments

License