src/third_party/webrtc/video_engine/include/vie_base.h

   1 /*
   2  *  Copyright (c) 2012 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 //  - Creating and deleting VideoEngine instances.
  14 //  - Creating and deleting channels.
  15 //  - Connect a video channel with a corresponding voice channel for audio/video
  16 //    synchronization.
  17 //  - Start and stop sending and receiving.
  18
  19 #ifndef WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_BASE_H_
  20 #define WEBRTC_VIDEO_ENGINE_INCLUDE_VIE_BASE_H_
  21
  22 #include "webrtc/common_types.h"
  23
  24 #if defined(ANDROID) && !defined(WEBRTC_CHROMIUM_BUILD)
  25 #include <jni.h>
  26 #endif
  27
  28 namespace webrtc {
  29
  30 class Config;
  31 class VoiceEngine;
  32
  33 // CpuOveruseObserver is called when a system overuse is detected and
  34 // VideoEngine cannot keep up the encoding frequency.
  35 class CpuOveruseObserver {
  36  public:
  37   // Called as soon as an overuse is detected.
  38   virtual void OveruseDetected() = 0;
  39   // Called periodically when the system is not overused any longer.
  40   virtual void NormalUsage() = 0;
  41
  42  protected:
  43   virtual ~CpuOveruseObserver() {}
  44 };
  45
  46 struct CpuOveruseOptions {
  47   CpuOveruseOptions()
  48       : enable_capture_jitter_method(true),
  49         low_capture_jitter_threshold_ms(20.0f),
  50         high_capture_jitter_threshold_ms(30.0f),
  51         enable_encode_usage_method(false),
  52         low_encode_usage_threshold_percent(60),
  53         high_encode_usage_threshold_percent(90),
  54         low_encode_time_rsd_threshold(-1),
  55         high_encode_time_rsd_threshold(-1),
  56         frame_timeout_interval_ms(1500),
  57         min_frame_samples(120),
  58         min_process_count(3),
  59         high_threshold_consecutive_count(2) {}
  60
  61   // Method based on inter-arrival jitter of captured frames.
  62   bool enable_capture_jitter_method;
  63   float low_capture_jitter_threshold_ms;  // Threshold for triggering underuse.
  64   float high_capture_jitter_threshold_ms; // Threshold for triggering overuse.
  65   // Method based on encode time of frames.
  66   bool enable_encode_usage_method;
  67   int low_encode_usage_threshold_percent;  // Threshold for triggering underuse.
  68   int high_encode_usage_threshold_percent; // Threshold for triggering overuse.
  69   int low_encode_time_rsd_threshold;   // Additional threshold for triggering
  70                                        // underuse (used in addition to
  71                                        // threshold above if configured).
  72   int high_encode_time_rsd_threshold;  // Additional threshold for triggering
  73                                        // overuse (used in addition to
  74                                        // threshold above if configured).
  75   // General settings.
  76   int frame_timeout_interval_ms;  // The maximum allowed interval between two
  77                                   // frames before resetting estimations.
  78   int min_frame_samples;  // The minimum number of frames required.
  79   int min_process_count;  // The number of initial process times required before
  80                           // triggering an overuse/underuse.
  81   int high_threshold_consecutive_count; // The number of consecutive checks
  82                                         // above the high threshold before
  83                                         // triggering an overuse.
  84
  85   bool Equals(const CpuOveruseOptions& o) const {
  86     return enable_capture_jitter_method == o.enable_capture_jitter_method &&
  87         low_capture_jitter_threshold_ms == o.low_capture_jitter_threshold_ms &&
  88         high_capture_jitter_threshold_ms ==
  89         o.high_capture_jitter_threshold_ms &&
  90         enable_encode_usage_method == o.enable_encode_usage_method &&
  91         low_encode_usage_threshold_percent ==
  92         o.low_encode_usage_threshold_percent &&
  93         high_encode_usage_threshold_percent ==
  94         o.high_encode_usage_threshold_percent &&
  95         low_encode_time_rsd_threshold == o.low_encode_time_rsd_threshold &&
  96         high_encode_time_rsd_threshold == o.high_encode_time_rsd_threshold &&
  97         frame_timeout_interval_ms == o.frame_timeout_interval_ms &&
  98         min_frame_samples == o.min_frame_samples &&
  99         min_process_count == o.min_process_count &&
 100         high_threshold_consecutive_count == o.high_threshold_consecutive_count;
 101   }
 102 };
 103
 104 struct CpuOveruseMetrics {
 105   CpuOveruseMetrics()
 106       : capture_jitter_ms(-1),
 107         avg_encode_time_ms(-1),
 108         encode_usage_percent(-1),
 109         encode_rsd(-1),
 110         capture_queue_delay_ms_per_s(-1) {}
 111
 112   int capture_jitter_ms;  // The current estimated jitter in ms based on
 113                           // incoming captured frames.
 114   int avg_encode_time_ms;   // The average encode time in ms.
 115   int encode_usage_percent; // The average encode time divided by the average
 116                             // time difference between incoming captured frames.
 117   int encode_rsd;           // The relative std dev of encode time of frames.
 118   int capture_queue_delay_ms_per_s;  // The current time delay between an
 119                                      // incoming captured frame until the frame
 120                                      // is being processed. The delay is
 121                                      // expressed in ms delay per second.
 122 };
 123
 124 class WEBRTC_DLLEXPORT VideoEngine {
 125  public:
 126   // Creates a VideoEngine object, which can then be used to acquire sub‐APIs.
 127   static VideoEngine* Create();
 128   static VideoEngine* Create(const Config& config);
 129
 130   // Deletes a VideoEngine instance.
 131   static bool Delete(VideoEngine*& video_engine);
 132
 133   // Specifies the amount and type of trace information, which will be created
 134   // by the VideoEngine.
 135   static int SetTraceFilter(const unsigned int filter);
 136
 137   // Sets the name of the trace file and enables non‐encrypted trace messages.
 138   static int SetTraceFile(const char* file_nameUTF8,
 139                           const bool add_file_counter = false);
 140
 141   // Installs the TraceCallback implementation to ensure that the VideoEngine
 142   // user receives callbacks for generated trace messages.
 143   static int SetTraceCallback(TraceCallback* callback);
 144
 145 #if defined(ANDROID) && !defined(WEBRTC_CHROMIUM_BUILD)
 146   // Android specific.
 147   static int SetAndroidObjects(JavaVM* java_vm, jobject context);
 148 #endif
 149
 150  protected:
 151   VideoEngine() {}
 152   virtual ~VideoEngine() {}
 153 };
 154
 155 class WEBRTC_DLLEXPORT ViEBase {
 156  public:
 157   // Factory for the ViEBase sub‐API and increases an internal reference
 158   // counter if successful. Returns NULL if the API is not supported or if
 159   // construction fails.
 160   static ViEBase* GetInterface(VideoEngine* video_engine);
 161
 162   // Releases the ViEBase sub-API and decreases an internal reference counter.
 163   // Returns the new reference count. This value should be zero
 164   // for all sub-API:s before the VideoEngine object can be safely deleted.
 165   virtual int Release() = 0;
 166
 167   // Initiates all common parts of the VideoEngine.
 168   virtual int Init() = 0;
 169
 170   // Connects a VideoEngine instance to a VoiceEngine instance for audio video
 171   // synchronization.
 172   virtual int SetVoiceEngine(VoiceEngine* voice_engine) = 0;
 173
 174   // Creates a new channel.
 175   virtual int CreateChannel(int& video_channel) = 0;
 176
 177   // Creates a new channel grouped together with |original_channel|. The channel
 178   // can both send and receive video. It is assumed the channel is sending
 179   // and/or receiving video to the same end-point.
 180   // Note: |CreateReceiveChannel| will give better performance and network
 181   // properties for receive only channels.
 182   virtual int CreateChannel(int& video_channel,
 183                             int original_channel) = 0;
 184
 185   // Creates a new channel grouped together with |original_channel|. The channel
 186   // can only receive video and it is assumed the remote end-point is the same
 187   // as for |original_channel|.
 188   virtual int CreateReceiveChannel(int& video_channel,
 189                                    int original_channel) = 0;
 190
 191   // Deletes an existing channel and releases the utilized resources.
 192   virtual int DeleteChannel(const int video_channel) = 0;
 193
 194   // Registers an observer to be called when an overuse is detected, see
 195   // 'CpuOveruseObserver' for details.
 196   // NOTE: This is still very experimental functionality.
 197   virtual int RegisterCpuOveruseObserver(int channel,
 198                                          CpuOveruseObserver* observer) = 0;
 199
 200   // Sets options for cpu overuse detector.
 201   virtual int SetCpuOveruseOptions(int channel,
 202                                    const CpuOveruseOptions& options) = 0;
 203
 204   // Gets cpu overuse measures.
 205   virtual int GetCpuOveruseMetrics(int channel, CpuOveruseMetrics* metrics) = 0;
 206
 207   // Registers a callback which is called when send-side delay statistics has
 208   // been updated.
 209   // TODO(holmer): Remove the default implementation when fakevideoengine.h has
 210   // been updated.
 211   virtual void RegisterSendSideDelayObserver(
 212       int channel, SendSideDelayObserver* observer) {}
 213
 214   // Specifies the VoiceEngine and VideoEngine channel pair to use for
 215   // audio/video synchronization.
 216   virtual int ConnectAudioChannel(const int video_channel,
 217                                   const int audio_channel) = 0;
 218
 219   // Disconnects a previously paired VideoEngine and VoiceEngine channel pair.
 220   virtual int DisconnectAudioChannel(const int video_channel) = 0;
 221
 222   // Starts sending packets to an already specified IP address and port number
 223   // for a specified channel.
 224   virtual int StartSend(const int video_channel) = 0;
 225
 226   // Stops packets from being sent for a specified channel.
 227   virtual int StopSend(const int video_channel) = 0;
 228
 229   // Prepares VideoEngine for receiving packets on the specified channel.
 230   virtual int StartReceive(const int video_channel) = 0;
 231
 232   // Stops receiving incoming RTP and RTCP packets on the specified channel.
 233   virtual int StopReceive(const int video_channel) = 0;
 234
 235   // Retrieves the version information for VideoEngine and its components.
 236   virtual int GetVersion(char version[1024]) = 0;
 237
 238   // Returns the last VideoEngine error code.
 239   virtual int LastError() = 0;
 240
 241  protected:
 242   ViEBase() {}
 243   virtual ~ViEBase() {}
 244 };
 245
 246 }  // namespace webrtc
 247
 248 #endif  // #define WEBRTC_VIDEO_ENGINE_MAIN_INTERFACE_VIE_BASE_H_