dom/media/AudioRingBuffer.h

   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 "AudioSampleFormat.h"
  10 #include "mozilla/Span.h"
  11
  12 #include <functional>
  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_