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 11 #ifndef MODULES_DESKTOP_CAPTURE_DESKTOP_CAPTURER_H_ 12 #define MODULES_DESKTOP_CAPTURE_DESKTOP_CAPTURER_H_ 13 14 #include <stddef.h> 15 #include <stdint.h> 16 17 #include <memory> 18 #include <string> 19 #include <type_traits> 20 #include <vector> 21 22 #include "modules/desktop_capture/desktop_capture_types.h" 23 #include "modules/desktop_capture/desktop_frame.h" 24 #include "modules/desktop_capture/shared_memory.h" 25 #include "rtc_base/system/rtc_export.h" 26 27 namespace webrtc { 28 29 class DesktopCaptureOptions; 30 class DesktopFrame; 31 32 // Abstract interface for screen and window capturers. 33 class RTC_EXPORT DesktopCapturer { 34 public: 35 enum class Result { 36 // The frame was captured successfully. 37 SUCCESS, 38 39 // There was a temporary error. The caller should continue calling 40 // CaptureFrame(), in the expectation that it will eventually recover. 41 ERROR_TEMPORARY, 42 43 // Capture has failed and will keep failing if the caller tries calling 44 // CaptureFrame() again. 45 ERROR_PERMANENT, 46 47 MAX_VALUE = ERROR_PERMANENT 48 }; 49 50 // Interface that must be implemented by the DesktopCapturer consumers. 51 class Callback { 52 public: 53 // Called after a frame has been captured. |frame| is not nullptr if and 54 // only if |result| is SUCCESS. 55 virtual void OnCaptureResult(Result result, 56 std::unique_ptr<DesktopFrame> frame) = 0; 57 58 protected: ~Callback()59 virtual ~Callback() {} 60 }; 61 62 typedef intptr_t SourceId; 63 64 static_assert(std::is_same<SourceId, ScreenId>::value, 65 "SourceId should be a same type as ScreenId."); 66 67 struct Source { 68 // The unique id to represent a Source of current DesktopCapturer. 69 SourceId id; 70 71 // Title of the window or screen in UTF-8 encoding, maybe empty. This field 72 // should not be used to identify a source. 73 std::string title; 74 }; 75 76 typedef std::vector<Source> SourceList; 77 78 virtual ~DesktopCapturer(); 79 80 // Called at the beginning of a capturing session. |callback| must remain 81 // valid until capturer is destroyed. 82 virtual void Start(Callback* callback) = 0; 83 84 // Sets SharedMemoryFactory that will be used to create buffers for the 85 // captured frames. The factory can be invoked on a thread other than the one 86 // where CaptureFrame() is called. It will be destroyed on the same thread. 87 // Shared memory is currently supported only by some DesktopCapturer 88 // implementations. 89 virtual void SetSharedMemoryFactory( 90 std::unique_ptr<SharedMemoryFactory> shared_memory_factory); 91 92 // Captures next frame, and involve callback provided by Start() function. 93 // Pending capture requests are canceled when DesktopCapturer is deleted. 94 virtual void CaptureFrame() = 0; 95 96 // Sets the window to be excluded from the captured image in the future 97 // Capture calls. Used to exclude the screenshare notification window for 98 // screen capturing. 99 virtual void SetExcludedWindow(WindowId window); 100 101 // TODO(zijiehe): Following functions should be pure virtual. The default 102 // implementations are for backward compatibility only. Remove default 103 // implementations once all DesktopCapturer implementations in Chromium have 104 // implemented these functions. 105 106 // Gets a list of sources current capturer supports. Returns false in case of 107 // a failure. 108 // For DesktopCapturer implementations to capture screens, this function 109 // should return monitors. 110 // For DesktopCapturer implementations to capture windows, this function 111 // should only return root windows owned by applications. 112 virtual bool GetSourceList(SourceList* sources); 113 114 // Selects a source to be captured. Returns false in case of a failure (e.g. 115 // if there is no source with the specified type and id.) 116 virtual bool SelectSource(SourceId id); 117 118 // Brings the selected source to the front and sets the input focus on it. 119 // Returns false in case of a failure or no source has been selected or the 120 // implementation does not support this functionality. 121 virtual bool FocusOnSelectedSource(); 122 123 // Returns true if the |pos| on the selected source is covered by other 124 // elements on the display, and is not visible to the users. 125 // |pos| is in full desktop coordinates, i.e. the top-left monitor always 126 // starts from (0, 0). 127 // The return value if |pos| is out of the scope of the source is undefined. 128 virtual bool IsOccluded(const DesktopVector& pos); 129 130 // Creates a DesktopCapturer instance which targets to capture windows. 131 static std::unique_ptr<DesktopCapturer> CreateWindowCapturer( 132 const DesktopCaptureOptions& options); 133 134 // Creates a DesktopCapturer instance which targets to capture screens. 135 static std::unique_ptr<DesktopCapturer> CreateScreenCapturer( 136 const DesktopCaptureOptions& options); 137 138 #if defined(WEBRTC_USE_PIPEWIRE) || defined(WEBRTC_USE_X11) 139 static bool IsRunningUnderWayland(); 140 #endif // defined(WEBRTC_USE_PIPEWIRE) || defined(WEBRTC_USE_X11) 141 142 protected: 143 // CroppingWindowCapturer needs to create raw capturers without wrappers, so 144 // the following two functions are protected. 145 146 // Creates a platform specific DesktopCapturer instance which targets to 147 // capture windows. 148 static std::unique_ptr<DesktopCapturer> CreateRawWindowCapturer( 149 const DesktopCaptureOptions& options); 150 151 // Creates a platform specific DesktopCapturer instance which targets to 152 // capture screens. 153 static std::unique_ptr<DesktopCapturer> CreateRawScreenCapturer( 154 const DesktopCaptureOptions& options); 155 }; 156 157 } // namespace webrtc 158 159 #endif // MODULES_DESKTOP_CAPTURE_DESKTOP_CAPTURER_H_ 160