Docs

Author: jatinchowdhury18

README.md

@@ -0,0 +1,54 @@
+# chowdsp_polyphase_fir
+
+[![Test](https://github.com/Chowdhury-DSP/chowdsp_polyphase_fir/actions/workflows/test.yml/badge.svg)](https://github.com/Chowdhury-DSP/chowdsp_polyphase_fir/actions/workflows/test.yml)
+
+This repository contains a minimal C/C++ library for computing [polyphase FIR filters](https://www.dsprelated.com/blogimages/JosefHoffmann/decim_interp_polyphase.pdf).
+
+## Usage
+
+First, determine your memory requirements:
+```cpp
+const auto persistent_bytes = persistent_bytes_required (n_channels, n_taps, interpolation_factor, max_block_size, alignment);
+const auto scratch_bytes = scratch_bytes_required (n_taps, interpolation_factor, max_block_size, alignment);
+```
+
+Next, you can create a "state" object:
+```cpp
+auto* state = init (n_channels,
+                    n_taps,
+                    interpolation_factor,
+                    max_block_size,
+                    allocate_bytes (persistent_bytes, alignment),
+                    alignment);
+```
+
+And load in our filter coefficients:
+```cpp
+load_coeffs (state, coeffs, n_taps);
+```
+
+Now we're ready to do our processing! We can do polyphase interpolation:
+```cpp
+process_interpolate (state,
+                     input_buffer,
+                     output_buffer,
+                     n_channels,
+                     n_samples,
+                     scratch_data,
+                     use_avx);
+```
+
+Or decimation:
+```cpp
+process_decimate (state,
+                  input_buffer,
+                  output_buffer,
+                  n_channels,
+                  n_samples,
+                  scratch_data,
+                  use_avx);
+```
+
+## License
+
+This code is licensed under the BSD 3-clause license. Enjoy!

chowdsp_polyphase_fir.h

@@ -10,6 +10,12 @@ namespace chowdsp::polyphase_fir
 #include <stddef.h>
 #endif
 
+/**
+ * Object to hold the filter's persistent state.
+ *
+ * Users should not instantiate this object directly,
+ * it will be provided by the `init()` method.
+ */
 struct Polyphase_FIR_State
 {
     float* coeffs {};
@@ -21,16 +27,33 @@ struct Polyphase_FIR_State
     int factor {};
 };
 
+/** Returns the number of bytes needed to construct the filter state. */
 size_t persistent_bytes_required (int n_channels, int n_taps, int factor, int max_samples_in, int alignment);
 
+/*
+ * Initializes the filter and returns a state object.
+ *
+ * Note that the number of taps must be greater than or equal to 16.
+ *
+ * The `max_samples_in` argument is relative to the "interpolation" mode of the filter.
+ * For "decimation", the naximum input size if `max_samples_in * factor`.
+ *
+ * The returned pointer will be allocated into the provided block of persistent data.
+ * This means that you should not free the pointer since it will be freed automatically
+ * when you free the persistent data.
+ */
 struct Polyphase_FIR_State* init (int n_channels, int n_taps, int factor, int max_samples_in, void* persistent_data, int alignment);
 
+/** Loads a set of filter coefficients into the filter */
 void load_coeffs (struct Polyphase_FIR_State* state, const float* coeffs, int n_taps);
 
+/** Resets the filter state */
 void reset (struct Polyphase_FIR_State* state);
 
+/** Returns the scratch memory required by the filter */
 size_t scratch_bytes_required (int n_taps, int factor, int max_samples_in, int alignment);
 
+/** Process data through the "interpolation" mode of the filter */
 void process_interpolate (struct Polyphase_FIR_State* state,
                           const float* const* in,
                           float* const* out,
@@ -39,6 +62,7 @@ void process_interpolate (struct Polyphase_FIR_State* state,
                           void* scratch_data,
                           bool use_avx);
 
+/** Process data through the "decimation" mode of the filter */
 void process_decimate (struct Polyphase_FIR_State* state,
                        const float* const* in,
                        float* const* out,