Support flushFromFrame API. (#2271)

* Support flushFromFrame API.

Fixes #2268.

Author: flamme

apps/OboeTester/app/src/main/cpp/NativeAudioContext.cpp

@@ -587,6 +587,25 @@ void ActivityTestOutput::setupMemoryBuffer(std::unique_ptr<uint8_t[]> &buffer, i
     }
 }
 
+int64_t ActivityTestOutput::flushFromFrame(int32_t accuracy, int64_t frame) {
+    std::shared_ptr<oboe::AudioStream> oboeStream = getOutputStream();
+    if (oboeStream == nullptr) {
+        return static_cast<int64_t>(oboe::Result::ErrorInvalidState);
+    }
+    const int64_t requestedFrames = frame;
+    if (auto result = oboeStream->flushFromFrame(
+            static_cast<oboe::FlushFromAccuracy>(accuracy), frame);
+        result.error() != oboe::Result::OK) {
+        LOGE("Failed to flushFromFrame(%d, %jd), error=%d, suggestedFrame=%jd",
+             accuracy, requestedFrames, result.error(), frame);
+        return static_cast<int64_t>(result.error());
+    } else {
+        LOGD("Successfully flushFromFrame(%d, %jd), actual flushed frame: %jd",
+             accuracy, requestedFrames, result.value());
+        return result.value();
+    }
+}
+
 // ======================================================================= ActivityTestInput
 void ActivityTestInput::configureAfterOpen() {
     mInputAnalyzer.reset();

apps/OboeTester/app/src/main/cpp/NativeAudioContext.h

@@ -154,6 +154,10 @@ class ActivityContext {
 
     oboe::Result flush();
 
+    virtual int64_t flushFromFrame(int32_t accuracy, int64_t frame) {
+        return static_cast<int64_t>(oboe::Result::ErrorUnimplemented);
+    }
+
     oboe::Result stopAllStreams();
 
     virtual oboe::Result stop() {
@@ -472,6 +476,8 @@ class ActivityTestOutput : public ActivityContext {
 
     void setupMemoryBuffer(std::unique_ptr<uint8_t[]>& buffer, int length) final;
 
+    int64_t flushFromFrame(int32_t accuracy, int64_t frame) final;
+
 protected:
     SignalType                       mSignalType = SignalType::Sine;
 

apps/OboeTester/app/src/main/cpp/jni-bridge.cpp

@@ -222,6 +222,13 @@ Java_com_mobileer_oboetester_TestAudioActivity_flushNative(JNIEnv *env, jobject)
     return (jint) engine.getCurrentActivity()->flush();
 }
 
+JNIEXPORT jlong JNICALL
+Java_com_mobileer_oboetester_TestAudioActivity_flushFromFrameNative(
+        JNIEnv * /*env*/, jobject, jint accuracy, jlong frames) {
+    return (jlong) engine.getCurrentActivity()->flushFromFrame(
+            accuracy, static_cast<int64_t>(frames));
+}
+
 JNIEXPORT jint JNICALL
 Java_com_mobileer_oboetester_TestAudioActivity_stopNative(JNIEnv *env, jobject) {
     return (jint) engine.getCurrentActivity()->stop();

apps/OboeTester/app/src/main/java/com/mobileer/oboetester/TestAudioActivity.java

@@ -777,6 +777,8 @@ private void openStreamContext(StreamContext streamContext) throws IOException {
 
     private native int releaseNative();
 
+    protected native long flushFromFrameNative(int accuracy, long frames);
+
     protected native void setActivityType(int activityType);
 
     private native int getFramesPerCallback();

apps/OboeTester/app/src/main/java/com/mobileer/oboetester/TestOutputActivity.java

@@ -19,12 +19,17 @@
 import android.os.Bundle;
 import android.os.Handler;
 import android.os.Looper;
+import android.util.Log;
 import android.view.View;
 import android.widget.AdapterView;
+import android.widget.Button;
 import android.widget.CheckBox;
+import android.widget.EditText;
+import android.widget.LinearLayout;
 import android.widget.SeekBar;
 import android.widget.Spinner;
 import android.widget.TextView;
+import android.widget.Toast;
 
 import java.io.IOException;
 import java.util.Locale;
@@ -42,6 +47,11 @@ public final class TestOutputActivity extends TestOutputActivityBase {
     private CheckBox mShouldSetStreamControlByAttributes;
     private boolean mShouldDisableForCompressedFormat = false;
 
+    private LinearLayout mFlushFromFrameLayout;
+    private EditText mFlushFromFrameEditText;
+    private Spinner mFlushFromAccuracySpinner;
+    private Button mFlushFromFrameButton;
+
     private class OutputSignalSpinnerListener implements android.widget.AdapterView.OnItemSelectedListener {
         @Override
         public void onItemSelected(AdapterView<?> parent, View view, int pos, long id) {
@@ -113,6 +123,17 @@ protected void onCreate(Bundle savedInstanceState) {
         mVolumeSeekBar.setOnSeekBarChangeListener(mVolumeChangeListener);
 
         mShouldSetStreamControlByAttributes = (CheckBox) findViewById(R.id.enableSetStreamControlByAttributes);
+
+        mFlushFromFrameLayout = (LinearLayout) findViewById(R.id.flushFromFrameLayout);
+        mFlushFromFrameEditText = (EditText) findViewById(R.id.flushFromFrameEditText);
+        mFlushFromAccuracySpinner = (Spinner) findViewById(R.id.flushFromAccuracySpinner);
+        mFlushFromFrameButton = (Button) findViewById(R.id.flushFromFrameButton);
+        mFlushFromFrameButton.setOnClickListener(new View.OnClickListener() {
+            @Override
+            public void onClick(View v) {
+                flushFromFrame();
+            }
+        });
     }
 
     @Override
@@ -180,6 +201,27 @@ public void startAudio() throws IOException {
         mOutputSignalSpinner.setEnabled(false);
     }
 
+    public void flushFromFrame() {
+        try {
+            int accuracy = mFlushFromAccuracySpinner.getSelectedItemPosition();
+            long positionInFrames = Long.parseLong(mFlushFromFrameEditText.getText().toString());
+            long result = flushFromFrameNative(accuracy, positionInFrames);
+            if (result >= 0) {
+                Toast.makeText(this,
+                        String.format("Successfully flushed from: %d, actual flushed position: %d",
+                                positionInFrames, result),
+                        Toast.LENGTH_LONG).show();
+            } else {
+                Toast.makeText(
+                        this, "Failed to flush from Frame", Toast.LENGTH_LONG).show();
+            }
+        } catch (NumberFormatException e) {
+            Log.e(TAG, "Failed to flushFromFrame, the requested frame(" +
+                    mFlushFromFrameEditText.getText().toString() + ") is invalid");
+            showErrorToast("Invalid number of frames");
+        }
+    }
+
     public void onChannelBoxClicked(View view) {
         CheckBox checkBox = (CheckBox) view;
         String text = (String) checkBox.getText();

apps/OboeTester/app/src/main/res/layout/activity_test_output.xml

@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:app="http://schemas.android.com/apk/res-auto"
     xmlns:tools="http://schemas.android.com/tools"
     android:layout_width="match_parent"
     android:layout_height="match_parent"
@@ -44,6 +45,48 @@
 
         <include layout="@layout/merge_audio_common"/>
 
+        <LinearLayout
+            android:id="@+id/flushFromFrameLayout"
+            android:layout_width="match_parent"
+            android:layout_height="wrap_content"
+            android:orientation="vertical">
+            <LinearLayout
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:orientation="horizontal">
+                <TextView
+                    android:layout_width="wrap_content"
+                    android:layout_height="wrap_content"
+                    android:text="Flush from frame:" />
+                <EditText
+                    android:id="@+id/flushFromFrameEditText"
+                    android:layout_width="0dp"
+                    android:layout_height="wrap_content"
+                    android:layout_weight="1"
+                    android:inputType="number"/>
+            </LinearLayout>
+            <LinearLayout
+                android:layout_width="match_parent"
+                android:layout_height="wrap_content"
+                android:orientation="horizontal">
+                <TextView
+                    android:layout_width="wrap_content"
+                    android:layout_height="wrap_content"
+                    android:text="FlushFromAccuracy:" />
+                <Spinner
+                    android:id="@+id/flushFromAccuracySpinner"
+                    android:layout_width="wrap_content"
+                    android:layout_height="wrap_content"
+                    android:entries="@array/flush_from_accuracy"
+                    android:prompt="@string/flush_from_accuracy_prompt" />
+                <Button
+                    android:id="@+id/flushFromFrameButton"
+                    android:layout_width="match_parent"
+                    android:layout_height="wrap_content"
+                    android:text="Flush From Frame" />
+            </LinearLayout>
+        </LinearLayout>
+
         <HorizontalScrollView
             android:layout_width="wrap_content"
             android:layout_height="wrap_content">

apps/OboeTester/app/src/main/res/values/strings.xml

@@ -350,4 +350,10 @@
     <string name="dynamic_workload_graph_info">
         Dynamic Workload: Black\nCPU Load: Green or Red (Glitch detected)
     </string>
+
+    <string name="flush_from_accuracy_prompt">Choose a FlushFromAccuracy</string>
+    <string-array name="flush_from_accuracy">
+        <item>Undefined</item>
+        <item>Accurate</item>
+    </string-array>
 </resources>

include/oboe/AudioStream.h

@@ -690,6 +690,51 @@ class AudioStream : public AudioStreamBase {
         return Result::ErrorUnimplemented;
     }
 
+    /**
+     * Flush all data from given position. If this operation returns successfully, the following
+     * data will be written from the returned position.
+     *
+     * This method will only available when the performance mode is
+     * PerformanceMode::PowerSavingOffloaded.
+     *
+     * The requested position must not be negative or greater than the written frames. The current
+     * written position can be known by querying getFramesWritten().
+     *
+     * When clients request to flush from a certain position, the audio system will return the
+     * actual flushed position based on the requested position, playback latency, etc. The written
+     * position will be updated as the actual flush position. All data after actual flush position
+     * flushed. The client can provide data from actual flush position at next write operation or
+     * data callback request. When the stream is flushed, the stream end will be reset. The client
+     * must not write any data before this function returns. Otherwise, the data will be corrupted.
+     * When the method returns successfully and the stream is active, the client must write data
+     * immediately if little audio data remains. Otherwise, the stream will underrun.
+     *
+     *  This was introduced in Android API Level 37.
+     *
+     * @param accuracy the accuracy requirement when flushing. The value must be one of the valid
+     *                 FlushFromAccuracy value.
+     * @param position the start point in frames to flush the stream.
+     * @return a result which the error code indicates if the stream is successfully flush or not
+     *         and value as the successfully flushed position or suggested flushed position.
+     *         Result::OK if the stream is successfully flushed. The value is the actual flushed
+     *         position.
+     *         Result::ErrorUnimplemented if it is not supported by the device. The value is the
+     *         requested position.
+     *         Result::ErrorIllegalArgument if the stream is not an output offload stream or the
+     *         accuracy is not one of valid FlushFromAccuracy values. The value is the requested
+     *         position.
+     *         Result::ErrorOutOfRange if the provided position is negative or is greater than the
+     *         frames written or the stream cannot flush from the requested position and
+     *         FlushFromAccuracy::Accurate is requested. The value is suggested flushed position.
+     *         Result::ErrorDisconnected if the stream is disconnected. The value is the requested
+     *         position.
+     *         Result::ErrorClosed if the stream is closed. The value is the requested position.
+     */
+    virtual ResultWithValue<int64_t> flushFromFrame(
+            FlushFromAccuracy accuracy, int64_t positionInFrames) {
+        return ResultWithValue<int64_t>(Result::ErrorUnimplemented);
+    }
+
 protected:
 
     /**

include/oboe/Definitions.h

@@ -1077,6 +1077,24 @@ namespace oboe {
         Always
     };
 
+    /**
+     * The values are defined to be used for the accuracy requirement when calling
+     * AudioStream.flushFromFrame.
+     */
+    enum class FlushFromAccuracy : int32_t {
+        /**
+         * There is not requirement for frame accuracy when flushing, it is up to the OS
+         * to select a right position to flush from.
+         */
+        Undefined = 0, // AAUDIO_FLUSH_FROM_ACCURACY_UNDEFINED
+
+        /**
+         * The stream must be flushed from the requested position. If it is not possible to flush
+         * from the requested position, the stream must not be flushed.
+         */
+        Accurate = 1, // AAUDIO_FLUSH_FROM_ACCURACY_ACCURATE
+    };
+
     /**
      * On API 16 to 26 OpenSL ES will be used. When using OpenSL ES the optimal values for sampleRate and
      * framesPerBurst are not known by the native code.

include/oboe/ResultWithValue.h

@@ -65,6 +65,10 @@ class ResultWithValue {
             : mValue(value)
             , mError(oboe::Result::OK) {}
 
+    ResultWithValue(T value, oboe::Result error)
+            : mValue(value)
+            , mError(error) {}
+
     /**
      * Get the result.
      *