1/*
2 *  Copyright (c) 2011 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// This sub-API supports the following functionalities:
12//
13//  - Allocating capture devices.
14//  - Connect a capture device with one or more channels.
15//  - Start and stop capture devices.
16//  - Getting capture device capabilities.
17
18#ifndef WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_CAPTURE_H_
19#define WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_CAPTURE_H_
20
21#include "webrtc/common_types.h"
22#include "webrtc/common_video/interface/i420_video_frame.h"
23
24namespace webrtc {
25
26class VideoEngine;
27class VideoCaptureModule;
28
29// This structure describes one set of the supported capabilities for a capture
30// device.
31struct CaptureCapability {
32  unsigned int width;
33  unsigned int height;
34  unsigned int maxFPS;
35  RawVideoType rawType;
36  VideoCodecType codecType;
37  unsigned int expectedCaptureDelay;
38  bool interlaced;
39  CaptureCapability() {
40    width = 0;
41    height = 0;
42    maxFPS = 0;
43    rawType = kVideoI420;
44    codecType = kVideoCodecUnknown;
45    expectedCaptureDelay = 0;
46    interlaced = false;
47  }
48};
49
50// This enumerator tells the current brightness alarm mode.
51enum Brightness {
52  Normal = 0,
53  Bright = 1,
54  Dark = 2
55};
56
57// This enumerator describes the capture alarm mode.
58enum CaptureAlarm {
59  AlarmRaised = 0,
60  AlarmCleared = 1
61};
62
63enum RotateCapturedFrame {
64  RotateCapturedFrame_0 = 0,
65  RotateCapturedFrame_90 = 90,
66  RotateCapturedFrame_180 = 180,
67  RotateCapturedFrame_270 = 270
68};
69
70struct ViEVideoFrameI420 {
71  ViEVideoFrameI420() {
72    y_plane = NULL;
73    u_plane = NULL;
74    v_plane = NULL;
75    y_pitch = 0;
76    u_pitch = 0;
77    v_pitch = 0;
78    width = 0;
79    height = 0;
80  }
81
82  unsigned char* y_plane;
83  unsigned char* u_plane;
84  unsigned char* v_plane;
85
86  int y_pitch;
87  int u_pitch;
88  int v_pitch;
89
90  unsigned short width;
91  unsigned short height;
92};
93
94// This class declares an abstract interface to be used when implementing
95// a user-defined capture device. This interface is not meant to be
96// implemented by the user. Instead, the user should call AllocateCaptureDevice
97// in the ViECapture interface, which will create a suitable implementation.
98// The user should then call IncomingFrame in this interface to deliver
99// captured frames to the system.
100class WEBRTC_DLLEXPORT ViEExternalCapture {
101 public:
102  ViEExternalCapture() {}
103  virtual ~ViEExternalCapture() {}
104
105  // This method is called by the user to deliver a new captured frame to
106  // VideoEngine.
107  // |capture_time| must be specified in the NTP time format in milliseconds.
108  virtual int IncomingFrame(unsigned char* video_frame,
109                            unsigned int video_frame_length,
110                            unsigned short width,
111                            unsigned short height,
112                            RawVideoType video_type,
113                            unsigned long long capture_time = 0) = 0;
114
115  // This method is specifically for delivering a new captured I420 frame to
116  // VideoEngine.
117  // |capture_time| must be specified in the NTP time format in milliseconds.
118  virtual int IncomingFrameI420(
119      const ViEVideoFrameI420& video_frame,
120      unsigned long long capture_time = 0) = 0;
121
122  virtual void SwapFrame(I420VideoFrame* frame) {}
123};
124
125// This class declares an abstract interface for a user defined observer. It is
126// up to the VideoEngine user to implement a derived class which implements the
127// observer class. The observer is registered using RegisterObserver() and
128// deregistered using DeregisterObserver().
129class WEBRTC_DLLEXPORT ViECaptureObserver {
130 public:
131  // This method is called if a bright or dark captured image is detected.
132  virtual void BrightnessAlarm(const int capture_id,
133                               const Brightness brightness) = 0;
134
135  // This method is called periodically telling the capture device frame rate.
136  virtual void CapturedFrameRate(const int capture_id,
137                                 const unsigned char frame_rate) = 0;
138
139  // This method is called if the capture device stops delivering images to
140  // VideoEngine.
141  virtual void NoPictureAlarm(const int capture_id,
142                              const CaptureAlarm alarm) = 0;
143
144 protected:
145  virtual ~ViECaptureObserver() {}
146};
147
148class WEBRTC_DLLEXPORT ViECapture {
149 public:
150  // Factory for the ViECapture sub‐API and increases an internal reference
151  // counter if successful. Returns NULL if the API is not supported or if
152  // construction fails.
153  static ViECapture* GetInterface(VideoEngine* video_engine);
154
155  // Releases the ViECapture sub-API and decreases an internal reference
156  // counter.
157  // Returns the new reference count. This value should be zero
158  // for all sub-API:s before the VideoEngine object can be safely deleted.
159  virtual int Release() = 0;
160
161  // Gets the number of available capture devices.
162  virtual int NumberOfCaptureDevices() = 0;
163
164  // Gets the name and unique id of a capture device.
165  virtual int GetCaptureDevice(unsigned int list_number,
166                               char* device_nameUTF8,
167                               const unsigned int device_nameUTF8Length,
168                               char* unique_idUTF8,
169                               const unsigned int unique_idUTF8Length) = 0;
170
171  // Allocates a capture device to be used in VideoEngine.
172  virtual int AllocateCaptureDevice(const char* unique_idUTF8,
173                                    const unsigned int unique_idUTF8Length,
174                                    int& capture_id) = 0;
175
176  // Registers an external capture device to be used in VideoEngine
177  virtual int AllocateExternalCaptureDevice(
178      int& capture_id,
179      ViEExternalCapture *&external_capture) = 0;
180
181  // Use capture device using external capture module.
182  virtual int AllocateCaptureDevice(VideoCaptureModule& capture_module,
183                                    int& capture_id) = 0;
184
185  // Releases a capture device and makes it available for other applications.
186  virtual int ReleaseCaptureDevice(const int capture_id) = 0;
187
188  // This function connects a capture device with a channel. Multiple channels
189  // can be connected to the same capture device.
190  virtual int ConnectCaptureDevice(const int capture_id,
191                                   const int video_channel) = 0;
192
193  // Disconnects a capture device as input for a specified channel.
194  virtual int DisconnectCaptureDevice(const int video_channel) = 0;
195
196  // Makes a capture device start capturing video frames.
197  virtual int StartCapture(
198      const int capture_id,
199      const CaptureCapability& capture_capability = CaptureCapability()) = 0;
200
201  // Stops a started capture device from capturing video frames.
202  virtual int StopCapture(const int capture_id) = 0;
203
204  // Rotates captured frames before encoding and sending.
205  // Used on mobile devices with rotates cameras.
206  virtual int SetRotateCapturedFrames(const int capture_id,
207                                      const RotateCapturedFrame rotation) = 0;
208
209  // This function sets the expected delay from when a video frame is captured
210  // to when that frame is delivered to VideoEngine.
211  virtual int SetCaptureDelay(const int capture_id,
212                              const unsigned int capture_delay_ms) = 0;
213
214  // Returns the number of sets of capture capabilities the capture device
215  // supports.
216  virtual int NumberOfCapabilities(
217      const char* unique_id_utf8,
218      const unsigned int unique_id_utf8_length) = 0;
219
220  // Gets a set of capture capabilities for a specified capture device.
221  virtual int GetCaptureCapability(const char* unique_id_utf8,
222                                   const unsigned int unique_id_utf8_length,
223                                   const unsigned int capability_number,
224                                   CaptureCapability& capability) = 0;
225
226  // Displays the capture device property dialog box for the specified capture
227  // device. Windows only.
228  virtual int ShowCaptureSettingsDialogBox(
229      const char* unique_idUTF8,
230      const unsigned int unique_id_utf8_length,
231      const char* dialog_title,
232      void* parent_window = NULL,
233      const unsigned int x = 200,
234      const unsigned int y = 200) = 0;
235
236  // Gets the clockwise angle the frames from the camera must be rotated in
237  // order to display the frames correctly if the display is rotated in its
238  // natural orientation.
239  virtual int GetOrientation(const char* unique_id_utf8,
240                             RotateCapturedFrame& orientation) = 0;
241
242  // Enables brightness alarm detection and the brightness alarm callback.
243  virtual int EnableBrightnessAlarm(const int capture_id,
244                                    const bool enable) = 0;
245
246  // Registers an instance of a user implementation of the ViECaptureObserver.
247  virtual int RegisterObserver(const int capture_id,
248                               ViECaptureObserver& observer) = 0;
249
250  // Removes an already registered instance of ViECaptureObserver.
251  virtual int DeregisterObserver(const int capture_id) = 0;
252
253 protected:
254  ViECapture() {}
255  virtual ~ViECapture() {}
256};
257
258}  // namespace webrtc
259
260#endif  // WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_CAPTURE_H_
261