Line data Source code
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 WEBRTC_MODULES_DESKTOP_CAPTURE_DESKTOP_CAPTURER_H_
12 : #define WEBRTC_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 "webrtc/modules/desktop_capture/desktop_frame.h"
23 : #include "webrtc/modules/desktop_capture/desktop_capture_types.h"
24 : #include "webrtc/modules/desktop_capture/shared_memory.h"
25 :
26 : namespace webrtc {
27 :
28 : class DesktopCaptureOptions;
29 : class DesktopFrame;
30 :
31 : // Abstract interface for screen and window capturers.
32 0 : class DesktopCapturer {
33 : public:
34 : enum class Result {
35 : // The frame was captured successfully.
36 : SUCCESS,
37 :
38 : // There was a temporary error. The caller should continue calling
39 : // CaptureFrame(), in the expectation that it will eventually recover.
40 : ERROR_TEMPORARY,
41 :
42 : // Capture has failed and will keep failing if the caller tries calling
43 : // CaptureFrame() again.
44 : ERROR_PERMANENT,
45 :
46 : MAX_VALUE = ERROR_PERMANENT
47 : };
48 :
49 : // Interface that must be implemented by the DesktopCapturer consumers.
50 0 : class Callback {
51 : public:
52 : // Called after a frame has been captured. |frame| is not nullptr if and
53 : // only if |result| is SUCCESS.
54 : virtual void OnCaptureResult(Result result,
55 : std::unique_ptr<DesktopFrame> frame) = 0;
56 :
57 : protected:
58 0 : virtual ~Callback() {}
59 : };
60 :
61 : typedef intptr_t SourceId;
62 :
63 : static_assert(std::is_same<SourceId, ScreenId>::value,
64 : "SourceId should be a same type as ScreenId.");
65 :
66 0 : struct Source {
67 : // The unique id to represent a Source of current DesktopCapturer.
68 : SourceId id;
69 : pid_t pid;
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 or until Stop() is called
82 : virtual void Start(Callback* callback) = 0;
83 : virtual void Stop() = 0;
84 :
85 : // Sets SharedMemoryFactory that will be used to create buffers for the
86 : // captured frames. The factory can be invoked on a thread other than the one
87 : // where CaptureFrame() is called. It will be destroyed on the same thread.
88 : // Shared memory is currently supported only by some DesktopCapturer
89 : // implementations.
90 : virtual void SetSharedMemoryFactory(
91 : std::unique_ptr<SharedMemoryFactory> shared_memory_factory);
92 :
93 : // Captures next frame, and involve callback provided by Start() function.
94 : // Pending capture requests are canceled when DesktopCapturer is deleted.
95 : virtual void CaptureFrame() = 0;
96 :
97 : // Sets the window to be excluded from the captured image in the future
98 : // Capture calls. Used to exclude the screenshare notification window for
99 : // screen capturing.
100 : virtual void SetExcludedWindow(WindowId window);
101 :
102 : // TODO(zijiehe): Following functions should be pure virtual. The default
103 : // implementations are for backward compatibility only. Remove default
104 : // implementations once all DesktopCapturer implementations in Chromium have
105 : // implemented these functions.
106 :
107 : // Gets a list of sources current capturer supports. Returns false in case of
108 : // a failure.
109 : virtual bool GetSourceList(SourceList* sources);
110 :
111 : // Selects a source to be captured. Returns false in case of a failure (e.g.
112 : // if there is no source with the specified type and id.)
113 : virtual bool SelectSource(SourceId id);
114 :
115 : // Brings the selected source to the front and sets the input focus on it.
116 : // Returns false in case of a failure or no source has been selected or the
117 : // implementation does not support this functionality.
118 : virtual bool FocusOnSelectedSource();
119 :
120 : // Creates a DesktopCapturer instance which targets to capture windows.
121 : static std::unique_ptr<DesktopCapturer> CreateWindowCapturer(
122 : const DesktopCaptureOptions& options);
123 :
124 : // Creates a DesktopCapturer instance which targets to capture screens.
125 : static std::unique_ptr<DesktopCapturer> CreateScreenCapturer(
126 : const DesktopCaptureOptions& options);
127 :
128 : // Creates a DesktopCapturer instance which targets to capture apps.
129 : static std::unique_ptr<DesktopCapturer> CreateAppCapturer(
130 : const DesktopCaptureOptions& options);
131 :
132 : protected:
133 : // CroppingWindowCapturer needs to create raw capturers without wrappers, so
134 : // the following two functions are protected.
135 :
136 : // Creates a platform specific DesktopCapturer instance which targets to
137 : // capture windows.
138 : static std::unique_ptr<DesktopCapturer> CreateRawWindowCapturer(
139 : const DesktopCaptureOptions& options);
140 :
141 : // Creates a platform specific DesktopCapturer instance which targets to
142 : // capture screens.
143 : static std::unique_ptr<DesktopCapturer> CreateRawScreenCapturer(
144 : const DesktopCaptureOptions& options);
145 :
146 : // Creates a platform specific DesktopCapturer instance which targets to
147 : // capture apps.
148 : static std::unique_ptr<DesktopCapturer> CreateRawAppCapturer(
149 : const DesktopCaptureOptions& options);
150 : };
151 :
152 : } // namespace webrtc
153 :
154 : #endif // WEBRTC_MODULES_DESKTOP_CAPTURE_DESKTOP_CAPTURER_H_
155 :
|