From bb052d08372c9b20d96000383bacb2c8085c79c7 Mon Sep 17 00:00:00 2001
From: Weird Constructor <weirdconstructor@gmail.com>
Date: Thu, 5 Aug 2021 18:39:42 +0200
Subject: [PATCH] Document oversampling and distortion with VPSOscillator

---
 src/dsp/helpers.rs | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/src/dsp/helpers.rs b/src/dsp/helpers.rs
index a26a22b..0d2e3d1 100644
--- a/src/dsp/helpers.rs
+++ b/src/dsp/helpers.rs
@@ -1509,6 +1509,37 @@ impl PolyBlepOscillator {
 ///     *output_sample = osc.next(freq, israte, d, v);
 /// }
 ///```
+///
+/// It can be beneficial to apply distortion and oversampling.
+/// Especially oversampling can be important for some `d` and `v`
+/// combinations, even without distortion.
+///
+///```
+/// use hexodsp::dsp::helpers::{VPSOscillator, rand_01, apply_distortion};
+/// use hexodsp::dsp::biquad::Oversampling;
+///
+/// let mut osc = VPSOscillator::new(rand_01() * 0.25);
+/// let mut ovr : Oversampling<4> = Oversampling::new();
+///
+/// let freq   = 440.0; // Hz
+/// let israte = 1.0 / 44100.0; // Seconds per Sample
+/// let d      = 0.5;   // Range: 0.0 to 1.0
+/// let v      = 0.75;  // Range: 0.0 to 1.0
+///
+/// let mut block_of_samples = [0.0; 128];
+/// // in your process function:
+/// for output_sample in block_of_samples.iter_mut() {
+///     // It is advised to limit the `v` value, because with certain
+///     // `d` values the combination creates just a DC offset.
+///     let v = VPSOscillator::limit_v(d, v);
+///
+///     let overbuf = ovr.resample_buffer();
+///     for b in overbuf {
+///         *b = apply_distortion(osc.next(freq, israte, d, v), 0.9,  1);
+///     }
+///     *output_sample = ovr.downsample();
+/// }
+///```
 #[derive(Debug, Clone)]
 pub struct VPSOscillator {
     phase:       f32,