From 4bae3649d504d590a546717a8e49f96a30d9a745 Mon Sep 17 00:00:00 2001
From: Glenn Kasten <gkasten@google.com>
Date: Fri, 30 Nov 2012 13:41:12 -0800
Subject: [PATCH] flush() comments and checks

flush() is only useful for streaming mode.
It is a no-op if track is active or uses a static buffer.

Change-Id: I918ac181ffae3d16a0d67d8a7208f4aec61b5bd6
---
 include/media/AudioTrack.h    | 11 ++++++++---
 media/libmedia/AudioTrack.cpp | 19 ++++++++++---------
 2 files changed, 18 insertions(+), 12 deletions(-)

diff --git a/include/media/AudioTrack.h b/include/media/AudioTrack.h
index fe46a2224d..d2739f7f79 100644
--- a/include/media/AudioTrack.h
+++ b/include/media/AudioTrack.h
@@ -163,7 +163,7 @@ public:
      * the PCM data to be rendered by AudioTrack is passed in a shared memory buffer
      * identified by the argument sharedBuffer. This prototype is for static buffer playback.
      * PCM data must be present in memory before the AudioTrack is started.
-     * The write() and flush() methods are not supported in this case.
+     * The write() method is not supported in this case.
      * It is recommended to pass a callback function to be notified of playback end by an
      * EVENT_UNDERRUN event.
      */
@@ -247,8 +247,10 @@ public:
             void        stop();
             bool        stopped() const;
 
-    /* Flush a stopped track. All pending buffers are discarded.
-     * This function has no effect if the track is not stopped.
+    /* Flush a stopped or paused track. All previously buffered data is discarded immediately.
+     * This has the effect of draining the buffers without mixing or output.
+     * Flush is intended for streaming mode, for example before switching to non-contiguous content.
+     * This function is a no-op if the track is not stopped or paused, or uses a static buffer.
      */
             void        flush();
 
@@ -492,7 +494,10 @@ protected:
                                  audio_output_flags_t flags,
                                  const sp<IMemory>& sharedBuffer,
                                  audio_io_handle_t output);
+
+            // can only be called when !mActive
             void flush_l();
+
             status_t setLoop_l(uint32_t loopStart, uint32_t loopEnd, int loopCount);
             audio_io_handle_t getOutput_l();
             status_t restoreTrack_l(audio_track_cblk_t*& cblk, bool fromStart);
diff --git a/media/libmedia/AudioTrack.cpp b/media/libmedia/AudioTrack.cpp
index f5641e0690..597d057779 100644
--- a/media/libmedia/AudioTrack.cpp
+++ b/media/libmedia/AudioTrack.cpp
@@ -397,6 +397,7 @@ void AudioTrack::stop()
         mMarkerReached = false;
         // Force flush if a shared buffer is used otherwise audioflinger
         // will not stop before end of buffer is reached.
+        // It may be needed to make sure that we stop playback, likely in case looping is on.
         if (mSharedBuffer != 0) {
             flush_l();
         }
@@ -419,26 +420,26 @@ bool AudioTrack::stopped() const
 void AudioTrack::flush()
 {
     AutoMutex lock(mLock);
-    flush_l();
+    if (!mActive && mSharedBuffer == 0) {
+        flush_l();
+    }
 }
 
-// must be called with mLock held
 void AudioTrack::flush_l()
 {
     ALOGV("flush");
+    ALOG_ASSERT(!mActive);
 
     // clear playback marker and periodic update counter
     mMarkerPosition = 0;
     mMarkerReached = false;
     mUpdatePeriod = 0;
 
-    if (!mActive) {
-        mFlushed = true;
-        mAudioTrack->flush();
-        // Release AudioTrack callback thread in case it was waiting for new buffers
-        // in AudioTrack::obtainBuffer()
-        mCblk->cv.signal();
-    }
+    mFlushed = true;
+    mAudioTrack->flush();
+    // Release AudioTrack callback thread in case it was waiting for new buffers
+    // in AudioTrack::obtainBuffer()
+    mCblk->cv.signal();
 }
 
 void AudioTrack::pause()
-- 
2.11.0