Have AudioRendererImpl advance time until it's told to stop.

media/filters/audio_clock.h

Index: media/filters/audio_clock.h
diff --git a/media/filters/audio_clock.h b/media/filters/audio_clock.h
index 1a27dee00092dea9134950f7ba5b97c83c6951b5..33c13d23fa390253c5b81feb9a8e8cb529f348f1 100644
--- a/media/filters/audio_clock.h
+++ b/media/filters/audio_clock.h
@@ -16,6 +16,36 @@ namespace media {
 // estimating the amount of delay in wall clock time. Takes changes in playback
 // rate into account to handle scenarios where multiple rates may be present in
 // a playback pipeline with large delay.
+//
+//
+// USAGE
+//
+// Prior to starting audio playback, construct an AudioClock with an initial
+// media timestamp and a sample rate matching the sample rate the audio device
+// was opened at.
+//
+// Each time the audio rendering callback is executed, call WroteAudio() once
+// (and only once!) containing information on what was written:
+//   1) How many frames of audio data requested
+//   2) How many frames of audio data provided
+//   3) The playback rate of the audio data provided
+//   4) The current amount of delay
+//
+// After a call to WroteAudio(), clients can inspect the resulting media
+// timestamp. This can be used for UI purposes, synchronizing video, etc...
+//
+//
+// DETAILS
+//
+// Silence (whether caused by the initial audio delay or failing to write the
+// amount of requested frames due to underflow) is also modeled and will cause
+// the media timestamp to stop increasing until all known silence has been
+// played. AudioClock's model is initialized with silence during the first call
+// to WroteAudio() using the delay value.
+//
+// Playback rates are tracked for translating frame durations into media
+// durations. Since silence doesn't affect media timestamps, it also isn't
+// affected by playback rates.
 class MEDIA_EXPORT AudioClock {
  public:
   AudioClock(base::TimeDelta start_timestamp, int sample_rate);
@@ -29,15 +59,29 @@ class MEDIA_EXPORT AudioClock {
                   int delay_frames,
                   float playback_rate);
 
-  // Calculates the current media timestamp taking silence and changes in
-  // playback rate into account.
-  base::TimeDelta current_media_timestamp() const {
-    return current_media_timestamp_;
-  }
+  // Returns the bounds of media data currently buffered by the audio hardware,
+  // taking silence and changes in playback rate into account. Buffered audio
+  // structure and timestamps are updated with every call to WroteAudio().
+  //
+  //  start_timestamp = 1000 ms                           sample_rate = 40 Hz
+  // +-----------------------+-----------------------+-----------------------+
+  // |   10 frames silence   |   20 frames @ 1.0x    |   20 frames @ 0.5x    |
+  // |      = 250 ms (wall)  |      = 500 ms (wall)  |      = 500 ms (wall)  |
+  // |      =   0 ms (media) |      = 500 ms (media) |      = 250 ms (media) |
+  // +-----------------------+-----------------------+-----------------------+
+  // ^                                                                       ^
+  // front_timestamp() is equal to               back_timestamp() is equal to
+  // |start_timestamp| since no                  amount of media frames tracked
+  // media data has been played yet.             by AudioClock, which would be
+  //                                             1000 + 500 + 250 = 1750 ms.
+  base::TimeDelta front_timestamp() const { return front_timestamp_; }
+  base::TimeDelta back_timestamp() const { return back_timestamp_; }
 
   // Clients can provide |time_since_writing| to simulate the passage of time
   // since last writing audio to get a more accurate current media timestamp.
-  base::TimeDelta CurrentMediaTimestampSinceWriting(
+  //
+  // The value will be bounded between front_timestamp() and back_timestamp().
+  base::TimeDelta TimestampSinceWriting(
       base::TimeDelta time_since_writing) const;
 
   // Returns the amount of contiguous media time buffered at the head of the
@@ -53,10 +97,6 @@ class MEDIA_EXPORT AudioClock {
     return contiguous_audio_data_buffered_at_same_rate_;
   }
 
-  // Returns true if there is any audio data buffered by the audio hardware,
-  // even if there is silence mixed in.
-  bool audio_data_buffered() const { return audio_data_buffered_; }
-
  private:
   // Even with a ridiculously high sample rate of 256kHz, using 64 bits will
   // permit tracking up to 416999965 days worth of time (that's 1141 millenia).
@@ -81,10 +121,10 @@ class MEDIA_EXPORT AudioClock {
   std::deque<AudioData> buffered_;
   int64_t total_buffered_frames_;
 
-  base::TimeDelta current_media_timestamp_;
+  base::TimeDelta front_timestamp_;
+  base::TimeDelta back_timestamp_;
 
   // Cached results of last call to WroteAudio().
-  bool audio_data_buffered_;
   base::TimeDelta contiguous_audio_data_buffered_;
   base::TimeDelta contiguous_audio_data_buffered_at_same_rate_;