Use Windows Graphics Capture for content recognition with Screen Curtain and Magnifier

[cary-rowen]

Link to issue number:

Follow up #20630
Part of #20480.
Fixes #19164

Summary of the issue:

Content recognition currently uses GDI to capture screen pixels. Screen Curtain causes this capture to return black pixels, while NVDA's built-in Magnifier can cause recognition to receive magnified, cropped or color-transformed pixels instead of the original screen content.

Description of user facing changes:

On supported systems, Windows OCR can now be used while Screen Curtain or NVDA's built-in Magnifier is active. Existing GDI capture behavior is preserved when neither feature is active and when WGC is unavailable for Magnifier.

Description of developer facing changes:

Added a private Python wrapper for the Windows Graphics Capture backend introduced in #20630 and centralized capture selection in contentRecog.recogUi. Content recognizers using the shared recognition framework receive the same capture behavior. Negative virtual-screen origins are now accepted for monitors positioned left of or above the primary display. No public API changes are introduced.

Description of development approach:

GDI remains the default capture path. WGC is used when Screen Curtain is active, or when NVDA's built-in Magnifier is active and WGC is supported. A WGC failure while Magnifier is active falls back to GDI, preserving the previous usable behavior. No GDI fallback is allowed while Screen Curtain is active because it would return pixels from the obscured display. Capture failures and watchdog cancellation are passed through the existing recognition result lifecycle. Enabling Screen Curtain during automatically refreshed recognition is blocked only when WGC is unavailable.

Testing strategy:

Unit tests cover default GDI selection, Screen Curtain and Magnifier failure behavior, watchdog cancellation, Screen Curtain state transitions, negative virtual-screen coordinates and invalid capture dimensions. The focused content recognition test suite and Python lint and formatting checks pass. Windows OCR with Screen Curtain has also been tested manually.

Known issues with pull request:

Further manual testing is pending.

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.

[LeonarddeR]

This is lovely @cary-rowen .
Note that when testing manually, extra attention should probably go to differences in scaling. This probably depends won whether Graphics Capture hooks into the system before or after scaling takes place.

[hwf1324]

Manual testing when running from source code:

• Perform recognition while Screen Curtain/Magnifier is enabled.
• Perform recognition on single/multiple monitors.
• Magnifier's various color filters can also be used to retrieve the original image.

No issues.

As for DPI, it can be recognized normally after I switch monitors or adjust the scaling settings.

[cary-rowen]

Thanks @hwf1324

[Qchristensen]

User guide reads well

[seanbudd]

Thanks @cary-rowen