desktop_capture_options.h (12824B)
1 /* 2 * Copyright (c) 2013 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 #ifndef MODULES_DESKTOP_CAPTURE_DESKTOP_CAPTURE_OPTIONS_H_ 11 #define MODULES_DESKTOP_CAPTURE_DESKTOP_CAPTURE_OPTIONS_H_ 12 13 #include <cstdint> 14 15 #include "api/scoped_refptr.h" 16 #include "rtc_base/system/rtc_export.h" 17 18 #if defined(WEBRTC_USE_X11) 19 #include "modules/desktop_capture/linux/x11/shared_x_display.h" 20 #endif 21 22 #if defined(WEBRTC_USE_PIPEWIRE) 23 #include "modules/desktop_capture/linux/wayland/shared_screencast_stream.h" 24 #endif 25 26 #if defined(WEBRTC_MAC) && !defined(WEBRTC_IOS) 27 #include "modules/desktop_capture/mac/desktop_configuration_monitor.h" 28 #endif 29 30 #include "modules/desktop_capture/full_screen_window_detector.h" 31 32 namespace webrtc { 33 34 // An object that stores initialization parameters for screen and window 35 // capturers. 36 class RTC_EXPORT DesktopCaptureOptions { 37 public: 38 // Returns instance of DesktopCaptureOptions with default parameters. On Linux 39 // also initializes X window connection. x_display() will be set to null if 40 // X11 connection failed (e.g. DISPLAY isn't set). 41 static DesktopCaptureOptions CreateDefault(); 42 43 DesktopCaptureOptions(); 44 DesktopCaptureOptions(const DesktopCaptureOptions& options); 45 DesktopCaptureOptions(DesktopCaptureOptions&& options); 46 ~DesktopCaptureOptions(); 47 48 DesktopCaptureOptions& operator=(const DesktopCaptureOptions& options); 49 DesktopCaptureOptions& operator=(DesktopCaptureOptions&& options); 50 51 #if defined(WEBRTC_USE_X11) 52 const scoped_refptr<SharedXDisplay>& x_display() const { return x_display_; } 53 void set_x_display(scoped_refptr<SharedXDisplay> x_display) { 54 x_display_ = x_display; 55 } 56 #endif 57 58 #if defined(WEBRTC_MAC) && !defined(WEBRTC_IOS) 59 // TODO(zijiehe): Remove both DesktopConfigurationMonitor and 60 // FullScreenChromeWindowDetector out of DesktopCaptureOptions. It's not 61 // reasonable for external consumers to set these two parameters. 62 const scoped_refptr<DesktopConfigurationMonitor>& configuration_monitor() 63 const { 64 return configuration_monitor_; 65 } 66 // If nullptr is set, ScreenCapturer won't work and WindowCapturer may return 67 // inaccurate result from IsOccluded() function. 68 void set_configuration_monitor(scoped_refptr<DesktopConfigurationMonitor> m) { 69 configuration_monitor_ = m; 70 } 71 72 bool allow_iosurface() const { return allow_iosurface_; } 73 void set_allow_iosurface(bool allow) { allow_iosurface_ = allow; } 74 75 // If this flag is set, and the system supports it, ScreenCaptureKit will be 76 // used for desktop capture. 77 // TODO: crbug.com/327458809 - Force the use of SCK and ignore this flag in 78 // new versions of macOS that remove support for the CGDisplay-based APIs. 79 bool allow_sck_capturer() const { return allow_sck_capturer_; } 80 void set_allow_sck_capturer(bool allow) { allow_sck_capturer_ = allow; } 81 82 // If ScreenCaptureKit is used for desktop capture and this flag is 83 // set, the ScreenCaptureKit backend will use SCContentSharingPicker for 84 // picking source. 85 bool allow_sck_system_picker() const { return allow_sck_system_picker_; } 86 void set_allow_sck_system_picker(bool allow) { 87 allow_sck_system_picker_ = allow; 88 } 89 #endif 90 91 const scoped_refptr<FullScreenWindowDetector>& full_screen_window_detector() 92 const { 93 return full_screen_window_detector_; 94 } 95 void set_full_screen_window_detector( 96 scoped_refptr<FullScreenWindowDetector> detector) { 97 full_screen_window_detector_ = detector; 98 } 99 100 // Flag indicating that the capturer should use screen change notifications. 101 // Enables/disables use of XDAMAGE in the X11 capturer. 102 bool use_update_notifications() const { return use_update_notifications_; } 103 void set_use_update_notifications(bool use_update_notifications) { 104 use_update_notifications_ = use_update_notifications; 105 } 106 107 // Flag indicating if desktop effects (e.g. Aero) should be disabled when the 108 // capturer is active. Currently used only on Windows. 109 bool disable_effects() const { return disable_effects_; } 110 void set_disable_effects(bool disable_effects) { 111 disable_effects_ = disable_effects; 112 } 113 114 // Flag that should be set if the consumer uses updated_region() and the 115 // capturer should try to provide correct updated_region() for the frames it 116 // generates (e.g. by comparing each frame with the previous one). 117 bool detect_updated_region() const { return detect_updated_region_; } 118 void set_detect_updated_region(bool detect_updated_region) { 119 detect_updated_region_ = detect_updated_region; 120 } 121 122 // Indicates that the capturer should try to include the cursor in the frame. 123 // If it is able to do so it will set `DesktopFrame::may_contain_cursor()`. 124 // Not all capturers will support including the cursor. If this value is false 125 // or the cursor otherwise cannot be included in the frame, then cursor 126 // metadata will be sent, though the capturer may choose to always send cursor 127 // metadata. 128 bool prefer_cursor_embedded() const { return prefer_cursor_embedded_; } 129 void set_prefer_cursor_embedded(bool prefer_cursor_embedded) { 130 prefer_cursor_embedded_ = prefer_cursor_embedded; 131 } 132 133 #if defined(WEBRTC_WIN) 134 // Enumerating windows owned by the current process on Windows has some 135 // complications due to |GetWindowText*()| APIs potentially causing a 136 // deadlock (see the comments in the `GetWindowListHandler()` function in 137 // window_capture_utils.cc for more details on the deadlock). 138 // To avoid this issue, consumers can either ensure that the thread that runs 139 // their message loop never waits on `GetSourceList()`, or they can set this 140 // flag to false which will prevent windows running in the current process 141 // from being enumerated and included in the results. Consumers can still 142 // provide the WindowId for their own windows to `SelectSource()` and capture 143 // them. 144 bool enumerate_current_process_windows() const { 145 return enumerate_current_process_windows_; 146 } 147 void set_enumerate_current_process_windows( 148 bool enumerate_current_process_windows) { 149 enumerate_current_process_windows_ = enumerate_current_process_windows; 150 } 151 152 // Allowing directx based capturer or not, this capturer works on windows 7 153 // with platform update / windows 8 or upper. 154 bool allow_directx_capturer() const { return allow_directx_capturer_; } 155 void set_allow_directx_capturer(bool enabled) { 156 allow_directx_capturer_ = enabled; 157 } 158 159 // Flag that may be set to allow use of the cropping window capturer (which 160 // captures the screen & crops that to the window region in some cases). An 161 // advantage of using this is significantly higher capture frame rates than 162 // capturing the window directly. A disadvantage of using this is the 163 // possibility of capturing unrelated content (e.g. overlapping windows that 164 // aren't detected properly, or neighboring regions when moving/resizing the 165 // captured window). Note: this flag influences the behavior of calls to 166 // DesktopCapturer::CreateWindowCapturer; calls to 167 // CroppingWindowCapturer::CreateCapturer ignore the flag (treat it as true). 168 bool allow_cropping_window_capturer() const { 169 return allow_cropping_window_capturer_; 170 } 171 void set_allow_cropping_window_capturer(bool allow) { 172 allow_cropping_window_capturer_ = allow; 173 } 174 175 #if defined(RTC_ENABLE_WIN_WGC) 176 // This flag enables the WGC capturer for capturing the screen. 177 // This capturer should offer similar or better performance than the cropping 178 // capturer without the disadvantages listed above. However, the WGC capturer 179 // is only available on Windows 10 version 1809 (Redstone 5) and up. This flag 180 // will have no affect on older versions. 181 // If set, and running a supported version of Win10, this flag will take 182 // precedence over the cropping, directx, and magnification flags. 183 bool allow_wgc_screen_capturer() const { return allow_wgc_screen_capturer_; } 184 void set_allow_wgc_screen_capturer(bool allow) { 185 allow_wgc_screen_capturer_ = allow; 186 } 187 188 // This flag has the same effect as allow_wgc_screen_capturer but it only 189 // enables or disables WGC for window capturing (not screen). 190 bool allow_wgc_window_capturer() const { return allow_wgc_window_capturer_; } 191 void set_allow_wgc_window_capturer(bool allow) { 192 allow_wgc_window_capturer_ = allow; 193 } 194 195 // This flag enables the WGC capturer for fallback capturer. 196 // The flag is useful when the first capturer (eg. WindowCapturerWinGdi) is 197 // unreliable in certain devices where WGC is supported, but not used by 198 // default. 199 bool allow_wgc_capturer_fallback() const { 200 return allow_wgc_capturer_fallback_; 201 } 202 void set_allow_wgc_capturer_fallback(bool allow) { 203 allow_wgc_capturer_fallback_ = allow; 204 } 205 206 // This flag enables 0Hz mode in combination with the WGC capturer. 207 // The flag has no effect if the allow_wgc_capturer flag is false. 208 bool allow_wgc_zero_hertz() const { return allow_wgc_zero_hertz_; } 209 void set_allow_wgc_zero_hertz(bool allow) { allow_wgc_zero_hertz_ = allow; } 210 211 // This flag controls whether the WGC capturer is required to draw a border 212 // around the captured window/screen. 213 // The flag has no effect if the allow_wgc_capturer flag is false. 214 bool wgc_require_border() const { return wgc_require_border_; } 215 void set_wgc_require_border(bool require) { wgc_require_border_ = require; } 216 217 // For window capture, set to true to include more application content like 218 // tool tips and drop downs. From the Microsoft developer docs: 219 // 220 // "Secondary Windows are considered to be windows that have either the 221 // WS_POPUP or WS_EX_TOOLWINDOW styles that intersect the main window. The 222 // windows are drawn into the texture the app receives and are clipped if they 223 // go outside the bounds of the main top level window." 224 bool wgc_include_secondary_windows() const { 225 return wgc_include_secondary_windows_; 226 } 227 void set_wgc_include_secondary_windows(bool include) { 228 wgc_include_secondary_windows_ = include; 229 } 230 #endif // defined(RTC_ENABLE_WIN_WGC) 231 #endif // defined(WEBRTC_WIN) 232 233 #if defined(WEBRTC_USE_PIPEWIRE) 234 bool allow_pipewire() const { return allow_pipewire_; } 235 void set_allow_pipewire(bool allow) { allow_pipewire_ = allow; } 236 237 const scoped_refptr<SharedScreenCastStream>& screencast_stream() const { 238 return screencast_stream_; 239 } 240 void set_screencast_stream(scoped_refptr<SharedScreenCastStream> stream) { 241 screencast_stream_ = stream; 242 } 243 244 void set_width(uint32_t width) { width_ = width; } 245 uint32_t get_width() const { return width_; } 246 247 void set_height(uint32_t height) { height_ = height; } 248 uint32_t get_height() const { return height_; } 249 250 void set_pipewire_use_damage_region(bool use_damage_regions) { 251 pipewire_use_damage_region_ = use_damage_regions; 252 } 253 bool pipewire_use_damage_region() const { 254 return pipewire_use_damage_region_; 255 } 256 #endif 257 258 private: 259 #if defined(WEBRTC_USE_X11) 260 scoped_refptr<SharedXDisplay> x_display_; 261 #endif 262 #if defined(WEBRTC_USE_PIPEWIRE) 263 // An instance of shared PipeWire ScreenCast stream we share between 264 // BaseCapturerPipeWire and MouseCursorMonitorPipeWire as cursor information 265 // is sent together with screen content. 266 scoped_refptr<SharedScreenCastStream> screencast_stream_; 267 #endif 268 #if defined(WEBRTC_MAC) && !defined(WEBRTC_IOS) 269 scoped_refptr<DesktopConfigurationMonitor> configuration_monitor_; 270 bool allow_iosurface_ = false; 271 bool allow_sck_capturer_ = false; 272 bool allow_sck_system_picker_ = false; 273 #endif 274 275 scoped_refptr<FullScreenWindowDetector> full_screen_window_detector_; 276 277 #if defined(WEBRTC_WIN) 278 bool enumerate_current_process_windows_ = true; 279 bool allow_directx_capturer_ = false; 280 bool allow_cropping_window_capturer_ = false; 281 #if defined(RTC_ENABLE_WIN_WGC) 282 bool allow_wgc_screen_capturer_ = false; 283 bool allow_wgc_window_capturer_ = false; 284 bool allow_wgc_capturer_fallback_ = false; 285 bool allow_wgc_zero_hertz_ = false; 286 bool wgc_require_border_ = false; 287 bool wgc_include_secondary_windows_ = false; 288 #endif 289 #endif 290 #if defined(WEBRTC_USE_X11) 291 bool use_update_notifications_ = false; 292 #else 293 bool use_update_notifications_ = true; 294 #endif 295 bool disable_effects_ = true; 296 bool detect_updated_region_ = false; 297 bool prefer_cursor_embedded_ = false; 298 #if defined(WEBRTC_USE_PIPEWIRE) 299 bool allow_pipewire_ = false; 300 bool pipewire_use_damage_region_ = true; 301 uint32_t width_ = 0; 302 uint32_t height_ = 0; 303 #endif 304 }; 305 306 } // namespace webrtc 307 308 #endif // MODULES_DESKTOP_CAPTURE_DESKTOP_CAPTURE_OPTIONS_H_