Add PeerConnectionInterface::UpdateCallBitrate.

webrtc/api/peerconnectioninterface.h

Index: webrtc/api/peerconnectioninterface.h
diff --git a/webrtc/api/peerconnectioninterface.h b/webrtc/api/peerconnectioninterface.h
index e96545736257bdbd25b27715bf48c828926d4dcb..31d8ca18a77a969566929449a41f2bd63243c427 100644
--- a/webrtc/api/peerconnectioninterface.h
+++ b/webrtc/api/peerconnectioninterface.h
@@ -728,6 +728,18 @@ class PeerConnectionInterface : public rtc::RefCountInterface {
   // 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;