Add a Windows Graphics Capture backend for content recognition

[cary-rowen]

Link to issue number:

Part of ADR #20480.

Summary of the issue:

NVDA did not have a native Windows Graphics Capture backend for the region capture path used by content recognition.

Description of user facing changes:

None yet. This PR adds backend support only.

Description of developer facing changes:

Added wgcCapture exports to nvdaHelperLocalWin10.dll and bound them from source/NVDAHelper/localWin10.py.

Description of development approach:

Implemented a native helper in nvdaHelper/localWin10/wgcCapture.cpp / .h that checks whether WGC monitor capture is available, captures the virtual-screen region by composing the intersecting monitors, copies the pixels into an NVDA-owned buffer, and scales the result to the requested destination size.

The helper stays isolated from the content recognition call sites so the next PR can switch behavior in one place without broad churn.

Testing strategy:

Built the source tree successfully and confirmed the new helper links into nvdaHelperLocalWin10.dll. No call site is wired up yet, so there is no user-facing workflow to exercise at this stage.

Known issues with pull request:

None.

Code Review Checklist:

• Documentation:
  • Change log entry
  • User Documentation
  • Developer / Technical Documentation
  • Context sensitive help for GUI changes
• Testing:
  • Unit tests
  • System (end to end) tests
  • Manual testing
• UX of all users considered:
  • Speech
  • Braille
  • Low Vision
  • Different web browsers
  • Localization in other languages / culture than English
• API is compatible with existing add-ons.
• Security precautions taken.

[Copilot]

Pull request overview

Adds a native Windows Graphics Capture (WGC) implementation to nvdaHelperLocalWin10.dll to enable a future switch of NVDA’s content-recognition region capture away from GDI when Screen Curtain is active (per ADR/issue #20480), while keeping call sites unchanged for now.

Changes:

• Added a new native helper (wgcCapture.cpp/.h) that can (1) detect WGC availability and (2) capture a virtual-screen region across monitors into a caller-owned BGRA buffer with scaling.
• Exported the new helper from nvdaHelperLocalWin10.dll and added Python ctypes bindings in source/NVDAHelper/localWin10.py.
• Updated the localWin10 SCons build to compile the new source and link required Windows libraries.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
source/NVDAHelper/localWin10.py	Adds ctypes bindings for wgcCapture_isSupported and wgcCapture_captureScreenRegion.
nvdaHelper/localWin10/wgcCapture.h	Declares the exported WGC support + capture APIs for the localWin10 helper DLL.
nvdaHelper/localWin10/wgcCapture.cpp	Implements WGC monitor capture, compositing across intersecting monitors, and scaling into a BGRA buffer.
nvdaHelper/localWin10/sconscript	Adds wgcCapture.cpp to the build and links against required libs (d3d11, runtimeobject, user32).

Suppressed comments (1)

nvdaHelper/localWin10/wgcCapture.cpp:472

• The requestPixels buffer is value-initialized to RGBQUAD{} (all zeros), which makes the “pixels outside all monitors are black” region transparent (alpha=0). If alpha is preserved for captured pixels, it’s better to make the background an opaque black (alpha=255) to avoid inconsistent alpha semantics in the returned BGRA8 buffer.

	std::vector<RGBQUAD> requestPixels(
		static_cast<std::size_t>(width) * height,
		RGBQUAD {}
	);

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[seanbudd]

Thanks @cary-rowen - just minor suggestions

[seanbudd]

Thanks @cary-rowen