Merge pull request #132 from HEnquist/capability-traits

Split Resampler into capability traits Adjustable and Resizable

Author: HEnquist

README.md

@@ -273,8 +273,9 @@ RUST_LOG=trace cargo test --features log
 ## Example
 
 Resample a dummy audio file from 44100 to 48000 Hz.
+This uses the `Fft` resampler, which requires the `fft_resampler` feature (enabled by default).
 See also the "process_f64" example that can be used to process a file from disk.
-```rust
+```rust,ignore
 use rubato::{
     Resampler, Fft, FixedSync, Indexing
 };
@@ -408,6 +409,28 @@ let r = Fft::<f64>::new_custom(rate_in, rate_out, chunk_size, sub_chunks, channe
     WindowFunction::BlackmanHarris2, fixed)?;
 ```
 
+**Ratio and chunk-size changes moved to capability traits.** `set_resample_ratio`,
+`set_resample_ratio_relative` are now on the `Adjustable` trait, and `set_chunk_size` is on
+`Resizable`. On a concrete resampler, just bring the trait into scope. On a `dyn Resampler`,
+recover the capability with `as_adjustable()` / `as_resizable()` (this replaces the old
+`SyncNotAdjustable` / `ChunkSizeNotAdjustable` errors, which are removed). To query the
+capability through a shared `&dyn Resampler`, use `is_adjustable()` / `is_resizable()`.
+
+```rust,ignore
+// before: on a Box<dyn Resampler>, with a runtime error for synchronous resamplers
+resampler.set_resample_ratio(new_ratio, true)?;
+// after: None means "synchronous, nothing to adjust"
+if let Some(adjustable) = resampler.as_adjustable() {
+    adjustable.set_resample_ratio(new_ratio, true)?;
+}
+
+// before: on a concrete Async resampler
+async_resampler.set_resample_ratio_relative(0.95, true)?;
+// after: same call, but the Adjustable trait must be in scope
+use rubato::Adjustable;
+async_resampler.set_resample_ratio_relative(0.95, true)?;
+```
+
 **The error enums are now `#[non_exhaustive]`.** If you `match` on `ResampleError` or
 `ResamplerConstructionError`, add a `_ => ...` arm.
 
@@ -440,6 +463,12 @@ let r = Fft::<f64>::new_custom(rate_in, rate_out, chunk_size, sub_chunks, channe
     `SincInterpolationType`, `PolynomialDegree`, `FixedSync` and `FixedAsync`.
   - Return `WrongNumberOfMaskChannels` instead of panicking when the
     `active_channels_mask` passed to a process method has the wrong length.
+  - Split the capability-specific methods out of `Resampler` into the `Adjustable` trait
+    (`set_resample_ratio`, `set_resample_ratio_relative`) and the `Resizable` trait
+    (`set_chunk_size`). `Resampler` gains `as_adjustable()` and `as_resizable()` to recover
+    these capabilities from a trait object, and `is_adjustable()` / `is_resizable()` to query
+    them through a shared reference. The `SyncNotAdjustable` and `ChunkSizeNotAdjustable`
+    error variants are removed, since calling these methods is now a compile-time capability.
 - v3.0.0
   - Use separate lifetimes for `buffer_in` and `buffer_out` in `process_into_buffer`.
   - Improve sinc resampler performance with smarter dot product calculation.

examples/fixedout_ramp64.rs

@@ -1,8 +1,8 @@
 extern crate rubato;
 use audioadapter_buffers::direct::InterleavedSlice;
 use rubato::{
-    Async, FixedAsync, Indexing, Resampler, SincInterpolationParameters, SincInterpolationType,
-    WindowFunction,
+    Adjustable, Async, FixedAsync, Indexing, Resampler, SincInterpolationParameters,
+    SincInterpolationType, WindowFunction,
 };
 use std::convert::TryInto;
 use std::env;

examples/polyfixedin_ramp64.rs

@@ -1,6 +1,6 @@
 extern crate rubato;
 use audioadapter_buffers::direct::InterleavedSlice;
-use rubato::{Async, FixedAsync, Indexing, PolynomialDegree, Resampler};
+use rubato::{Adjustable, Async, FixedAsync, Indexing, PolynomialDegree, Resampler};
 use std::convert::TryInto;
 use std::env;
 use std::fs::File;

src/asynchro.rs

@@ -11,7 +11,7 @@ use crate::sinc_interpolator::{
     AnyInterpolator, AvxSample, NeonSample, SincInterpolator, SseSample,
 };
 use crate::{get_offsets, get_partial_len, update_mask, Indexing};
-use crate::{validate_buffers, Resampler, Sample};
+use crate::{validate_buffers, Adjustable, Resampler, Resizable, Sample};
 
 /// An enum for specifying which side of an asynchronous resampler should be fixed size.
 /// This is similar to [FixedSync](crate::FixedSync) that is used for the synchronous resamplers.
@@ -55,8 +55,8 @@ pub trait InnerResampler<T>: Send {
 /// and when output size is fixed, the input size varies.
 ///
 /// The number of frames on the fixed side is determined by the chunk size argument to the constructor.
-/// This value can be changed by the `set_chunk_size()` method,
-/// to let the resampler process smaller chunks of audio data.
+/// This value can be changed by the [set_chunk_size](Resizable::set_chunk_size) method of the
+/// [Resizable] trait (which must be in scope), to let the resampler process smaller chunks of audio data.
 /// Note that the chunk size cannot exceed the value given at creation time.
 ///
 /// When the input size is fixed, the maximum value can be retrieved using the `input_size_max()` method,
@@ -155,7 +155,7 @@ where
     ///
     /// Parameters are:
     /// - `resample_ratio`: Starting ratio between output and input sample rates, must be > 0.
-    /// - `max_resample_ratio_relative`: Maximum ratio that can be set with [Resampler::set_resample_ratio] relative to `resample_ratio`, must be >= 1.0. The minimum relative ratio is the reciprocal of the maximum. For example, with `max_resample_ratio_relative` of 10.0, the ratio can be set between `resample_ratio * 10.0` and `resample_ratio / 10.0`.
+    /// - `max_resample_ratio_relative`: Maximum ratio that can be set with [Adjustable::set_resample_ratio](crate::Adjustable::set_resample_ratio) relative to `resample_ratio`, must be >= 1.0. The minimum relative ratio is the reciprocal of the maximum. For example, with `max_resample_ratio_relative` of 10.0, the ratio can be set between `resample_ratio * 10.0` and `resample_ratio / 10.0`.
     /// - `interpolation_type`: Degree of polynomial used for interpolation, see [PolynomialDegree].
     /// - `chunk_size`: Size of input data in frames.
     /// - `nbr_channels`: Number of channels in input/output.
@@ -237,7 +237,7 @@ where
     ///
     /// Parameters are:
     /// - `resample_ratio`: Starting ratio between output and input sample rates, must be > 0.
-    /// - `max_resample_ratio_relative`: Maximum ratio that can be set with [Resampler::set_resample_ratio] relative to `resample_ratio`, must be >= 1.0. The minimum relative ratio is the reciprocal of the maximum. For example, with `max_resample_ratio_relative` of 10.0, the ratio can be set between `resample_ratio * 10.0` and `resample_ratio / 10.0`.
+    /// - `max_resample_ratio_relative`: Maximum ratio that can be set with [Adjustable::set_resample_ratio](crate::Adjustable::set_resample_ratio) relative to `resample_ratio`, must be >= 1.0. The minimum relative ratio is the reciprocal of the maximum. For example, with `max_resample_ratio_relative` of 10.0, the ratio can be set between `resample_ratio * 10.0` and `resample_ratio / 10.0`.
     /// - `parameters`: Parameters for interpolation, see [SincInterpolationParameters].
     /// - `chunk_size`: Size of input data in frames.
     /// - `nbr_channels`: Number of channels in input/output.
@@ -277,7 +277,7 @@ where
     ///
     /// Parameters are:
     /// - `resample_ratio`: Starting ratio between output and input sample rates, must be > 0.
-    /// - `max_resample_ratio_relative`: Maximum ratio that can be set with [Resampler::set_resample_ratio] relative to `resample_ratio`, must be >= 1.0. The minimum relative ratio is the reciprocal of the maximum. For example, with `max_resample_ratio_relative` of 10.0, the ratio can be set between `resample_ratio` * 10.0 and `resample_ratio` / 10.0.
+    /// - `max_resample_ratio_relative`: Maximum ratio that can be set with [Adjustable::set_resample_ratio](crate::Adjustable::set_resample_ratio) relative to `resample_ratio`, must be >= 1.0. The minimum relative ratio is the reciprocal of the maximum. For example, with `max_resample_ratio_relative` of 10.0, the ratio can be set between `resample_ratio` * 10.0 and `resample_ratio` / 10.0.
     /// - `interpolation_type`: Parameters for interpolation, see `SincInterpolationParameters`.
     /// - `interpolator`: The interpolator to use.
     /// - `chunk_size`: Size of output data in frames.
@@ -441,6 +441,23 @@ where
             self.needed_output_size
         );
     }
+
+    /// Check whether a ratio, expressed relative to the original ratio, is within the
+    /// allowed `1 / max` to `max` range. Checking the relative ratio directly avoids the
+    /// rounding error that a `(original * rel) / original` round-trip would introduce at
+    /// the exact bounds.
+    fn relative_ratio_in_bounds(&self, rel_ratio: f64) -> bool {
+        rel_ratio >= 1.0 / self.max_relative_ratio && rel_ratio <= self.max_relative_ratio
+    }
+
+    /// Apply an already validated resample ratio to the internal state.
+    fn apply_ratio(&mut self, new_ratio: f64, ramp: bool) {
+        if !ramp {
+            self.resample_ratio = new_ratio;
+        }
+        self.target_ratio = new_ratio;
+        self.update_lengths();
+    }
 }
 
 impl<T> Resampler<T> for Async<T>
@@ -573,35 +590,10 @@ where
         self.needed_input_size
     }
 
-    fn set_resample_ratio(&mut self, new_ratio: f64, ramp: bool) -> ResampleResult<()> {
-        trace!("Change resample ratio to {}", new_ratio);
-        if (new_ratio / self.resample_ratio_original >= 1.0 / self.max_relative_ratio)
-            && (new_ratio / self.resample_ratio_original <= self.max_relative_ratio)
-        {
-            if !ramp {
-                self.resample_ratio = new_ratio;
-            }
-            self.target_ratio = new_ratio;
-            self.update_lengths();
-            Ok(())
-        } else {
-            Err(ResampleError::RatioOutOfBounds {
-                provided: new_ratio,
-                original: self.resample_ratio_original,
-                max_relative_ratio: self.max_relative_ratio,
-            })
-        }
-    }
-
     fn resample_ratio(&self) -> f64 {
         self.resample_ratio
     }
 
-    fn set_resample_ratio_relative(&mut self, rel_ratio: f64, ramp: bool) -> ResampleResult<()> {
-        let new_ratio = self.resample_ratio_original * rel_ratio;
-        self.set_resample_ratio(new_ratio, ramp)
-    }
-
     fn reset(&mut self) {
         self.buffer
             .iter_mut()
@@ -614,6 +606,60 @@ where
         self.update_lengths();
     }
 
+    fn as_adjustable(&mut self) -> Option<&mut dyn Adjustable<T>> {
+        Some(self)
+    }
+
+    fn is_adjustable(&self) -> bool {
+        true
+    }
+
+    fn as_resizable(&mut self) -> Option<&mut dyn Resizable<T>> {
+        Some(self)
+    }
+
+    fn is_resizable(&self) -> bool {
+        true
+    }
+}
+
+impl<T> Adjustable<T> for Async<T>
+where
+    T: Sample,
+{
+    fn set_resample_ratio(&mut self, new_ratio: f64, ramp: bool) -> ResampleResult<()> {
+        trace!("Change resample ratio to {}", new_ratio);
+        if self.relative_ratio_in_bounds(new_ratio / self.resample_ratio_original) {
+            self.apply_ratio(new_ratio, ramp);
+            Ok(())
+        } else {
+            Err(ResampleError::RatioOutOfBounds {
+                provided: new_ratio,
+                original: self.resample_ratio_original,
+                max_relative_ratio: self.max_relative_ratio,
+            })
+        }
+    }
+
+    fn set_resample_ratio_relative(&mut self, rel_ratio: f64, ramp: bool) -> ResampleResult<()> {
+        let new_ratio = self.resample_ratio_original * rel_ratio;
+        if self.relative_ratio_in_bounds(rel_ratio) {
+            self.apply_ratio(new_ratio, ramp);
+            Ok(())
+        } else {
+            Err(ResampleError::RatioOutOfBounds {
+                provided: new_ratio,
+                original: self.resample_ratio_original,
+                max_relative_ratio: self.max_relative_ratio,
+            })
+        }
+    }
+}
+
+impl<T> Resizable<T> for Async<T>
+where
+    T: Sample,
+{
     fn set_chunk_size(&mut self, chunksize: usize) -> ResampleResult<()> {
         if chunksize > self.max_chunk_size || chunksize == 0 {
             return Err(ResampleError::InvalidChunkSize {
@@ -632,14 +678,14 @@ mod tests {
     use crate::tests::expected_output_value;
     use crate::Indexing;
     use crate::PolynomialDegree;
-    use crate::Resampler;
     use crate::SincInterpolationParameters;
     use crate::SincInterpolationType;
     use crate::WindowFunction;
     use crate::{
         assert_fi_len, assert_fo_len, check_input_offset, check_masked, check_output,
         check_output_offset, check_ratio, check_reset,
     };
+    use crate::{Adjustable, Resampler, Resizable};
     use crate::{Async, FixedAsync};
     use audioadapter_buffers::direct::SequentialSliceOfVecs;
     use test_case::test_matrix;
@@ -816,6 +862,37 @@ mod tests {
         check_output!(resampler, f64);
     }
 
+    // The exact relative bounds `1 / max` and `max` must be accepted. The pair below is chosen
+    // so that the old `(original * rel) / original` round-trip rounds the lower bound just outside
+    // the range and wrongly rejected it; checking the relative ratio directly must not.
+    #[test_log::test]
+    fn async_relative_ratio_exact_bounds() {
+        let params = basic_params();
+        let original_ratio = 44100.0 / 48000.0;
+        let max = 1.0161;
+        let mut resampler =
+            Async::<f64>::new_sinc(original_ratio, max, &params, 1024, 2, FixedAsync::Input)
+                .unwrap();
+
+        assert!(
+            resampler.set_resample_ratio_relative(max, false).is_ok(),
+            "exact upper bound must be accepted"
+        );
+        assert!(
+            resampler
+                .set_resample_ratio_relative(1.0 / max, false)
+                .is_ok(),
+            "exact lower bound must be accepted"
+        );
+        // Just outside the range must still be rejected.
+        assert!(resampler
+            .set_resample_ratio_relative(max * 1.0001, false)
+            .is_err());
+        assert!(resampler
+            .set_resample_ratio_relative(1.0 / max * 0.9999, false)
+            .is_err());
+    }
+
     fn process_and_get_frame_counts(resampler: &mut Async<f64>) -> (usize, usize) {
         let input_frames = resampler.input_frames_next();
         let output_frames_max = resampler.output_frames_max();

src/error.rs

@@ -119,17 +119,14 @@ impl error::Error for ResamplerConstructionError {}
 #[derive(Clone, Copy, PartialEq)]
 #[non_exhaustive]
 pub enum ResampleError {
-    /// Error raised when [Resampler::set_resample_ratio](crate::Resampler::set_resample_ratio)
+    /// Error raised when [Adjustable::set_resample_ratio](crate::Adjustable::set_resample_ratio)
     /// is called with a ratio outside the maximum range specified when
     /// the resampler was constructed.
     RatioOutOfBounds {
         provided: f64,
         original: f64,
         max_relative_ratio: f64,
     },
-    /// Error raised when calling [Resampler::set_resample_ratio](crate::Resampler::set_resample_ratio)
-    /// on a synchronous resampler.
-    SyncNotAdjustable,
     /// Error raised when the number of channels in the input buffer doesn't match the value expected.
     WrongNumberOfInputChannels {
         expected: usize,
@@ -161,7 +158,6 @@ pub enum ResampleError {
         max: usize,
         requested: usize,
     },
-    ChunkSizeNotAdjustable,
 }
 
 impl fmt::Display for ResampleError {
@@ -175,9 +171,6 @@ impl fmt::Display for ResampleError {
                 write!(f, "New resample ratio out of bounds. Provided ratio {}, original resample ratio {}, maximum relative ratio {}, allowed absolute range {} to {}",
                 provided, original, max_relative_ratio, original / max_relative_ratio, original * max_relative_ratio)
             }
-            Self::SyncNotAdjustable { .. } => {
-                write!(f, "Not possible to adjust a synchronous resampler")
-            }
             Self::WrongNumberOfInputChannels { expected, actual } => {
                 write!(
                     f,
@@ -220,9 +213,6 @@ impl fmt::Display for ResampleError {
                     requested, max
                 )
             }
-            Self::ChunkSizeNotAdjustable { .. } => {
-                write!(f, "This resampler does not support changing the chunk size")
-            }
         }
     }
 }