New namespace, constexprs and scoped enums

CMakeLists.txt

@@ -11,25 +11,25 @@ include_directories(
 set (oboe_sources
         include/oboe/LatencyTuner.h
         include/oboe/Definitions.h
-        include/oboe/Stream.h
-        include/oboe/StreamBase.h
-        include/oboe/StreamBuilder.h
-        include/oboe/StreamCallback.h
+        include/oboe/AudioStream.h
+        include/oboe/AudioStreamBase.h
+        include/oboe/AudioStreamBuilder.h
+        include/oboe/AudioStreamCallback.h
         include/oboe/Utilities.h
         src/aaudio/AAudioLoader.cpp
-        src/aaudio/StreamAAudio.cpp
+        src/aaudio/AudioStreamAAudio.cpp
         src/common/AudioClock.h
         src/common/OboeDebug.h
         src/common/LatencyTuner.cpp
-        src/common/Stream.cpp
-        src/common/StreamBuilder.cpp
+        src/common/AudioStream.cpp
+        src/common/AudioStreamBuilder.cpp
         src/common/Utilities.cpp
         src/fifo/FifoBuffer.cpp
         src/fifo/FifoController.cpp
         src/fifo/FifoControllerBase.cpp
         src/fifo/FifoControllerIndirect.cpp
-        src/opensles/StreamBuffered.cpp
-        src/opensles/StreamOpenSLES.cpp
+        src/opensles/AudioStreamBuffered.cpp
+        src/opensles/AudioStreamOpenSLES.cpp
         src/opensles/OpenSLESUtilities.cpp
         )
 

FullGuide.md

@@ -3,7 +3,7 @@ Oboe is a C++ library which makes it easy to build high-performance audio apps o
 
 ## Audio streams
 
-Oboe moves audio data between your app and the audio inputs and outputs on your Android device. Your app passes data in and out by reading from and writing to *audio streams*, represented by the class `Stream`. The read/write calls can be blocking or non-blocking.
+Oboe moves audio data between your app and the audio inputs and outputs on your Android device. Your app passes data in and out by reading from and writing to *audio streams*, represented by the class `AudioStream`. The read/write calls can be blocking or non-blocking.
 
 A stream is defined by the following:
 
@@ -59,11 +59,11 @@ Oboe might perform sample conversion on its own. For example, if an app is writi
 
 ## Creating an audio stream
 
-The Oboe library follows a [builder design pattern](https://en.wikipedia.org/wiki/Builder_pattern) and provides the class `StreamBuilder`.
+The Oboe library follows a [builder design pattern](https://en.wikipedia.org/wiki/Builder_pattern) and provides the class `AudioStreamBuilder`.
 
-  1. Set the audio stream configuration using an StreamBuilder. Use the builder functions that correspond to the stream parameters. These optional set functions are available:
+  1. Set the audio stream configuration using an AudioStreamBuilder. Use the builder functions that correspond to the stream parameters. These optional set functions are available:
 
-    StreamBuilder streamBuilder;
+    AudioStreamBuilder streamBuilder;
 
     streamBuilder.setDeviceId(deviceId);
     streamBuilder.setDirection(direction);
@@ -81,7 +81,7 @@ whether Oboe will use AAudio or OpenSL ES as the audio engine for you app. Oboe
 will automatically select the best implementation available on your device. If
 you want to specifically select AAudio or OpenSL, set the APIIndex yourself.
 After a stream has been opened, you can verify that the API you specified was
-chosen by calling `StreamBuilder::getAPIIndex()`. The allowable indexes are
+chosen by calling `AudioStreamBuilder::getAPIIndex()`. The allowable indexes are
 `AAudio` and `OpenSLES`.
 
 If you do not specify the deviceId, the default is the primary output device.
@@ -92,7 +92,7 @@ it to `kUnspecified`.
 
 To be safe, check the state of the audio stream after you create it, as explained in step 3, below.
 
-  2. After you've configured the StreamBuilder, call `openStream()` to open the stream:
+  2. After you've configured the AudioStreamBuilder, call `openStream()` to open the stream:
 
     Result result = streamBuilder.openStream(&stream_);
     if (result != OK){
@@ -113,7 +113,7 @@ To be safe, check the state of the audio stream after you create it, as explaine
   builder setting:
 
 
-| StreamBuilder set methods | Stream get methods |
+| AudioStreamBuilder set methods | AudioStream get methods |
 | :------------------------ | :----------------- |
 | `setDeviceId()` | `getDeviceId()` |
 | `setDirection()` | `getDirection()` |
@@ -166,7 +166,7 @@ Though it's not shown, you can call `close()` from any state
 
 Oboe doesn't provide callbacks to alert you to state changes. One special
 function,
-`Stream::waitForStateChange()` can be used to wait for a state change.
+`AudioStream::waitForStateChange()` can be used to wait for a state change.
 
 The function does not detect a state change on its own, and does not wait for a
 specific state. It waits until the current state
@@ -194,16 +194,16 @@ stream.
 
 You can use this same technique after calling request start, stop, or flush,
 using the corresponding transient state as the inputState. Do not call
-`waitForStateChange()` after calling `Stream::close()` since the stream
+`waitForStateChange()` after calling `AudioStream::close()` since the stream
 will be deleted as soon as it closes. And do not call `close()`
 while `waitForStateChange()` is running in another thread.
 
 ### Reading and writing to an audio stream
 
 After the stream is started you can read or write to it using the methods
-`Stream::read(buffer, numFrames, timeoutNanos)`
+`AudioStream::read(buffer, numFrames, timeoutNanos)`
 and
-`Stream::write(buffer, numFrames, timeoutNanos)`.
+`AudioStream::write(buffer, numFrames, timeoutNanos)`.
 
 
 For a blocking read or write that transfers the specified number of frames, set timeoutNanos greater than zero. For a non-blocking call, set timeoutNanos to zero. In this case the result is the actual number of frames transferred.
@@ -248,7 +248,7 @@ An audio stream can become disconnected at any time if one of these events happe
 When a stream is disconnected, it has the state "Disconnected" and any attempts to execute write() or other functions return `OBOE_ERROR_DISCONNECTED`.  When a stream is disconnected, all you can do is close it.
 
 If you need to be informed when an audio device is disconnected, write a class
-which extends `StreamCallback` and implements the `onError(stream, error)`
+which extends `AudioStreamCallback` and implements the `onError(stream, error)`
 method. Register your class using `builder.setCallback(yourCallbackClass)`.
 
 The `onError()` method should check the state of the stream as shown in the following
@@ -258,7 +258,7 @@ stream it might have different characteristics than the
 original stream (for example framesPerBurst):
 
 ```
-void PlayAudioEngine::onError(Stream *audioStream, Result error) {
+void PlayAudioEngine::onError(AudioStream *audioStream, Result error) {
     if (error == Result::ErrorDisconnected) {
         // Handle stream restart on a separate thread
         std::function<void(void)> restartStream = std::bind(&PlayAudioEngine::restartStream, this);
@@ -268,7 +268,7 @@ void PlayAudioEngine::onError(Stream *audioStream, Result error) {
 }
 ```
 
-You can also implement two other callback methods in the class `StreamCallback`:
+You can also implement two other callback methods in the class `AudioStreamCallback`:
 
 * `onAudioReady()` is used for a high-priority callback
 * `onExit()` is called when the callback thread exits.
@@ -285,13 +285,13 @@ For applications that require low latency, an audio stream can use an asynchrono
 The callback runs in a high-priority thread that has better performance.
 
 Your code can access the callback mechanism by implementing the virtual class
-`StreamCallback`. The stream periodically executes `onAudioReady()` (the
+`AudioStreamCallback`. The stream periodically executes `onAudioReady()` (the
 callback function) to acquire the data for its next burst.
 
-    class AudioEngine : StreamCallback {
+    class AudioEngine : AudioStreamCallback {
     public:
         DataCallbackResult AudioEngine::onAudioReady(
-                Stream *oboeStream,
+                AudioStream *oboeStream,
                 void *audioData,
                 int32_t numFrames){
             oscillator_->render(static_cast<float *>(audioData), numFrames);
@@ -322,11 +322,11 @@ The callback does a non-blocking read from the input stream placing the data int
 
 (Note that Oboe version 1 does not support input streams, so this example cannot run.)
 
-    class AudioEngine : StreamCallback {
+    class AudioEngine : AudioStreamCallback {
     public:
 
         oboe_data_callback_result_t AudioEngine::onAudioReady(
-                Stream *oboeStream,
+                AudioStream *oboeStream,
                 void *audioData,
                 int32_t numFrames){
                 Result result =
@@ -347,20 +347,20 @@ The callback does a non-blocking read from the input stream placing the data int
             streamBuilder.setCallback(this);
         }
 
-        void setRecordingStream(Stream *stream) {
+        void setRecordingStream(AudioStream *stream) {
           recordingStream = stream;
         }
 
     private:
-        Stream *recordingStream;
+        AudioStream *recordingStream;
     }
 
 
 Note that in this example it is assumed the input and output streams have the same number of channels, format and sample rate. The format of the streams can be mismatched - as long as the code handles the translations properly.
 
 ### Setting performance mode
 
-Every Stream has a *performance mode* which has a large effect on your app's behavior. There are three modes:
+Every AudioStream has a *performance mode* which has a large effect on your app's behavior. There are three modes:
 
 * `PerformanceMode::None` is the default mode. It uses a basic stream that balances latency and power savings.
 * `PerformanceMode::LowLatency` uses smaller buffers and an optimized data path for reduced latency.
@@ -382,12 +382,12 @@ In the current version of Oboe, in order to achieve the lowest possible latency
 MyOboeStreamCallback myCallback;
 
 // Create a stream builder
-StreamBuilder builder;
+AudioStreamBuilder builder;
 builder.setCallback(myCallback);
 builder.setPerformanceMode(PerformanceMode::LowLatency);
 
 // Use it to create the stream
-Stream *stream;
+AudioStream *stream;
 builder.openStream(&stream);
 ```
 
@@ -399,7 +399,7 @@ This is because Oboe avoids using mutexes, which can cause thread preemption and
 
 To be safe, don't call `waitForStateChange()` or read or write to the same stream from two different threads. Similarly, don't close a stream in one thread while reading or writing to it in another thread.
 
-Calls that return stream settings, like `Stream::getSampleRate()` and `Stream::getChannelCount()`, are thread safe.
+Calls that return stream settings, like `AudioStream::getSampleRate()` and `AudioStream::getChannelCount()`, are thread safe.
 
 These calls are also thread safe:
 
@@ -409,7 +409,7 @@ These calls are also thread safe:
 * `convertSharingModeToText()`
 * `convertDataCallbackResultToText()`
 * `convertDirectionToText()`
-* `Stream::get*()` except for `getTimestamp()`
+* `AudioStream::get*()` except for `getTimestamp()`
 
 
 <b>Note:</b> When a stream uses a callback function, it's safe to read/write from the callback thread while also closing the stream

GettingStarted.md

@@ -48,22 +48,22 @@ Include the Oboe header:
 
     #include <oboe/Oboe.h>
 
-Streams are built using an `StreamBuilder`. Create one like this:
+Streams are built using an `AudioStreamBuilder`. Create one like this:
 
-    oboe::StreamBuilder builder;
+    oboe::AudioStreamBuilder builder;
 
 Use the builder's set methods to set properties on the stream (you can read more about these properties in the [full guide](FullGuide.md)):
 
     builder.setDirection(oboe::Direction::Output);
     builder.setPerformanceMode(oboe::PerformanceMode::LowLatency);
     builder.setSharingMode(oboe::SharingMode::Exclusive);
 
-Define an `StreamCallback` class to receive callbacks whenever the stream requires new data.
+Define an `AudioStreamCallback` class to receive callbacks whenever the stream requires new data.
 
-    class MyCallback : public oboe::StreamCallback {
+    class MyCallback : public oboe::AudioStreamCallback {
     public:
         oboe::Result
-        onAudioReady(oboe::Stream *audioStream, void *audioData, int32_t numFrames){
+        onAudioReady(oboe::AudioStream *audioStream, void *audioData, int32_t numFrames){
             generateSineWave(static_cast<float *>(audioData), numFrames);
             return oboe::DataCallbackResult::Continue;
         }
@@ -76,7 +76,7 @@ Supply this callback class to the builder:
 
 Open the stream:
 
-    oboe::Stream *stream;
+    oboe::AudioStream *stream;
     oboe::Result result = builder.openStream(&stream);
 
 Check the result to make sure the stream was opened successfully. Oboe has many convenience methods for converting its types into human-readable strings, they all start with `oboe::convert`:
@@ -87,10 +87,10 @@ Check the result to make sure the stream was opened successfully. Oboe has many
 
 Note that this sample code uses the [logging macros from here](https://github.com/googlesamples/android-audio-high-performance/blob/master/debug-utils/logging_macros.h).
 
-Check the properties of the created stream. The **format** is one property which you should check. The default is `float` on API 21+ and `int16_t` on API 20 or lower. This will dictate the `audioData` type in the `StreamCallback::onAudioReady` callback.
+Check the properties of the created stream. The **format** is one property which you should check. The default is `float` on API 21+ and `int16_t` on API 20 or lower. This will dictate the `audioData` type in the `AudioStreamCallback::onAudioReady` callback.
 
     oboe::AudioFormat format = stream->getFormat();
-    LOGI("Stream format is %s", oboe::convertAudioFormatToText(format));
+    LOGI("AudioStream format is %s", oboe::convertAudioFormatToText(format));
 
 Now start the stream. 
 

build_all_android.sh

@@ -122,8 +122,8 @@ build_oboe mips
 printf "%s\r\n" "example: |" >> ${CDEP_MANIFEST_FILE}
 printf "%s\r\n" "  #include <oboe/Oboe.h>" >> ${CDEP_MANIFEST_FILE}
 printf "%s\r\n" "  void openStream() {" >> ${CDEP_MANIFEST_FILE}
-printf "%s\r\n" "    StreamBuilder builder;" >> ${CDEP_MANIFEST_FILE}
-printf "%s\r\n" "    Stream *stream;" >> ${CDEP_MANIFEST_FILE}
+printf "%s\r\n" "    AudioStreamBuilder builder;" >> ${CDEP_MANIFEST_FILE}
+printf "%s\r\n" "    AudioStream *stream;" >> ${CDEP_MANIFEST_FILE}
 printf "%s\r\n" "    builder.openStream(&stream);" >> ${CDEP_MANIFEST_FILE}
 printf "%s\r\n" "  }" >> ${CDEP_MANIFEST_FILE}
 

include/oboe/Stream.h → include/oboe/AudioStream.h

@@ -20,8 +20,8 @@
 #include <cstdint>
 #include <ctime>
 #include "oboe/Definitions.h"
-#include "oboe/StreamBuilder.h"
-#include "oboe/StreamBase.h"
+#include "oboe/AudioStreamBuilder.h"
+#include "oboe/AudioStreamBase.h"
 
 /** WARNING - UNDER CONSTRUCTION - THIS API WILL CHANGE. */
 
@@ -32,13 +32,13 @@ constexpr int64_t kDefaultTimeoutNanos = (2000 * kNanosPerMillisecond);
 /**
  * Base class for Oboe C++ audio stream.
  */
-class Stream : public StreamBase {
+class AudioStream : public AudioStreamBase {
 public:
 
-    Stream() {}
-    explicit Stream(const StreamBuilder &builder);
+    AudioStream() {}
+    explicit AudioStream(const AudioStreamBuilder &builder);
 
-    virtual ~Stream() = default;
+    virtual ~AudioStream() = default;
 
     /**
      * Open a stream based on the current settings.
@@ -144,7 +144,7 @@ class Stream : public StreamBase {
 
     bool isPlaying();
 
-    std::shared_ptr<StreamCallback> getCallback() const { return mStreamCallback; }
+    std::shared_ptr<AudioStreamCallback> getCallback() const { return mStreamCallback; }
 
     int32_t getBytesPerFrame() const { return mChannelCount * getBytesPerSample(); }
 

include/oboe/StreamBase.h → include/oboe/AudioStreamBase.h

@@ -18,7 +18,7 @@
 #define OBOE_STREAM_BASE_H_
 
 #include <memory>
-#include "oboe/StreamCallback.h"
+#include "oboe/AudioStreamCallback.h"
 #include "oboe/Definitions.h"
 
 namespace oboe {
@@ -31,17 +31,17 @@ namespace oboe {
  * OboeStream will generally return the actual final value, but getFramesPerCallback()
  * can be unspecified even for a stream.
  */
-class StreamBase {
+class AudioStreamBase {
 public:
 
-    StreamBase() {}
+    AudioStreamBase() {}
 
-    virtual ~StreamBase() = default;
+    virtual ~AudioStreamBase() = default;
 
     // This class only contains primitives so we can use default constructor and copy methods.
-    StreamBase(const StreamBase&) = default;
+    AudioStreamBase(const AudioStreamBase&) = default;
 
-    StreamBase& operator=(const StreamBase&) = default;
+    AudioStreamBase& operator=(const AudioStreamBase&) = default;
 
     /**
      * @return number of channels, for example 2 for stereo
@@ -90,12 +90,12 @@ class StreamBase {
 
     int32_t getDeviceId() const { return mDeviceId; }
 
-    std::shared_ptr<StreamCallback> getCallback() const {
+    std::shared_ptr<AudioStreamCallback> getCallback() const {
         return mStreamCallback;
     }
 
 protected:
-    std::shared_ptr<StreamCallback> mStreamCallback;
+    std::shared_ptr<AudioStreamCallback> mStreamCallback;
     int32_t                         mFramesPerCallback = kUnspecified;
     int32_t                         mChannelCount = kUnspecified;
     int32_t                         mSampleRate = kUnspecified;