gecko-dev/dom/media/AudioRingBuffer.h

/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-*/
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef MOZILLA_AUDIO_RING_BUFFER_H_
#define MOZILLA_AUDIO_RING_BUFFER_H_

#include "AudioSampleFormat.h"
#include "mozilla/Span.h"

#include <functional>

namespace mozilla {

/**
 * AudioRingBuffer works with audio sample format float or short. The
 * implementation wrap around the RingBuffer thus it is not thread-safe. Reads
 * and writes must happen in the same thread which may be different than the
 * construction thread. The memory is pre-allocated in the constructor, but may
 * also be re-allocated on the fly should a larger length be needed. The sample
 * format has to be specified in order to be used.
 */
class AudioRingBuffer final {
 public:
  explicit AudioRingBuffer(uint32_t aSizeInBytes);
  ~AudioRingBuffer();

  /**
   * Set the sample format to either short or float. The sample format must be
   * set before the using any other method.
   */
  void SetSampleFormat(AudioSampleFormat aFormat);

  /**
   * Write `aBuffer.Length()` number of samples when the format is float.
   */
  uint32_t Write(const Span<const float>& aBuffer);

  /**
   * Write `aBuffer.Length()` number of samples when the format is short.
   */
  uint32_t Write(const Span<const int16_t>& aBuffer);

  /**
   * Write `aSamples` number of samples from `aBuffer`. Note the `aBuffer` does
   * not change.
   */
  uint32_t Write(const AudioRingBuffer& aBuffer, uint32_t aSamples);

  /**
   * Write `aSamples` number of zeros before the beginning of the existing data.
   */
  uint32_t PrependSilence(uint32_t aSamples);

  /**
   * Write `aSamples` number of zeros.
   */
  uint32_t WriteSilence(uint32_t aSamples);

  /**
   * Read `aBuffer.Length()` number of samples when the format is float.
   */
  uint32_t Read(const Span<float>& aBuffer);

  /**
   * Read `aBuffer.Length()` number of samples when the format is short.
   */
  uint32_t Read(const Span<int16_t>& aBuffer);

  /**
   * Read the internal buffer without extra copies when sample format is float.
   * Check also the RingBuffer::ReadNoCopy() for more details.
   */
  uint32_t ReadNoCopy(
      std::function<uint32_t(const Span<const float>&)>&& aCallable);

  /**
   * Read the internal buffer without extra copies when sample format is short.
   * Check also the RingBuffer::ReadNoCopy() for more details.
   */
  uint32_t ReadNoCopy(
      std::function<uint32_t(const Span<const int16_t>&)>&& aCallable);

  /**
   * Remove `aSamples` number of samples.
   */
  uint32_t Discard(uint32_t aSamples);

  /**
   * Remove all available samples.
   */
  uint32_t Clear();

  /**
   * Increase the ring buffer size if necessary to at least the specified length
   * in bytes. Must be divisible by the sample size.
   * Will not deallocate memory if the underlying buffer is large enough.
   * Returns false if memory allocation is required and fails.
   */
  bool EnsureLengthBytes(uint32_t aLengthBytes);

  /**
   * Return the number of samples this buffer can hold.
   */
  uint32_t Capacity() const;

  /**
   * Return true if the buffer is full.
   */
  bool IsFull() const;

  /**
   * Return true if the buffer is empty.
   */
  bool IsEmpty() const;

  /**
   * Return the number of samples available for writing.
   */
  uint32_t AvailableWrite() const;

  /**
   * Return the number of samples available for reading.
   */
  uint32_t AvailableRead() const;

 private:
  class AudioRingBufferPrivate;
  UniquePtr<AudioRingBufferPrivate> mPtr;
};

}  // namespace mozilla

#endif  // MOZILLA_AUDIO_RING_BUFFER_H_