Oboe  1.2
A library for creating real-time audio apps on Android
AudioStream.h
1 /*
2  * Copyright 2016 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef OBOE_STREAM_H_
18 #define OBOE_STREAM_H_
19 
20 #include <atomic>
21 #include <cstdint>
22 #include <ctime>
23 #include <mutex>
24 #include "oboe/Definitions.h"
25 #include "oboe/ResultWithValue.h"
26 #include "oboe/AudioStreamBuilder.h"
27 #include "oboe/AudioStreamBase.h"
28 
31 namespace oboe {
32 
39 constexpr int64_t kDefaultTimeoutNanos = (2000 * kNanosPerMillisecond);
40 
44 class AudioStream : public AudioStreamBase {
45 public:
46 
47  AudioStream() {}
48 
54  explicit AudioStream(const AudioStreamBuilder &builder);
55 
56  virtual ~AudioStream() = default;
57 
66  virtual Result open() {
67  return Result::OK; // Called by subclasses. Might do more in the future.
68  }
69 
73  virtual Result close();
74 
79  virtual Result start(int64_t timeoutNanoseconds = kDefaultTimeoutNanos);
80 
85  virtual Result pause(int64_t timeoutNanoseconds = kDefaultTimeoutNanos);
86 
91  virtual Result flush(int64_t timeoutNanoseconds = kDefaultTimeoutNanos);
92 
97  virtual Result stop(int64_t timeoutNanoseconds = kDefaultTimeoutNanos);
98 
99  /* Asynchronous requests.
100  * Use waitForStateChange() if you need to wait for completion.
101  */
102 
107  virtual Result requestStart() = 0;
108 
113  virtual Result requestPause() = 0;
114 
119  virtual Result requestFlush() = 0;
120 
125  virtual Result requestStop() = 0;
126 
132  virtual StreamState getState() const = 0;
133 
161  virtual Result waitForStateChange(StreamState inputState,
162  StreamState *nextState,
163  int64_t timeoutNanoseconds) = 0;
164 
177  virtual ResultWithValue<int32_t> setBufferSizeInFrames(int32_t /* requestedFrames */) {
178  return Result::ErrorUnimplemented;
179  }
180 
194  return ResultWithValue<int32_t>(Result::ErrorUnimplemented);
195  }
196 
200  virtual bool isXRunCountSupported() const = 0;
201 
207  virtual int32_t getFramesPerBurst() = 0;
208 
216  int32_t getBytesPerFrame() const { return mChannelCount * getBytesPerSample(); }
217 
224  int32_t getBytesPerSample() const;
225 
232  virtual int64_t getFramesWritten();
233 
240  virtual int64_t getFramesRead();
241 
266  return ResultWithValue<double>(Result::ErrorUnimplemented);
267  }
268 
286  virtual Result getTimestamp(clockid_t /* clockId */,
287  int64_t* /* framePosition */,
288  int64_t* /* timeNanoseconds */) {
289  return Result::ErrorUnimplemented;
290  }
291 
307  virtual ResultWithValue<FrameTimestamp> getTimestamp(clockid_t /* clockId */);
308 
309  // ============== I/O ===========================
322  virtual ResultWithValue<int32_t> write(const void* /* buffer */,
323  int32_t /* numFrames */,
324  int64_t /* timeoutNanoseconds */ ) {
325  return ResultWithValue<int32_t>(Result::ErrorUnimplemented);
326  }
327 
340  virtual ResultWithValue<int32_t> read(void* /* buffer */,
341  int32_t /* numFrames */,
342  int64_t /* timeoutNanoseconds */) {
343  return ResultWithValue<int32_t>(Result::ErrorUnimplemented);
344  }
345 
351  virtual AudioApi getAudioApi() const = 0;
352 
358  bool usesAAudio() const {
359  return getAudioApi() == AudioApi::AAudio;
360  }
361 
370  virtual void *getUnderlyingStream() const {
371  return nullptr;
372  }
373 
377  void launchStopThread();
378 
383  virtual void updateFramesWritten() = 0;
384 
389  virtual void updateFramesRead() = 0;
390 
391  /*
392  * Swap old callback for new callback.
393  * This not atomic.
394  * This should only be used internally.
395  * @param streamCallback
396  * @return previous streamCallback
397  */
398  AudioStreamCallback *swapCallback(AudioStreamCallback *streamCallback) {
399  AudioStreamCallback *previousCallback = mStreamCallback;
400  mStreamCallback = streamCallback;
401  return previousCallback;
402  }
403 
407  ResultWithValue<int32_t> getAvailableFrames();
408 
418  ResultWithValue<int32_t> waitForAvailableFrames(int32_t numFrames,
419  int64_t timeoutNanoseconds);
420 
421 protected:
422 
433  return mErrorCallbackCalled.exchange(true);
434  }
435 
442  virtual Result waitForStateTransition(StreamState startingState,
443  StreamState endingState,
444  int64_t timeoutNanoseconds);
445 
453  virtual DataCallbackResult onDefaultCallback(void* /* audioData */, int /* numFrames */) {
454  return DataCallbackResult::Stop;
455  }
456 
465  DataCallbackResult fireDataCallback(void *audioData, int numFrames);
466 
471  return mDataCallbackEnabled;
472  }
473 
478  void setDataCallbackEnabled(bool enabled) {
479  mDataCallbackEnabled = enabled;
480  }
481 
488  std::atomic<int64_t> mFramesWritten{};
489 
496  std::atomic<int64_t> mFramesRead{};
497 
498  std::mutex mLock; // for synchronizing start/stop/close
499 
500 private:
501  int mPreviousScheduler = -1;
502 
503  std::atomic<bool> mDataCallbackEnabled{false};
504  std::atomic<bool> mErrorCallbackCalled{false};
505 
506 
507 };
508 
514  void operator()(AudioStream *audioStream) {
515  if (audioStream) {
516  audioStream->close();
517  }
518  delete audioStream;
519  }
520  };
521 } // namespace oboe
522 
523 #endif /* OBOE_STREAM_H_ */
virtual DataCallbackResult onDefaultCallback(void *, int)
Definition: AudioStream.h:453
virtual Result stop(int64_t timeoutNanoseconds=kDefaultTimeoutNanos)
Definition: AudioStreamBuilder.h:31
ResultWithValue< int32_t > getAvailableFrames()
void setDataCallbackEnabled(bool enabled)
Definition: AudioStream.h:478
bool usesAAudio() const
Definition: AudioStream.h:358
virtual Result flush(int64_t timeoutNanoseconds=kDefaultTimeoutNanos)
int32_t getBytesPerFrame() const
Definition: AudioStream.h:216
virtual Result start(int64_t timeoutNanoseconds=kDefaultTimeoutNanos)
constexpr int64_t kDefaultTimeoutNanos
Definition: AudioStream.h:39
virtual ResultWithValue< int32_t > getXRunCount() const
Definition: AudioStream.h:193
std::atomic< int64_t > mFramesWritten
Definition: AudioStream.h:488
DataCallbackResult fireDataCallback(void *audioData, int numFrames)
virtual void * getUnderlyingStream() const
Definition: AudioStream.h:370
virtual void updateFramesWritten()=0
virtual int64_t getFramesWritten()
ResultWithValue< int32_t > waitForAvailableFrames(int32_t numFrames, int64_t timeoutNanoseconds)
Definition: AudioStreamCallback.h:33
int32_t mChannelCount
Definition: AudioStreamBase.h:156
DataCallbackResult
Definition: Definitions.h:119
AudioApi
Definition: Definitions.h:213
virtual Result waitForStateTransition(StreamState startingState, StreamState endingState, int64_t timeoutNanoseconds)
virtual int32_t getFramesPerBurst()=0
virtual Result close()
virtual ResultWithValue< int32_t > setBufferSizeInFrames(int32_t)
Definition: AudioStream.h:177
virtual ResultWithValue< double > calculateLatencyMillis()
Definition: AudioStream.h:265
virtual Result getTimestamp(clockid_t, int64_t *, int64_t *)
Definition: AudioStream.h:286
virtual Result open()
Definition: AudioStream.h:66
virtual int64_t getFramesRead()
Definition: AudioStream.h:44
bool isDataCallbackEnabled()
Definition: AudioStream.h:470
virtual ResultWithValue< int32_t > read(void *, int32_t, int64_t)
Definition: AudioStream.h:340
virtual Result requestPause()=0
virtual ResultWithValue< int32_t > write(const void *, int32_t, int64_t)
Definition: AudioStream.h:322
std::atomic< int64_t > mFramesRead
Definition: AudioStream.h:496
Definition: AudioStreamBase.h:29
constexpr int64_t kNanosPerMillisecond
Definition: Definitions.h:43
virtual Result requestStop()=0
virtual AudioApi getAudioApi() const =0
virtual Result waitForStateChange(StreamState inputState, StreamState *nextState, int64_t timeoutNanoseconds)=0
Result
Definition: Definitions.h:131
Definition: AudioStream.h:513
Definition: AudioStream.h:31
bool wasErrorCallbackCalled()
Definition: AudioStream.h:432
virtual bool isXRunCountSupported() const =0
AudioStreamCallback * mStreamCallback
Definition: AudioStreamBase.h:152
virtual Result requestStart()=0
StreamState
Definition: Definitions.h:58
virtual StreamState getState() const =0
virtual Result pause(int64_t timeoutNanoseconds=kDefaultTimeoutNanos)
virtual Result requestFlush()=0
virtual void updateFramesRead()=0
int32_t getBytesPerSample() const
Definition: ResultWithValue.h:47