[Cast] Refactor/clean-up VideoReceiver to match AudioReceiver as closely as possible.

media/cast/audio_receiver/audio_receiver.h

 // Copyright 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef MEDIA_CAST_AUDIO_RECEIVER_AUDIO_RECEIVER_H_
 #define MEDIA_CAST_AUDIO_RECEIVER_AUDIO_RECEIVER_H_
 
 #include "base/basictypes.h"
 #include "base/callback.h"
 #include "base/macros.h"
@@ skipping 13 matching lines @@
 #include "media/cast/rtp_receiver/rtp_receiver_defines.h"
 #include "media/cast/transport/utility/transport_encryption_handler.h"
 
 namespace media {
 namespace cast {
 
 class AudioDecoder;
 
 // AudioReceiver receives packets out-of-order while clients make requests for
 // complete frames in-order.  (A frame consists of one or more packets.)
-// AudioReceiver also includes logic for mapping RTP timestamps to the local
-// base::TimeTicks clock for each frame.
+//
+// AudioReceiver also includes logic for computing the playout time for each
+// frame, accounting for a constant targeted playout delay.  The purpose of the
+// playout delay is to provide a fixed window of time between the capture event
+// on the sender and the playout on the receiver.  This is important because
+// each step of the pipeline (i.e., encode frame, then transmit/retransmit from
+// the sender, then receive and re-order packets on the receiver, then decode
+// frame) can vary in duration and is typically very hard to predict.
+// Heuristics will determine when the targeted playout delay is insufficient in
+// the current environment; and the receiver can then increase the playout
+// delay, notifying the sender, to account for the extra variance.
+// TODO(miu): Make the last sentence true.  http://crbug.com/360111
 //
 // Two types of frames can be requested: 1) A frame of decoded audio data; or 2)
 // a frame of still-encoded audio data, to be passed into an external audio
 // decoder.  Each request for a frame includes a callback which AudioReceiver
 // guarantees will be called at some point in the future.  Clients should
 // generally limit the number of outstanding requests (perhaps to just one or
 // two).  When AudioReceiver is destroyed, any outstanding requests will be
 // immediately invoked with a NULL frame.
 //
 // This class is not thread safe.  Should only be called from the Main cast
@@ skipping 10 matching lines @@
   virtual ~AudioReceiver();
 
   // Request a decoded audio frame.  The audio signal data returned in the
   // callback will have the sampling rate and number of channels as requested in
   // the configuration that was passed to the ctor.
   //
   // The given |callback| is guaranteed to be run at some point in the future,
   // even if to respond with NULL at shutdown time.
   void GetRawAudioFrame(const AudioFrameDecodedCallback& callback);
 
-  // Extract an encoded audio frame from the cast receiver.
+  // Request an encoded audio frame.
   //
   // The given |callback| is guaranteed to be run at some point in the future,
   // even if to respond with NULL at shutdown time.
   void GetEncodedAudioFrame(const AudioFrameEncodedCallback& callback);
 
   // Deliver another packet, possibly a duplicate, and possibly out-of-order.
   void IncomingPacket(scoped_ptr<Packet> packet);
 
   // Update target audio delay used to compute the playout time. Rtcp
   // will also be updated (will be included in all outgoing reports).
@@ skipping 89 matching lines @@
   // NOTE: Weak pointers must be invalidated before all other member variables.
   base::WeakPtrFactory<AudioReceiver> weak_factory_;
 
   DISALLOW_COPY_AND_ASSIGN(AudioReceiver);
 };
 
 }  // namespace cast
 }  // namespace media
 
 #endif  // MEDIA_CAST_AUDIO_RECEIVER_AUDIO_RECEIVER_H_