blob: 335427af23ac6a9349cf44fd6bc731be173249a0 [file] [log] [blame]
sergeyu@chromium.org15e32cc2013-04-29 20:10:57 +00001/*
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
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020011#ifndef MODULES_DESKTOP_CAPTURE_DESKTOP_CAPTURER_H_
12#define MODULES_DESKTOP_CAPTURE_DESKTOP_CAPTURER_H_
sergeyu@chromium.org15e32cc2013-04-29 20:10:57 +000013
sergeyu@chromium.org3d34f662013-06-04 18:51:23 +000014#include <stddef.h>
zijieheb68d6552016-10-28 17:35:11 -070015#include <stdint.h>
sergeyu@chromium.org3d34f662013-06-04 18:51:23 +000016
kwiberg84be5112016-04-27 01:19:58 -070017#include <memory>
zijieheb68d6552016-10-28 17:35:11 -070018#include <string>
zijiehefce49052016-11-07 15:25:18 -080019#include <type_traits>
zijieheb68d6552016-10-28 17:35:11 -070020#include <vector>
kwiberg84be5112016-04-27 01:19:58 -070021
Mirko Bonadei92ea95e2017-09-15 06:47:31 +020022#include "modules/desktop_capture/desktop_frame.h"
23#include "modules/desktop_capture/desktop_capture_types.h"
24#include "modules/desktop_capture/shared_memory.h"
jiayl@webrtc.org7ee0c162014-03-26 15:57:43 +000025
sergeyu@chromium.org15e32cc2013-04-29 20:10:57 +000026namespace webrtc {
27
zijieheb68d6552016-10-28 17:35:11 -070028class DesktopCaptureOptions;
sergeyu@chromium.org15e32cc2013-04-29 20:10:57 +000029class DesktopFrame;
sergeyu@chromium.org15e32cc2013-04-29 20:10:57 +000030
31// Abstract interface for screen and window capturers.
32class DesktopCapturer {
33 public:
sergeyu5d910282016-06-07 16:41:58 -070034 enum class Result {
35 // The frame was captured successfully.
36 SUCCESS,
37
38 // There was a temporary error. The caller should continue calling
zijiehe249beee2016-10-18 23:13:29 -070039 // CaptureFrame(), in the expectation that it will eventually recover.
sergeyu5d910282016-06-07 16:41:58 -070040 ERROR_TEMPORARY,
41
42 // Capture has failed and will keep failing if the caller tries calling
zijiehe249beee2016-10-18 23:13:29 -070043 // CaptureFrame() again.
sergeyu5d910282016-06-07 16:41:58 -070044 ERROR_PERMANENT,
Sergey Ulanov4c17abe2016-06-15 13:55:44 -070045
46 MAX_VALUE = ERROR_PERMANENT
sergeyu5d910282016-06-07 16:41:58 -070047 };
48
sergeyu@chromium.org15e32cc2013-04-29 20:10:57 +000049 // Interface that must be implemented by the DesktopCapturer consumers.
50 class Callback {
51 public:
sergeyu5d910282016-06-07 16:41:58 -070052 // 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,
sergeyu6ef36e72016-06-21 16:50:00 -070055 std::unique_ptr<DesktopFrame> frame) = 0;
sergeyu@chromium.org15e32cc2013-04-29 20:10:57 +000056
57 protected:
58 virtual ~Callback() {}
59 };
60
zijieheb68d6552016-10-28 17:35:11 -070061 typedef intptr_t SourceId;
62
zijiehefce49052016-11-07 15:25:18 -080063 static_assert(std::is_same<SourceId, ScreenId>::value,
64 "SourceId should be a same type as ScreenId.");
65
zijieheb68d6552016-10-28 17:35:11 -070066 struct Source {
67 // The unique id to represent a Source of current DesktopCapturer.
68 SourceId id;
69
70 // Title of the window or screen in UTF-8 encoding, maybe empty. This field
71 // should not be used to identify a source.
72 std::string title;
73 };
74
75 typedef std::vector<Source> SourceList;
76
77 virtual ~DesktopCapturer();
sergeyu@chromium.org15e32cc2013-04-29 20:10:57 +000078
79 // Called at the beginning of a capturing session. |callback| must remain
80 // valid until capturer is destroyed.
81 virtual void Start(Callback* callback) = 0;
82
sergeyucc9669c2016-02-09 15:13:26 -080083 // Sets SharedMemoryFactory that will be used to create buffers for the
84 // captured frames. The factory can be invoked on a thread other than the one
zijiehe249beee2016-10-18 23:13:29 -070085 // where CaptureFrame() is called. It will be destroyed on the same thread.
86 // Shared memory is currently supported only by some DesktopCapturer
87 // implementations.
sergeyucc9669c2016-02-09 15:13:26 -080088 virtual void SetSharedMemoryFactory(
zijieheb68d6552016-10-28 17:35:11 -070089 std::unique_ptr<SharedMemoryFactory> shared_memory_factory);
sergeyucc9669c2016-02-09 15:13:26 -080090
zijiehe91902cb2016-10-13 16:47:49 -070091 // Captures next frame, and involve callback provided by Start() function.
92 // Pending capture requests are canceled when DesktopCapturer is deleted.
zijiehe249beee2016-10-18 23:13:29 -070093 virtual void CaptureFrame() = 0;
jiayl@webrtc.org7ee0c162014-03-26 15:57:43 +000094
95 // Sets the window to be excluded from the captured image in the future
96 // Capture calls. Used to exclude the screenshare notification window for
97 // screen capturing.
zijieheb68d6552016-10-28 17:35:11 -070098 virtual void SetExcludedWindow(WindowId window);
99
100 // TODO(zijiehe): Following functions should be pure virtual. The default
101 // implementations are for backward compatibility only. Remove default
102 // implementations once all DesktopCapturer implementations in Chromium have
103 // implemented these functions.
104
105 // Gets a list of sources current capturer supports. Returns false in case of
106 // a failure.
Zijie Heb010a322017-08-07 15:25:01 -0700107 // For DesktopCapturer implementations to capture screens, this function
108 // should return monitors.
109 // For DesktopCapturer implementations to capture windows, this function
110 // should only return root windows owned by applications.
zijieheb68d6552016-10-28 17:35:11 -0700111 virtual bool GetSourceList(SourceList* sources);
112
113 // Selects a source to be captured. Returns false in case of a failure (e.g.
114 // if there is no source with the specified type and id.)
115 virtual bool SelectSource(SourceId id);
116
117 // Brings the selected source to the front and sets the input focus on it.
118 // Returns false in case of a failure or no source has been selected or the
119 // implementation does not support this functionality.
120 virtual bool FocusOnSelectedSource();
zijiehe54fd5792016-11-02 14:49:35 -0700121
Zijie He12827112017-08-29 11:19:13 -0700122 // Returns true if the |pos| on the selected source is covered by other
123 // elements on the display, and is not visible to the users.
124 // |pos| is in full desktop coordinates, i.e. the top-left monitor always
125 // starts from (0, 0).
126 // The return value if |pos| is out of the scope of the source is undefined.
127 virtual bool IsOccluded(const DesktopVector& pos);
128
zijiehe54fd5792016-11-02 14:49:35 -0700129 // Creates a DesktopCapturer instance which targets to capture windows.
130 static std::unique_ptr<DesktopCapturer> CreateWindowCapturer(
131 const DesktopCaptureOptions& options);
132
133 // Creates a DesktopCapturer instance which targets to capture screens.
134 static std::unique_ptr<DesktopCapturer> CreateScreenCapturer(
135 const DesktopCaptureOptions& options);
136
137 protected:
138 // CroppingWindowCapturer needs to create raw capturers without wrappers, so
139 // the following two functions are protected.
140
141 // Creates a platform specific DesktopCapturer instance which targets to
142 // capture windows.
143 static std::unique_ptr<DesktopCapturer> CreateRawWindowCapturer(
144 const DesktopCaptureOptions& options);
145
146 // Creates a platform specific DesktopCapturer instance which targets to
147 // capture screens.
148 static std::unique_ptr<DesktopCapturer> CreateRawScreenCapturer(
149 const DesktopCaptureOptions& options);
sergeyu@chromium.org15e32cc2013-04-29 20:10:57 +0000150};
151
152} // namespace webrtc
153
Mirko Bonadei92ea95e2017-09-15 06:47:31 +0200154#endif // MODULES_DESKTOP_CAPTURE_DESKTOP_CAPTURER_H_
sergeyu@chromium.org15e32cc2013-04-29 20:10:57 +0000155