Audiospan documentation

sfizz/AudioSpan.h

@@ -34,6 +34,58 @@
 
 namespace sfz
 {
+/**
+ * @brief Extension of the concept of spans to multiple channels.
+ * 
+ * A span (and by extension an audiospan) is at its core a structure
+ * containing a pointer and a size to a buffer that is owned by another
+ * object. A span is thus a view into a buffer that is cheap to copy and
+ * pass around, and safe as long as the underlying buffer is allocated.
+ * The goal of the class is to reduce interfaces and usage annoyance for 
+ * codebases. Obviously, this requires that most functions use AudioSpans.
+ * It also protects against overreading a buffer. Users can still indicate
+ * that they 
+ * @code{.cpp}
+ * constexpr int bufferSize { 1024 };
+ * void gain(AudioSpan<float, 2> arrayView, float gain)
+ * {
+ *      for (auto& f: arrayView)
+ *          f *= gain;
+ * }
+ * 
+ * int main(char argc, char** argv)
+ * {
+ *      float leftChannel [bufferSize];
+ *      float rightChannel [bufferSize];
+ * 
+ *      for (int i = 0; i < bufferSize; ++i)
+ *      {
+ *          leftChannel[i] = 1.0f;
+ *          rightChannel[i] = 1.0f;
+ *      }
+ * 
+ *      // Type is inferred
+ *      AudioSpan explicitView { { leftChannel, rightChannel }, bufferSize };
+ *      // Size will be taken as the minimum size of all the spans given
+ *      // for all types that can be automatically cast to absl::Span or std::span
+ *      AudioSpan explicitView2 { { leftChannel, rightChannel } };
+ * 
+ *      gain(explicitView, 0.5f); // the array elements are now equal to 0.5f
+ *      gain(explicitView2, 0.5f); // the array elements are now equal to 0.25f
+ * 
+ *      // You can also build spans implicitely
+ *      gain({ { leftChannel, rightChannel }, bufferSize }, 0.5f); // elements equal to 0.125f
+ * }
+ * @endcode
+ * You can build AudioSpans from AudioBuffers directly, the AudioBufferT.cpp file in the test
+ * folder show some example.
+ *  As with many things templated in C++ the `Type` can be`const` or `volatile`, and `const float` 
+ * is not the same type as `float`. You thus cannot build an `AudioSpan<float>` from 
+ * a `const float *` buffer for example.
+ * 
+ * @tparam Type the underlying buffer type
+ * @tparam MaxChannels the maximum number of channels. Defaults to sfz::config::numChannels 
+ */
 template <class Type, unsigned int MaxChannels = sfz::config::numChannels>
 class AudioSpan {
 public:
@@ -42,8 +94,16 @@ public:
     {
     }
 
-    AudioSpan(const std::array<Type*, MaxChannels>& spans, int numChannels, size_type offset, size_type size)
+    /**
-        : numFrames(size)
+     * @brief Construct a new Audio Span object
+     * 
+     * @param spans an array of MaxChannels pointers to buffers.
+     * @param numChannels the number of spans to take in from the array
+     * @param offset starting offset for the AudioSpan
+     * @param numFrames size of the AudioSpan
+     */
+    AudioSpan(const std::array<Type*, MaxChannels>& spans, int numChannels, size_type offset, size_type numFrames)
+        : numFrames(numFrames)
         , numChannels(numChannels)
     {
         ASSERT(static_cast<unsigned int>(numChannels) <= MaxChannels);
@@ -51,6 +111,12 @@ public:
             this->spans[i] = spans[i] + offset;
     }
 
+    /**
+     * @brief Construct a new Audio Span object from initializer lists
+     * 
+     * @param spans the list of span
+     * @param numFrames the size of the audio span
+     */
     AudioSpan(std::initializer_list<Type*> spans, size_type numFrames)
         : numFrames(numFrames)
         , numChannels(spans.size())
@@ -65,6 +131,15 @@ public:
         }
     }
 
+    /**
+     * @brief Construct a new Audio Span object from a list of absl::Span<Type>
+     * 
+     * This constructor can be implicitely called for any source that can be cast transparently to
+     * an absl::Span<Type>. The size of the AudioSpan is inferred from the size of the smallest 
+     * absl::Span<Type>.
+     * 
+     * @param spans a list of objects compatible with absl::Span<Type>
+     */
     AudioSpan(std::initializer_list<absl::Span<Type>> spans)
         : numChannels(spans.size())
     {
@@ -78,6 +153,17 @@ public:
         }
     }
 
+    /**
+     * @brief Construct a new Audio Span object from an AudioBuffer with a const Type.
+     * 
+     * This constructor can be implicitely called for any source that can be cast transparently to
+     * an AudioBuffer<const Type>.
+     * 
+     * @tparam U the underlying type compatible with the template Type of the AudioSpan
+     * @tparam N the number of channels in the AudioBuffer
+     * @tparam Alignment the alignment block size for the platform
+     * @param audioBuffer the source AudioBuffer.
+     */
     template <class U, unsigned int N, unsigned int Alignment, typename = std::enable_if<N <= MaxChannels>, typename = std::enable_if_t<std::is_const<U>::value, int>>
     AudioSpan(AudioBuffer<U, N, Alignment>& audioBuffer)
         : numFrames(audioBuffer.getNumFrames())
@@ -87,6 +173,18 @@ public:
             this->spans[i] = audioBuffer.channelReader(i);
         }
     }
+
+    /**
+     * @brief Construct a new Audio Span object from an AudioBuffer with a non-const Type.
+     * 
+     * This constructor can be implicitely called for any source that can be cast transparently to
+     * an AudioBuffer<Type>.
+     * 
+     * @tparam U the underlying type compatible with the template Type of the AudioSpan
+     * @tparam N the number of channels in the AudioBuffer
+     * @tparam Alignment the alignment block size for the platform
+     * @param audioBuffer the source AudioBuffer.
+     */
     template <class U, unsigned int N, unsigned int Alignment, typename = std::enable_if<N <= MaxChannels>>
     AudioSpan(AudioBuffer<U, N, Alignment>& audioBuffer)
         : numFrames(audioBuffer.getNumFrames())
@@ -96,6 +194,12 @@ public:
             this->spans[i] = audioBuffer.channelWriter(i);
         }
     }
+
+    /**
+     * @brief AudioSpan copy constructor
+     * 
+     * @param other the other AudioSpan
+     */
     template <class U, unsigned int N, typename = std::enable_if<N <= MaxChannels>>
     AudioSpan(const AudioSpan<U, N>& other)
         : numFrames(other.getNumFrames())
@@ -106,6 +210,12 @@ public:
         }
     }
 
+    /**
+     * @brief Get a raw pointer to a specific channel from the AudioSpan
+     * 
+     * @param channelIndex the channel
+     * @return Type* the raw pointer to the channel
+     */
     Type* getChannel(int channelIndex)
     {
         ASSERT(channelIndex < numChannels);
@@ -115,6 +225,12 @@ public:
         return {};
     }
 
+    /**
+     * @brief Get a Span<Type> corresponding to a specific channel
+     * 
+     * @param channelIndex the channel
+     * @return absl::Span<Type> 
+     */
     absl::Span<Type> getSpan(int channelIndex)
     {
         ASSERT(channelIndex < numChannels);
@@ -124,6 +240,12 @@ public:
         return {};
     }
 
+    /**
+     * @brief Get a Span<const Type> corresponding to a specific channel
+     * 
+     * @param channelIndex the channel
+     * @return absl::Span<const Type> 
+     */
     absl::Span<const Type> getConstSpan(int channelIndex)
     {
         ASSERT(channelIndex < numChannels);
@@ -133,6 +255,11 @@ public:
         return {};
     }
 
+    /**
+     * @brief Get the mean of the squared values of the AudioSpan elements on all channels. 
+     * 
+     * @return Type
+     */
     Type meanSquared() noexcept
     {
         if (numChannels == 0)
@@ -143,27 +270,52 @@ public:
         return result / numChannels;
     }
 
+    /**
+     * @brief Fills all the elements of the AudioSpan with the same value
+     * 
+     * @param value the filling value
+     */
     void fill(Type value) noexcept
     {
+        static_assert(!std::is_const_v<Type>, "Can't allow mutating operations on const AudioSpans");
         for (int i = 0; i < numChannels; ++i)
             sfz::fill<Type>(getSpan(i), value);
     }
 
+    /**
+     * @brief Apply a gain span elementwise to all channels in the AudioSpan.
+     * 
+     * @param gain the gain to apply
+     */
     void applyGain(absl::Span<const Type> gain) noexcept
     {
+        static_assert(!std::is_const_v<Type>, "Can't allow mutating operations on const AudioSpans");
         for (int i = 0; i < numChannels; ++i)
             sfz::applyGain<Type>(gain, getSpan(i));
     }
 
+    /**
+     * @brief Apply a gain to all channels in the AudioSpan.
+     * 
+     * @param gain the gain to apply
+     */
     void applyGain(Type gain) noexcept
     {
+        static_assert(!std::is_const_v<Type>, "Can't allow mutating operations on const AudioSpans");
         for (int i = 0; i < numChannels; ++i)
             sfz::applyGain<Type>(gain, getSpan(i));
     }
 
+    /**
+     * @brief Add another AudioSpan with a compatible number of channels to the current
+     * AudioSpan.
+     * 
+     * @param other the other AudioSpan
+     */
     template <class U, unsigned int N, typename = std::enable_if<N <= MaxChannels>>
     void add(AudioSpan<U, N>& other)
     {
+        static_assert(!std::is_const_v<Type>, "Can't allow mutating operations on const AudioSpans");
         ASSERT(other.getNumChannels() == numChannels);
         if (other.getNumChannels() == numChannels) {
             for (int i = 0; i < numChannels; ++i)
@@ -171,9 +323,16 @@ public:
         }
     }
 
+    /**
+     * @brief Copy the elements of another AudioSpan with a compatible number of channels 
+     * to the current AudioSpan.
+     * 
+     * @param other the other AudioSpan
+     */
     template <class U, unsigned int N, typename = std::enable_if<N <= MaxChannels>>
     void copy(AudioSpan<U, N>& other)
     {
+        static_assert(!std::is_const_v<Type>, "Can't allow mutating operations on const AudioSpans");
         ASSERT(other.getNumChannels() == numChannels);
         if (other.getNumChannels() == numChannels) {
             for (int i = 0; i < numChannels; ++i)
@@ -181,34 +340,69 @@ public:
         }
     }
 
+    /**
+     * @brief Get the size of this AudioSpan.
+     * 
+     * @returns size_type the number of frames in the AudioSpan
+     */
     size_type getNumFrames()
     {
         return numFrames;
     }
 
+    /**
+     * @brief Get the number of channels of this AudioSpan.
+     * 
+     * @returns size_type the number of channels in the AudioSpan
+     */
     int getNumChannels()
     {
         return numChannels;
     }
-
+    
+    /**
+     * @brief Creates a new AudioSpan but with only the `length` first elements of each channel.
+     * 
+     * @param length the number of elements to take on each channel
+     */
     AudioSpan<Type> first(size_type length)
     {
         ASSERT(length <= numFrames);
         return { spans, numChannels, 0, length };
     }
 
+    /**
+     * @brief Creates a new AudioSpan but with only the `length` last elements of each channel.
+     * 
+     * @param length the number of elements to take on each channel
+     */
     AudioSpan<Type> last(size_type length)
     {
         ASSERT(length <= numFrames);
         return { spans, numChannels, numFrames - length, length };
     }
 
+    /**
+     * @brief Creates a new AudioSpan starting at an offset `offset` on each channel and
+     * taking `length` elements. The new AudioSpan will have `length` elements. This basically
+     * removes the first `offset` elements and the last `numFrames - length - offset` elements
+     *  from the AudioSpan.
+     * 
+     * @param length the number of elements to take on each channel
+     */
     AudioSpan<Type> subspan(size_type offset, size_type length)
     {
         ASSERT(length + offset <= numFrames);
         return { spans, numChannels, offset, length };
     }
 
+    /**
+     * @brief Creates a new AudioSpan starting at an offset `offset` on each channel and
+     * taking all the remaining elements. This function basically removes the first `offset`
+     * elements from the AudioSpan. The new Audiospan will have size `numFrames - offset`.
+     * 
+     * @param length the number of elements to take on each channel
+     */
     AudioSpan<Type> subspan(size_type offset)
     {
         ASSERT(offset <= numFrames);