Add PeerConnectionInterface::UpdateCallBitrate.

webrtc/api/peerconnectioninterface.h

 /*
  *  Copyright 2012 The WebRTC project authors. All Rights Reserved.
  *
  *  Use of this source code is governed by a BSD-style license
  *  that can be found in the LICENSE file in the root of the source
  *  tree. An additional intellectual property rights grant can be found
  *  in the file PATENTS.  All contributing project authors may
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
@@ skipping 710 matching lines @@
       const std::vector<cricket::Candidate>& candidates) {
     return false;
   }
 
   // Register a metric observer (used by chromium).
   //
   // There can only be one observer at a time. Before the observer is
   // destroyed, RegisterUMAOberver(nullptr) should be called.
   virtual void RegisterUMAObserver(UMAObserver* observer) = 0;
 
+  // The implementation is free to choose whatever values it wants for unset
+  // parameters. 0 <= min <= start <= max should hold for set parameters.
+  // Changing start will reset the current bitrate estimate.

[Taylor Brandstetter, 2017/04/13 22:16:13]

nit: I'd still prefer a more thorough description. For example:

"SetBitrate can be used to control the bandwidth allocated for all
RTP streams sent by this PeerConnection, within the bounds of other limits that
may be imposed (for example, by "b=TIAS" in SDP).

|min_bitrate_bps| and |max_bitrate_bps|, if set, clamp the allocated bandwidth,
which typically would come from the bandwidth estimator. For example, if
|max_bitrate_bps| is set to 2Mbps, the bandwidth allocated for all RTP streams
will not exceed 2Mbps, even if the bandwidth estimator predicts that more
bandwidth is available.

|start_bitrate_bps|, if set, resets the current bandwidth allocation, which may
increase or decrease as the bandwidth estimator continues to operate. If
SetBitrate is called a second time, and |start_bitrate_bps| is different from
the previous value, the bandwidth allocation will be reset to the provided
value. Otherwise (if |start_bitrate_bps| is unchanged), it will have no effect."

+  struct BitrateParameters {
+    rtc::Optional<int> min_bitrate_bps;
+    rtc::Optional<int> start_bitrate_bps;

[Taylor Brandstetter, 2017/04/13 22:16:13]

While writing the above description, I was reminded that "start_bitrate_bps"
isn't the most intuitive interface. It's called "start", but it could be used in
the middle of a call. And the rule that it only has an effect if it changes
means that if an application wants to restart bandwidth estimation from the same
point it last started, it would need to do something like:

BitrateParameters new_params;
// Needs to be different from the previous value to have an effect.
new_params.start_bitrate_bps.emplace(old_start_bitrate+1);
pc->SetBitrate(new_params);

What do you think about changing it to "current_bitrate_bps", and changing the
behavior to "reset current bitrate *any time* it's set", not just when it's
different from the previous value? Hopefully I'm making sense.

[Zach Stein, 2017/04/18 22:54:50]

I like current better than start, but I would prefer not to change
SetBweBitrates to interpret the same value as a reset in this change and adding
1 to start in peerconnection.cc seems too hacky to me.

[Taylor Brandstetter, 2017/04/19 01:06:53]

When you say you'd prefer not changing SetBweBitrates in this change, you mean
you'd rather do it in a standalone CL? That seems like a good idea. It would be
preferable to land that CL before this one, so that the PeerConnection API has
the right semantics the first time it's introduced. Otherwise applications could
start using it, then be surprised when its behavior changes.

[Zach Stein, 2017/04/20 20:48:00]

Looking at SetBweBitrates again, I think it actually sets current/start as long
as it is > 0, so I can make this change in Call in this CL.

+    rtc::Optional<int> max_bitrate_bps;
+  };
+
+  // Sets bitrate parameters for the entire connection.
+  virtual void SetBitrate(const BitrateParameters& bitrate) = 0;

[Taylor Brandstetter, 2017/04/13 22:16:13]

nit: "SetBitrateParameters"?

+
   // Returns the current SignalingState.
   virtual SignalingState signaling_state() = 0;
   virtual IceConnectionState ice_connection_state() = 0;
   virtual IceGatheringState ice_gathering_state() = 0;
 
   // Starts RtcEventLog using existing file. Takes ownership of |file| and
   // passes it on to Call, which will take the ownership. If the
   // operation fails the file will be closed. The logging will stop
   // automatically after 10 minutes have passed, or when the StopRtcEventLog
   // function is called.
@@ skipping 357 matching lines @@
     cricket::WebRtcVideoEncoderFactory* encoder_factory,
     cricket::WebRtcVideoDecoderFactory* decoder_factory) {
   return CreatePeerConnectionFactory(
       worker_and_network_thread, worker_and_network_thread, signaling_thread,
       default_adm, encoder_factory, decoder_factory);
 }
 
 }  // namespace webrtc
 
 #endif  // WEBRTC_API_PEERCONNECTIONINTERFACE_H_