Rename AudioRenderer::Play/Pause() to Start/StopRendering().

media/filters/audio_renderer_impl.h

 // Copyright (c) 2012 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.
 
 // Audio rendering unit utilizing an AudioRendererSink to output data.
 //
 // This class lives inside three threads during it's lifetime, namely:
 // 1. Render thread
 //    Where the object is created.
 // 2. Media thread (provided via constructor)
@@ skipping 54 matching lines @@
   virtual ~AudioRendererImpl();
 
   // AudioRenderer implementation.
   virtual void Initialize(DemuxerStream* stream,
                           const PipelineStatusCB& init_cb,
                           const StatisticsCB& statistics_cb,
                           const base::Closure& underflow_cb,
                           const TimeCB& time_cb,
                           const base::Closure& ended_cb,
                           const PipelineStatusCB& error_cb) OVERRIDE;
-  virtual void Play() OVERRIDE;
-  virtual void Pause() OVERRIDE;
+  virtual void StartRendering() OVERRIDE;
+  virtual void StopRendering() OVERRIDE;
   virtual void Flush(const base::Closure& callback) OVERRIDE;
   virtual void Stop(const base::Closure& callback) OVERRIDE;
   virtual void SetPlaybackRate(float rate) OVERRIDE;
   virtual void Preroll(base::TimeDelta time,
                        const PipelineStatusCB& cb) OVERRIDE;
   virtual void ResumeAfterUnderflow() OVERRIDE;
   virtual void SetVolume(float volume) OVERRIDE;
 
   // Disables underflow support.  When used, |state_| will never transition to
   // kUnderflow resulting in Render calls that underflow returning 0 frames
   // instead of some number of silence frames.  Must be called prior to
   // Initialize().
   void DisableUnderflowForTesting();
 
   // Allows injection of a custom time callback for non-realtime testing.
   typedef base::Callback<base::TimeTicks()> NowCB;
   void set_now_cb_for_testing(const NowCB& now_cb) {
     now_cb_ = now_cb;
   }
 
  private:
   friend class AudioRendererImplTest;
 
-  // TODO(acolwell): Add a state machine graph.
+  // Important detail: being in kPlaying doesn't imply that audio is being
+  // rendered. Rather, it means that the renderer is ready to go. The actual
+  // rendering of audio is controlled via Start/StopRendering().
+  //
+  //   kUninitialized
+  //         | Initialize()
+  //         |
+  //         V
+  //    kInitializing
+  //         | Decoders initialized
+  //         |
+  //         V            Decoders reset
+  //      kFlushed <------------------ kFlushing
+  //         | Preroll()                  ^
+  //         |                            |
+  //         V                            | Flush()
+  //     kPrerolling ----------------> kPlaying ---------.
+  //           Enough data buffered       ^              | Not enough data
+  //                                      |              | buffered
+  //                 Enough data buffered |              V
+  //                                 kRebuffering <--- kUnderflow
+  //                                      ResumeAfterUnderflow()
   enum State {
     kUninitialized,
     kInitializing,
-    kPaused,
     kFlushing,
+    kFlushed,
     kPrerolling,
     kPlaying,

[xhwang1, 2014/05/12 18:48:56]

nit: now what does kPlaying exactly mean?

[scherkus (not reviewing), 2014/05/12 18:55:32]

see the comment I added above -- unless your nit is that you feel the comment
doesn't explain what kPlaying is :)

the model we're moving towards is that we're always in a playing state, but that
it requires the clock to be advancing (i.e., by starting/stopping rendering of
audio)

     kStopped,
     kUnderflow,
     kRebuffering,
   };
 
   // Callback from the audio decoder delivering decoded audio samples.
   void DecodedAudioReady(AudioBufferStream::Status status,
                          const scoped_refptr<AudioBuffer>& buffer);
 
   // Handles buffers that come out of |splicer_|.
   // Returns true if more buffers are needed.
   bool HandleSplicerBuffer(const scoped_refptr<AudioBuffer>& buffer);
 
   // Helper functions for AudioDecoder::Status values passed to
   // DecodedAudioReady().
   void HandleAbortedReadOrDecodeError(bool is_decode_error);
 
   // Estimate earliest time when current buffer can stop playing.
   void UpdateEarliestEndTime_Locked(int frames_filled,
                                     const base::TimeDelta& playback_delay,
                                     const base::TimeTicks& time_now);
 
-  void DoPlay_Locked();
-  void DoPause_Locked();
+  void StartRendering_Locked();
+  void StopRendering_Locked();
 
   // AudioRendererSink::RenderCallback implementation.
   //
   // NOTE: These are called on the audio callback thread!
   //
   // Render() fills the given buffer with audio data by delegating to its
   // |algorithm_|. Render() also takes care of updating the clock.
   // Returns the number of frames copied into |audio_bus|, which may be less
   // than or equal to the initial number of frames in |audio_bus|
   //
@@ skipping 86 matching lines @@
   // After Initialize() has completed, all variables below must be accessed
   // under |lock_|. ------------------------------------------------------------
   base::Lock lock_;
 
   // Algorithm for scaling audio.
   scoped_ptr<AudioRendererAlgorithm> algorithm_;
 
   // Simple state tracking variable.
   State state_;
 
-  // Keep track of whether or not the sink is playing.
+  // Keep track of whether or not the sink is playing and whether we should be
+  // rendering.
+  bool rendering_;
   bool sink_playing_;
 
   // Keep track of our outstanding read to |decoder_|.
   bool pending_read_;
 
   // Keeps track of whether we received and rendered the end of stream buffer.
   bool received_end_of_stream_;
   bool rendered_end_of_stream_;
 
   scoped_ptr<AudioClock> audio_clock_;
@@ skipping 27 matching lines @@
 
   // NOTE: Weak pointers must be invalidated before all other member variables.
   base::WeakPtrFactory<AudioRendererImpl> weak_factory_;
 
   DISALLOW_COPY_AND_ASSIGN(AudioRendererImpl);
 };
 
 }  // namespace media
 
 #endif  // MEDIA_FILTERS_AUDIO_RENDERER_IMPL_H_