AudioRingBuffer.h (3775B)
1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-*/ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this file, 4 * You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 #ifndef MOZILLA_AUDIO_RING_BUFFER_H_ 7 #define MOZILLA_AUDIO_RING_BUFFER_H_ 8 9 #include <functional> 10 11 #include "AudioSampleFormat.h" 12 #include "mozilla/Span.h" 13 14 namespace mozilla { 15 16 /** 17 * AudioRingBuffer works with audio sample format float or short. The 18 * implementation wrap around the RingBuffer thus it is not thread-safe. Reads 19 * and writes must happen in the same thread which may be different than the 20 * construction thread. The memory is pre-allocated in the constructor, but may 21 * also be re-allocated on the fly should a larger length be needed. The sample 22 * format has to be specified in order to be used. 23 */ 24 class AudioRingBuffer final { 25 public: 26 explicit AudioRingBuffer(uint32_t aSizeInBytes); 27 ~AudioRingBuffer(); 28 29 /** 30 * Set the sample format to either short or float. The sample format must be 31 * set before the using any other method. 32 */ 33 void SetSampleFormat(AudioSampleFormat aFormat); 34 35 /** 36 * Write `aBuffer.Length()` number of samples when the format is float. 37 */ 38 uint32_t Write(const Span<const float>& aBuffer); 39 40 /** 41 * Write `aBuffer.Length()` number of samples when the format is short. 42 */ 43 uint32_t Write(const Span<const int16_t>& aBuffer); 44 45 /** 46 * Write `aSamples` number of samples from `aBuffer`. Note the `aBuffer` does 47 * not change. 48 */ 49 uint32_t Write(const AudioRingBuffer& aBuffer, uint32_t aSamples); 50 51 /** 52 * Write `aSamples` number of zeros before the beginning of the existing data. 53 */ 54 uint32_t PrependSilence(uint32_t aSamples); 55 56 /** 57 * Write `aSamples` number of zeros. 58 */ 59 uint32_t WriteSilence(uint32_t aSamples); 60 61 /** 62 * Read `aBuffer.Length()` number of samples when the format is float. 63 */ 64 uint32_t Read(const Span<float>& aBuffer); 65 66 /** 67 * Read `aBuffer.Length()` number of samples when the format is short. 68 */ 69 uint32_t Read(const Span<int16_t>& aBuffer); 70 71 /** 72 * Read the internal buffer without extra copies when sample format is float. 73 * Check also the RingBuffer::ReadNoCopy() for more details. 74 */ 75 uint32_t ReadNoCopy( 76 std::function<uint32_t(const Span<const float>&)>&& aCallable); 77 78 /** 79 * Read the internal buffer without extra copies when sample format is short. 80 * Check also the RingBuffer::ReadNoCopy() for more details. 81 */ 82 uint32_t ReadNoCopy( 83 std::function<uint32_t(const Span<const int16_t>&)>&& aCallable); 84 85 /** 86 * Remove `aSamples` number of samples. 87 */ 88 uint32_t Discard(uint32_t aSamples); 89 90 /** 91 * Remove all available samples. 92 */ 93 uint32_t Clear(); 94 95 /** 96 * Increase the ring buffer size if necessary to at least the specified length 97 * in bytes. Must be divisible by the sample size. 98 * Will not deallocate memory if the underlying buffer is large enough. 99 * Returns false if memory allocation is required and fails. 100 */ 101 bool EnsureLengthBytes(uint32_t aLengthBytes); 102 103 /** 104 * Return the number of samples this buffer can hold. 105 */ 106 uint32_t Capacity() const; 107 108 /** 109 * Return true if the buffer is full. 110 */ 111 bool IsFull() const; 112 113 /** 114 * Return true if the buffer is empty. 115 */ 116 bool IsEmpty() const; 117 118 /** 119 * Return the number of samples available for writing. 120 */ 121 uint32_t AvailableWrite() const; 122 123 /** 124 * Return the number of samples available for reading. 125 */ 126 uint32_t AvailableRead() const; 127 128 private: 129 class AudioRingBufferPrivate; 130 UniquePtr<AudioRingBufferPrivate> mPtr; 131 }; 132 133 } // namespace mozilla 134 135 #endif // MOZILLA_AUDIO_RING_BUFFER_H_