Clarifies the bandwidth estimation interfaces.

BUG=

Review URL: https://webrtc-codereview.appspot.com/965019

git-svn-id: http://webrtc.googlecode.com/svn/trunk@3087 4adac7df-926f-26a2-2b94-8c16560cd09d

webrtc/modules/bitrate_controller/include/bitrate_controller.h

@@ -23,10 +23,12 @@ class BitrateObserver {
  /*
   * Observer class for the encoders, each encoder should implement this class
   * to get the target bitrate. It also get the fraction loss and rtt to
-  * optimize its settings for this type of network.
+  * optimize its settings for this type of network. |target_bitrate| is the
+  * target media/payload bitrate excluding packet headers, measured in bits
+  * per second.
   */
  public:
-  virtual void OnNetworkChanged(const uint32_t targer_bitrate,
+  virtual void OnNetworkChanged(const uint32_t target_bitrate,
                                 const uint8_t fraction_loss,  // 0 - 255.
                                 const uint32_t rtt) = 0;
 
@@ -46,6 +48,8 @@ class BitrateController {
 
   virtual RtcpBandwidthObserver* CreateRtcpBandwidthObserver() = 0;
 
+  // Gets the available payload bandwidth in bits per second. Note that
+  // this bandwidth excludes packet headers.
   virtual bool AvailableBandwidth(uint32_t* bandwidth) const = 0;
 
   /*

webrtc/modules/remote_bitrate_estimator/include/remote_bitrate_estimator.h

@@ -50,11 +50,12 @@ class RemoteBitrateEstimator {
   virtual void IncomingRtcp(unsigned int ssrc, uint32_t ntp_secs,
                             uint32_t ntp_frac, uint32_t rtp_timestamp) = 0;
 
-  // Called for each incoming packet. The first SSRC will immediately be used
+  // Called for each incoming packet. Updates the incoming payload bitrate
-  // for overuse detection. Subsequent SSRCs will only be used when at least
+  // estimate and the over-use detector. If an over-use is detected the
-  // two RTCP SR reports with the same SSRC have been received.
+  // remote bitrate estimate will be updated. Note that |payload_size| is the
+  // packet size excluding headers.
   virtual void IncomingPacket(unsigned int ssrc,
-                              int packet_size,
+                              int payload_size,
                               int64_t arrival_time,
                               uint32_t rtp_timestamp) = 0;
 
@@ -69,7 +70,7 @@ class RemoteBitrateEstimator {
   virtual void RemoveStream(unsigned int ssrc) = 0;
 
   // Returns true if a valid estimate exists and sets |bitrate_bps| to the
-  // estimated bitrate in bits per second.
+  // estimated payload bitrate in bits per second.
   virtual bool LatestEstimate(unsigned int ssrc,
                               unsigned int* bitrate_bps) const = 0;
 };

webrtc/modules/remote_bitrate_estimator/remote_bitrate_estimator_multi_stream.cc

@@ -79,11 +79,11 @@ void RemoteBitrateEstimatorMultiStream::IncomingRtcp(unsigned int ssrc,
 }
 
 void RemoteBitrateEstimatorMultiStream::IncomingPacket(unsigned int ssrc,
-                                                       int packet_size,
+                                                       int payload_size,
                                                        int64_t arrival_time,
                                                        uint32_t rtp_timestamp) {
   CriticalSectionScoped cs(crit_sect_.get());
-  incoming_bitrate_.Update(packet_size, arrival_time);
+  incoming_bitrate_.Update(payload_size, arrival_time);
   StreamMap::iterator stream_it = streams_.find(ssrc);
   if (initial_ssrc_ == 0) {
     initial_ssrc_ = ssrc;
@@ -104,7 +104,7 @@ void RemoteBitrateEstimatorMultiStream::IncomingPacket(unsigned int ssrc,
     synchronization::RtpToNtpMs(rtp_timestamp, stream_it->second,
                                 &timestamp_in_ms);
   }
-  overuse_detector_.Update(packet_size, timestamp_in_ms, rtp_timestamp,
+  overuse_detector_.Update(payload_size, timestamp_in_ms, rtp_timestamp,
                            arrival_time);
   if (prior_state != kBwOverusing &&
       overuse_detector_.State() == kBwOverusing) {

webrtc/modules/remote_bitrate_estimator/remote_bitrate_estimator_multi_stream.h

@@ -41,10 +41,13 @@ class RemoteBitrateEstimatorMultiStream : public RemoteBitrateEstimator {
                     uint32_t rtp_timestamp);
 
   // Called for each incoming packet. The first SSRC will immediately be used
-  // for overuse detection. Subsequent SSRCs will only be used when at least
+  // for over-use detection. Subsequent SSRCs will only be used when at least
-  // two RTCP SR reports with the same SSRC have been received.
+  // two RTCP SR reports with the same SSRC have been received. Updates the
+  // incoming payload bitrate estimate and the over-use detector.
+  // If an over-use is detected the remote bitrate estimate will be updated.
+  // Note that |payload_size| is the packet size excluding headers.
   void IncomingPacket(unsigned int ssrc,
-                      int packet_size,
+                      int payload_size,
                       int64_t arrival_time,
                       uint32_t rtp_timestamp);
 
@@ -59,7 +62,7 @@ class RemoteBitrateEstimatorMultiStream : public RemoteBitrateEstimator {
   void RemoveStream(unsigned int ssrc);
 
   // Returns true if a valid estimate exists and sets |bitrate_bps| to the
-  // estimated bitrate in bits per second.
+  // estimated payload bitrate in bits per second.
   bool LatestEstimate(unsigned int ssrc, unsigned int* bitrate_bps) const;
 
  private:

webrtc/modules/remote_bitrate_estimator/remote_bitrate_estimator_single_stream.cc

@@ -24,7 +24,7 @@ RemoteBitrateEstimatorSingleStream::RemoteBitrateEstimatorSingleStream(
 
 void RemoteBitrateEstimatorSingleStream::IncomingPacket(
     unsigned int ssrc,
-    int packet_size,
+    int payload_size,
     int64_t arrival_time,
     uint32_t rtp_timestamp) {
   CriticalSectionScoped cs(crit_sect_.get());
@@ -42,9 +42,9 @@ void RemoteBitrateEstimatorSingleStream::IncomingPacket(
     it = insert_result.first;
   }
   OveruseDetector* overuse_detector = &it->second;
-  incoming_bitrate_.Update(packet_size, arrival_time);
+  incoming_bitrate_.Update(payload_size, arrival_time);
   const BandwidthUsage prior_state = overuse_detector->State();
-  overuse_detector->Update(packet_size, -1, rtp_timestamp, arrival_time);
+  overuse_detector->Update(payload_size, -1, rtp_timestamp, arrival_time);
   if (prior_state != overuse_detector->State() &&
       overuse_detector->State() == kBwOverusing) {
     // The first overuse should immediately trigger a new estimate.

webrtc/modules/remote_bitrate_estimator/remote_bitrate_estimator_single_stream.h

@@ -34,9 +34,12 @@ class RemoteBitrateEstimatorSingleStream : public RemoteBitrateEstimator {
                     uint32_t rtp_timestamp) {}
 
   // Called for each incoming packet. If this is a new SSRC, a new
-  // BitrateControl will be created.
+  // BitrateControl will be created. Updates the incoming payload bitrate
+  // estimate and the over-use detector. If an over-use is detected the
+  // remote bitrate estimate will be updated. Note that |payload_size| is the
+  // packet size excluding headers.
   void IncomingPacket(unsigned int ssrc,
-                      int packet_size,
+                      int payload_size,
                       int64_t arrival_time,
                       uint32_t rtp_timestamp);
 
@@ -51,7 +54,8 @@ class RemoteBitrateEstimatorSingleStream : public RemoteBitrateEstimator {
   void RemoveStream(unsigned int ssrc);
 
   // Returns true if a valid estimate exists for a stream identified by |ssrc|
-  // and sets |bitrate_bps| to the estimated bitrate in bits per second.
+  // and sets |bitrate_bps| to the estimated payload bitrate in bits per
+  // second.
   bool LatestEstimate(unsigned int ssrc, unsigned int* bitrate_bps) const;
 
  private: