Deprecated CGWindowListCreateImage causes warnings on macOS #1126
Description
When building on macOS, Sentry’s screenshot capturing functionality emits warnings due to the use of deprecated APIs:
MacSentrySubsystem.cpp(65,29): Warning : 'CGWindowListCreateImage' is deprecated: first deprecated in macOS 14.0 - Please use ScreenCaptureKit instead. [-Wdeprecated-declarations]
65 | CGImageRef ScreenshotRef = CGWindowListCreateImage(WindowRect, kCGWindowListOptionIncludingWindow, WindowID, kCGWindowImageDefault);
| ^
CGWindow.h(271,33): Reference : 'CGWindowListCreateImage' has been explicitly marked deprecated here
271 | CG_EXTERN CGImageRef __nullable CGWindowListCreateImage(CGRect screenBounds,
| ^
1 warning generated.So far, attempts to replace the deprecated CGWindowListCreateImage function with several alternative system APIs produced the following results:
1. ScreenCaptureKit
This is the recommended Apple's replacement for CGWindowListCreateImage in macOS 14.0 and later. However, it requires a more complex setup including user permissions for screen recording which may not be suitable for this particular use case.
Furthermore, even if the user manually grants the game app permission to capture the screen this functionality only works for ensures (non-fatal errors) but not for assertions or crashes, likely due to the asynchronous nature of the ScreenCaptureKit API.
Unreal Engine internally relies on ScreenCaptureKit to retrieve the selected pixel color in SEyeDropperButton during dropper mode which triggers a user permission prompt on first use. While this is expected behavior in the editor it’s less appropriate for a shipped game.
2. CGDisplayCreateImage
This function synchronously captures the entire screen and works for all error types similar to CGWindowListCreateImage. Redundant parts of the image can be manually cropped to keep only the game viewport. It doesn’t produce any warnings during the build, however Apple has also marked it as deprecated without specifying the macOS version in which this deprecation applies.
Although this doesn’t impact the screenshot capture results when using CGDisplayCreateImage, the API still triggers a system prompt requesting screen capture permission. Notably, even if the user denies permission the screenshot is still written to disk and uploaded to Sentry together with the event.
3. SentryScreenshotUtils::CaptureScreenshot
The replacement of CGWindowListCreateImage with the Sentry SDK’s custom screenshot capturing utility has already been implemented in:
While this approach removes all dependencies on system APIs it only works for ensures and does not capture screenshot for assertions and crashes (at least some of them) causing game/editor to hang.