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