Home | History | Annotate | Download | only in include 
      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 
     24 namespace webrtc {
     25 
     26 class VideoEngine;
     27 class VideoCaptureModule;
     28 
     29 // This structure describes one set of the supported capabilities for a capture
     30 // device.
     31 struct 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.
     51 enum Brightness {
     52   Normal = 0,
     53   Bright = 1,
     54   Dark = 2
     55 };
     56 
     57 // This enumerator describes the capture alarm mode.
     58 enum CaptureAlarm {
     59   AlarmRaised = 0,
     60   AlarmCleared = 1
     61 };
     62 
     63 enum RotateCapturedFrame {
     64   RotateCapturedFrame_0 = 0,
     65   RotateCapturedFrame_90 = 90,
     66   RotateCapturedFrame_180 = 180,
     67   RotateCapturedFrame_270 = 270
     68 };
     69 
     70 struct 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.
    100 class 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().
    129 class 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 
    148 class WEBRTC_DLLEXPORT ViECapture {
    149  public:
    150   // Factory for the ViECapture subAPI 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