Merge branch 'main' of https://github.com/jedlamartin/ReSinc into dev

Author: jedlamartin

README.md

@@ -1,99 +1,145 @@
 # ReSinc
 [![CI](https://github.com/jedlamartin/ReSinc/actions/workflows/ci.yml/badge.svg)](https://github.com/jedlamartin/ReSinc/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-![Language](https://img.shields.io/badge/language-C%2B%2B-blue.svg)
+![Language](https://img.shields.io/badge/language-C%2B%2B17-blue.svg)
 
 `ReSinc` is a lightweight, real-time safe, header-only C++ library for audio oversampling.
 
-It's designed for use in real-time audio applications (like VST/AU plugins) where running a non-linear process (distortion, saturation, etc.) at a higher sample rate is necessary to prevent aliasing artifacts. The library uses a pre-calculated, windowed Sinc filter for interpolation and decimation, ensuring high-fidelity results.
+It is designed for real-time audio applications (like VST/AU plugins) where running non-linear processes (distortion, saturation, compression) at a higher sample rate is necessary to prevent aliasing artifacts. The library uses a pre-calculated, windowed Sinc filter for high-fidelity interpolation and decimation.
 
 ## Features
 
-* **Real-Time Safe:** All memory is pre-allocated on initialization. The real-time processing functions (`interpolate`, `decimate`, `process`) are guaranteed not to allocate heap memory, lock, or block, making them safe for any high-priority audio thread.
-* **High-Quality:** Uses a Kaiser-windowed Sinc filter for "perfect" reconstruction and anti-aliasing.
-* **Simple Workflow:** Provides a clear `interpolate()` -> `process()` -> `decimate()` workflow.
-* **Header-Only:** Just drop `ReSinc.hpp` into your project and include it.
-* **Flexible & Template-Based:** Fully configurable via template parameters:
+* **Real-Time Safe:** All memory is pre-allocated during configuration. The real-time processing functions (`interpolate`, `decimate`, `process`) are guaranteed not to allocate heap memory, lock, or block.
+* **Flexible I/O:** Supports multiple data formats directly:
+    * **Standard Containers:** `std::vector<float>`, `std::vector<std::vector<float>>`, `std::array`.
+    * **JUCE Framework:** Directly accepts `juce::AudioBuffer<float>` / `juce::AudioBuffer<double>`.
+    * **Raw Pointers:** Standard `float**` arrays.
+* **High-Quality:** Uses a Kaiser-windowed Sinc filter for near-perfect reconstruction.
+* **Header-Only:** Single file `ReSinc.hpp`. No linking required.
+* **Configurable:**
     * `TYPE`: Sample type (`float` or `double`).
-    * `OVERSAMPLE_FACTOR`: The factor to oversample by (e.g., `2`, `4`, `8`).
-    * `SINC_RADIUS`: The "quality" of the filter, which also determines latency.
+    * `OVERSAMPLE_FACTOR`: e.g., `2`, `4`, `8`, `16`.
+    * `SINC_RADIUS`: Controls filter steepness and latency.
 
 ---
 
 ## Quick Start
 
-Here is a minimal example of how to use `Oversampler` to apply 4x oversampling to a simple distortion effect.
+Here is a minimal example using `std::vector` to apply 4x oversampling to a simple distortion effect.
 
 ```cpp
 #include "ReSinc.hpp"
 #include <vector>
 #include <cmath>
+#include <algorithm>
 
 // 1. Define your oversampler instance
 //    <float, 4x Oversampling, Sinc Radius of 32>
 Oversampler<float, 4, 32> oversampler;
 
 // 2. Call configure() once before processing begins
-//    (e.g., in your plugin's prepareToPlay())
 void setupAudio() {
     float sampleRate = 44100.0f;
     int maxChannels = 2;
-    int maxBlockSize = 1024;
+    int maxBlockSize = 512;
 
     oversampler.configure(sampleRate, maxChannels, maxBlockSize);
 }
 
-// 3. Run in your real-time audio callback (e.g., processBlock())
-void processAudio(const float* const* input, float* const* output, int numChannels, int numSamples) {
+// 3. Run in your real-time audio loop
+void processBlock(std::vector<std::vector<float>>& input, 
+                  std::vector<std::vector<float>>& output) {
 
-    // 3a. Upsample the audio into the internal buffer
-    oversampler.interpolate(input, numChannels, numSamples);
+    // 3a. Upsample: Input -> Internal Buffer
+    //     (Supports std::vector, juce::AudioBuffer, or float**)
+    oversampler.interpolate(input);
 
-    // 3b. Process the high-resolution internal buffer
-    //     This lambda is called immediately.
-    oversampler.process([&](std::vector<std::vector<float>>& internalBuffer) {
+    // 3b. Process: Operate on the high-resolution buffer
+    //     The callback receives the upsampled data (4x larger size)
+    oversampler.process([&](std::vector<std::vector<float>>& upsampledData) {
         
-        // 'internalBuffer' is now 4x larger
-        int oversampledSamples = numSamples * 4;
-
-        for (int ch = 0; ch < numChannels; ++ch) {
-            for (int s = 0; s < oversampledSamples; ++s) {
-                // Apply a non-linear process (e.g., distortion)
-                // This would alias badly at 1x, but is safe at 4x
-                internalBuffer[ch][s] = std::tanh(internalBuffer[ch][s] * 2.0f);
+        for (auto& channel : upsampledData) {
+            for (auto& sample : channel) {
+                // Apply non-linear process (e.g., Hard Clip)
+                // Safe from aliasing because we are at 4x rate
+                sample = std::max(-1.0f, std::min(1.0f, sample * 1.5f));
             }
         }
     });
 
-    // 3c. Downsample back to the original rate.
-    //     The Sinc filter automatically anti-aliases the signal.
-    oversampler.decimate(output, numChannels, numSamples);
+    // 3c. Downsample: Internal Buffer -> Output
+    //     Automatically applies anti-aliasing filter
+    oversampler.decimate(output);
 }
 ```
 ## API
 
 ### Template Parameters
 `template<typename TYPE, int OVERSAMPLE_FACTOR, int SINC_RADIUS>`
-* **`TYPE`**: The sample type to use, e.g., `float` or `double`.
-* **`OVERSAMPLE_FACTOR`**: The interpolation factor. `4` means 4x oversampling.
-* **`SINC_RADIUS`**: The half-length of the Sinc filter. This controls the filter's quality. A good starting value is `32`. Higher values mean better anti-aliasing but higher CPU cost and latency.
+* **`TYPE`**: The sample type (`float` or `double`).
+* **`OVERSAMPLE_FACTOR`**: Integer factor (e.g., `2`, `4`, `8`).
+* **`SINC_RADIUS`**: Half-length of the Sinc filter. 
+    * Example: `32` taps per side.
+    * Latency = `2 * SINC_RADIUS` samples (at input rate).
 
-### Public Methods
+### Configuration
 
-* **`void configure(TYPE sampleRate, int maxChannels, int maxBlockSize)`**
-    Pre-allocates all internal memory. This **must** be called once from a non-real-time thread before any processing begins.
+#### `void configure(TYPE sampleRate, int maxChannels, int maxBlockSize)`
+Pre-allocates all internal memory. **Must** be called once (from a non-real-time thread) before processing.
 
-* **`void interpolate(const TYPE* const* ptrToBuffers, int numChannels, int numSamples)`**
-    Upsamples a block of audio from `ptrToBuffers` into the internal high-sample-rate buffer.
+### Real-Time Processing
 
-* **`void process(std::function<void(std::vector<std::vector<TYPE>>&)> processBlock)`**
-    Takes a lambda (or other `std::function`) and executes it, giving it direct mutable access to the internal high-sample-rate buffer. This is where you should apply your oversampled processing.
+The `interpolate`, `process`, and `decimate` methods provide overloads for three categories of data:
 
-* **`void decimate(TYPE* const* ptrToBuffers, int numChannels, int numSamples)`**
-    Downsamples the internal high-sample-rate buffer into the provided `ptrToBuffers`, automatically applying the anti-aliasing filter.
+1.  **JUCE Types:** `juce::AudioBuffer<T>`
+2.  **Standard Containers:** `std::vector<T>`, `std::vector<std::vector<T>>`
+3.  **Raw Pointers:** `T**` / `T* const*`
 
-  ---
+#### 1. Interpolate (Input -> Internal)
+Upsamples input data and fills the internal buffer.
 
+```cpp
+// JUCE Support
+void interpolate(const juce::AudioBuffer<TYPE>& buffer);
+
+// STL Support (Multi-channel & Single-channel)
+void interpolate(const std::vector<std::vector<TYPE>>& buffer);
+void interpolate(const std::vector<TYPE>& buffer);
+
+// Raw Pointer Support
+void interpolate(const TYPE* const* ptrToBuffers, int numChannels, int numSamples);
+```
+#### 2. Process (Callback)
+Provides direct access to the upsampled data via a callback/lambda.
+
+```cpp
+// 1. Vector Access (Most Common)
+//    Provides the internal buffer as a vector of vectors
+oversampler.process([](std::vector<std::vector<TYPE>>& data) { ... });
+
+// 2. JUCE Wrapper Access
+//    Wraps the internal pointers in a temporary AudioBuffer for convenience.
+//    (Only enables if passed a JUCE type)
+oversampler.process([](juce::AudioBuffer<TYPE> data) { ... });
+
+// 3. Per-Channel Access
+//    Calls your lambda once for each channel vector
+oversampler.process([](std::vector<TYPE>& channelData) { ... });
+```
+#### 3. Decimate (Internal -> Output)
+Downsamples the internal buffer and writes to the output.
+
+```cpp
+// JUCE Support
+void decimate(juce::AudioBuffer<TYPE>& buffer);
+
+// STL Support
+void decimate(std::vector<std::vector<TYPE>>& buffer);
+void decimate(std::vector<TYPE>& buffer);
+
+// Raw Pointer Support
+void decimate(TYPE* const* ptrToBuffers, int numChannels, int numSamples);
+```
 ## Latency
 
 This library uses a linear-phase (symmetric) Sinc filter. By design, this introduces a known, fixed processing latency.
@@ -127,8 +173,6 @@ The repository includes a `tests/tests.cpp` file for validation. You can compile
 g++ tests/tests.cpp -o run_tests -std=c++17 -O3
 ./run_tests
 ```
----
-
 ## License
 
 This project is licensed under the **MIT License**. See the `LICENSE` file for details.