tor-browser

audio_view.h (11302B)

---

/*
*  Copyright (c) 2024 The WebRTC project authors. All Rights Reserved.
*
*  Use of this source code is governed by a BSD-style license
*  that can be found in the LICENSE file in the root of the source
*  tree. An additional intellectual property rights grant can be found
*  in the file PATENTS.  All contributing project authors may
*  be found in the AUTHORS file in the root of the source tree.
*/

#ifndef API_AUDIO_AUDIO_VIEW_H_
#define API_AUDIO_AUDIO_VIEW_H_

#include <cstddef>
#include <iterator>
#include <variant>
#include <vector>

#include "api/array_view.h"
#include "rtc_base/checks.h"

namespace webrtc {

// This file contains 3 types of view classes:
//
// * MonoView<>: A single channel contiguous buffer of samples.
//
// * InterleavedView<>: Channel samples are interleaved (side-by-side) in
//   the buffer. A single channel InterleavedView<> is the same thing as a
//   MonoView<>
//
// * DeinterleavedView<>: Each channel's samples are contiguous within the
//   buffer. Channels can be enumerated and accessing the individual channel
//   data is done via MonoView<>.
//
// The views are comparable to and built on ArrayView<> but add
// audio specific properties for the dimensions of the buffer and the above
// specialized [de]interleaved support.
//
// There are also a few generic utility functions that can simplify
// generic code for supporting more than one type of view.

// MonoView<> represents a view over a single contiguous, audio buffer. This
// can be either an single channel (mono) interleaved buffer (e.g. AudioFrame),
// or a de-interleaved channel (e.g. from AudioBuffer).
template <typename T>
using MonoView = ArrayView<T>;

// The maximum number of audio channels supported by WebRTC encoders, decoders
// and the AudioFrame class.
// TODO(peah, tommi): Should kMaxNumberOfAudioChannels be 16 rather than 24?
// The reason is that AudioFrame's max number of samples is 7680, which can
// hold 16 10ms 16bit channels at 48 kHz (and not 24 channels).
static constexpr size_t kMaxNumberOfAudioChannels = 24;

// InterleavedView<> is a view over an interleaved audio buffer (e.g. from
// AudioFrame).
template <typename T>
class InterleavedView {
public:
 using value_type = T;

 InterleavedView() = default;

 template <typename U>
 InterleavedView(U* data, size_t samples_per_channel, size_t num_channels)
     : num_channels_(num_channels),
       samples_per_channel_(samples_per_channel),
       data_(data, num_channels * samples_per_channel) {
   RTC_DCHECK_LE(num_channels_, kMaxNumberOfAudioChannels);
   RTC_DCHECK(num_channels_ == 0u || samples_per_channel_ != 0u);
 }

 // Construct an InterleavedView from a C-style array. Samples per channels
 // is calculated based on the array size / num_channels.
 template <typename U, size_t N>
 InterleavedView(U (&array)[N],  // NOLINT
                 size_t num_channels)
     : InterleavedView(array, N / num_channels, num_channels) {
   RTC_DCHECK_EQ(N % num_channels, 0u);
 }

 template <typename U>
 InterleavedView(const InterleavedView<U>& other)
     : num_channels_(other.num_channels()),
       samples_per_channel_(other.samples_per_channel()),
       data_(other.data()) {}

 size_t num_channels() const { return num_channels_; }
 size_t samples_per_channel() const { return samples_per_channel_; }
 ArrayView<T> data() const { return data_; }
 bool empty() const { return data_.empty(); }
 size_t size() const { return data_.size(); }

 MonoView<T> AsMono() const {
   RTC_DCHECK_EQ(num_channels(), 1u);
   RTC_DCHECK_EQ(data_.size(), samples_per_channel_);
   return data_;
 }

 // A simple wrapper around memcpy that includes checks for properties.
 // TODO(tommi): Consider if this can be utility function for both interleaved
 // and deinterleaved views.
 template <typename U>
 void CopyFrom(const InterleavedView<U>& source) {
   static_assert(sizeof(T) == sizeof(U), "");
   RTC_DCHECK_EQ(num_channels(), source.num_channels());
   RTC_DCHECK_EQ(samples_per_channel(), source.samples_per_channel());
   RTC_DCHECK_GE(data_.size(), source.data().size());
   const auto data = source.data();
   memcpy(&data_[0], &data[0], data.size() * sizeof(U));
 }

 T& operator[](size_t idx) const { return data_[idx]; }
 T* begin() const { return data_.begin(); }
 T* end() const { return data_.end(); }
 const T* cbegin() const { return data_.cbegin(); }
 const T* cend() const { return data_.cend(); }
 std::reverse_iterator<T*> rbegin() const { return data_.rbegin(); }
 std::reverse_iterator<T*> rend() const { return data_.rend(); }
 std::reverse_iterator<const T*> crbegin() const { return data_.crbegin(); }
 std::reverse_iterator<const T*> crend() const { return data_.crend(); }

private:
 // TODO(tommi): Consider having these both be stored as uint16_t to
 // save a few bytes per view. Use `dchecked_cast` to support size_t during
 // construction.
 size_t num_channels_ = 0u;
 size_t samples_per_channel_ = 0u;
 ArrayView<T> data_;
};

template <typename T>
class DeinterleavedView {
public:
 using value_type = T;

 DeinterleavedView() = default;

 // Construct a view where all the channels are coallocated in a single buffer.
 template <typename U>
 DeinterleavedView(U* data, size_t samples_per_channel, size_t num_channels)
     : num_channels_(num_channels),
       samples_per_channel_(samples_per_channel),
       data_(data) {}

 // Construct a view from an array of channel pointers where the channels
 // may all be allocated seperately.
 template <typename U>
 DeinterleavedView(U* const* channels,
                   size_t samples_per_channel,
                   size_t num_channels)
     : num_channels_(num_channels),
       samples_per_channel_(samples_per_channel),
       data_(channels) {}

 // Construct a view from an array of channel pointers where the pointers are
 // helt in a `std::vector<>`.
 template <typename U>
 DeinterleavedView(const std::vector<U*>& channels, size_t samples_per_channel)
     : num_channels_(channels.size()),
       samples_per_channel_(samples_per_channel),
       data_(channels.data()) {}

 // Construct a view from another view. Note that the type of
 // the other view may be different from the current type and
 // therefore the internal data types may not be exactly the
 // same, but still compatible.
 // E.g.:
 // DeinterleavedView<float> mutable_view;
 // DeinterleavedView<const float> const_view(mutable_view);
 template <typename U>
 DeinterleavedView(const DeinterleavedView<U>& other)
     : num_channels_(other.num_channels_),
       samples_per_channel_(other.samples_per_channel()) {
   if (other.is_ptr_array()) {
     data_ = std::get<U* const*>(other.data_);
   } else {
     data_ = std::get<U*>(other.data_);
   }
 }

 // Returns a deinterleaved channel where `idx` is the zero based index,
 // in the range [0 .. num_channels()-1].
 MonoView<T> operator[](size_t idx) const {
   RTC_DCHECK_LT(idx, num_channels());
   if (is_ptr_array())
     return MonoView<T>(std::get<T* const*>(data_)[idx], samples_per_channel_);
   return MonoView<T>(&std::get<T*>(data_)[idx * samples_per_channel_],
                      samples_per_channel_);
 }

 size_t num_channels() const { return num_channels_; }
 size_t samples_per_channel() const { return samples_per_channel_; }
 bool empty() const {
   return num_channels_ == 0u || samples_per_channel_ == 0u;
 }
 size_t size() const { return num_channels_ * samples_per_channel_; }

 // Returns the first (and possibly only) channel.
 MonoView<T> AsMono() const {
   RTC_DCHECK_GE(num_channels(), 1u);
   return (*this)[0];
 }

 // Zeros out all samples in channels represented by the view.
 void Clear() {
   for (size_t i = 0u; i < num_channels_; ++i) {
     MonoView<T> view = (*this)[i];
     ClearSamples(view);
   }
 }

private:
 bool is_ptr_array() const { return std::holds_alternative<T* const*>(data_); }

 template <typename U>
 friend class DeinterleavedView;

 size_t num_channels_ = 0u;
 size_t samples_per_channel_ = 0u;
 std::variant<T* const*, T*> data_;
};

template <typename T>
constexpr size_t NumChannels(const MonoView<T>& /* view */) {
 return 1u;
}

template <typename T>
size_t NumChannels(const InterleavedView<T>& view) {
 return view.num_channels();
}

template <typename T>
size_t NumChannels(const DeinterleavedView<T>& view) {
 return view.num_channels();
}

template <typename T>
constexpr bool IsMono(const MonoView<T>& /* view */) {
 return true;
}

template <typename T>
constexpr bool IsInterleavedView(const MonoView<T>& /* view */) {
 return true;
}

template <typename T>
constexpr bool IsInterleavedView(const InterleavedView<T>& /* view */) {
 return true;
}

template <typename T>
constexpr bool IsInterleavedView(const DeinterleavedView<const T>& /* view */) {
 return false;
}

template <typename T>
bool IsMono(const InterleavedView<T>& view) {
 return NumChannels(view) == 1u;
}

template <typename T>
bool IsMono(const DeinterleavedView<T>& view) {
 return NumChannels(view) == 1u;
}

template <typename T>
size_t SamplesPerChannel(const MonoView<T>& view) {
 return view.size();
}

template <typename T>
size_t SamplesPerChannel(const InterleavedView<T>& view) {
 return view.samples_per_channel();
}

template <typename T>
size_t SamplesPerChannel(const DeinterleavedView<T>& view) {
 return view.samples_per_channel();
}
// A simple wrapper around memcpy that includes checks for properties.
// The parameter order is the same as for memcpy(), first destination then
// source.
template <typename D, typename S>
void CopySamples(D& destination, const S& source) {
 static_assert(
     sizeof(typename D::value_type) == sizeof(typename S::value_type), "");
 // Here we'd really like to do
 // static_assert(IsInterleavedView(destination) == IsInterleavedView(source),
 //               "");
 // but the compiler doesn't like it inside this template function for
 // some reason. The following check is an approximation but unfortunately
 // means that copying between a MonoView and single channel interleaved or
 // deinterleaved views wouldn't work.
 // static_assert(sizeof(destination) == sizeof(source),
 //               "Incompatible view types");
 RTC_DCHECK_EQ(NumChannels(destination), NumChannels(source));
 RTC_DCHECK_EQ(SamplesPerChannel(destination), SamplesPerChannel(source));
 RTC_DCHECK_GE(destination.size(), source.size());
 memcpy(&destination[0], &source[0],
        source.size() * sizeof(typename S::value_type));
}

// Sets all the samples in a view to 0. This template function is a simple
// wrapper around `memset()` but adds the benefit of automatically calculating
// the byte size from the number of samples and sample type.
template <typename T>
void ClearSamples(T& view) {
 memset(&view[0], 0, view.size() * sizeof(typename T::value_type));
}

// Same as `ClearSamples()` above but allows for clearing only the first
// `sample_count` number of samples.
template <typename T>
void ClearSamples(T& view, size_t sample_count) {
 RTC_DCHECK_LE(sample_count, view.size());
 memset(&view[0], 0, sample_count * sizeof(typename T::value_type));
}

}  // namespace webrtc

#endif  // API_AUDIO_AUDIO_VIEW_H_