Document all current views

src/visualizers/graph.rs

@@ -9,6 +9,23 @@ use nih_plug_vizia::vizia::{
 use std::sync::{Arc, Mutex};
 
 /// A real-time graph displaying information that is stored inside a buffer
+///
+/// Use this view to construct peak graphs, loudness graphs, or any other graph that
+/// displays the data inside a [`VisualizerBuffer`].
+///
+/// # Example
+///
+/// Here's how to set up a basic peak graph. For this example, you'll need a
+/// [`PeakBuffer`](crate::utils::PeakBuffer) to store your peak information.
+///
+/// ```
+/// Graph::new(cx, Data::peak_buffer, (-32.0, 8.0), ValueScaling::Decibels)
+///     .color(Color::rgba(0, 0, 0, 160))
+///     .background_color(Color::rgba(0, 0, 0, 60));
+/// ```
+///
+/// The graph displays the range from -32.0dB to 8dB. It scales the values as
+/// decibels, and a stroke and fill (background) color is provided.
 pub struct Graph<L, I>
 where
     L: Lens<Target = Arc<Mutex<I>>>,
@@ -108,9 +125,22 @@ where
 }
 
 pub trait GraphModifiers {
-    /// Allows for the grid to be filled from the top instead of the bottom.
+    /// Allows for the graph to be filled from the top instead of the bottom.
     ///
     /// This is useful for certain graphs like gain reduction meters.
+    ///
+    /// # Example
+    ///
+    /// Here's a gain reduction graph, which you could overlay on top of a peak graph.
+    ///
+    /// Here, `gain_mult` could be a [`MinimaBuffer`](crate::utils::MinimaBuffer).
+    ///
+    /// ```
+    /// Graph::new(cx, Data::gain_mult, (-32.0, 8.0), ValueScaling::Decibels)
+    ///     .should_fill_from_top(true)
+    ///     .color(Color::rgba(255, 0, 0, 160))
+    ///     .background_color(Color::rgba(255, 0, 0, 60));
+    /// ```
     fn should_fill_from_top(self, fill_from_top: bool) -> Self;
 }
 

src/visualizers/grid.rs

@@ -11,6 +11,31 @@ use crate::utils::ValueScaling;
 /// A generic grid backdrop that displays either horizontal or vertical lines.
 ///
 /// Put this grid inside a ZStack, along with your visualizer of choice.
+///
+/// # Example
+///
+/// Here's how to add a `Grid` as a backdrop to a `Graph`.
+///
+/// ```
+/// ZStack::new(cx, |cx| {
+///     Grid::new(
+///         cx,
+///         ValueScaling::Linear,
+///         (-32., 8.),
+///         vec![6.0, 0.0, -6.0, -12.0, -18.0, -24.0, -30.0],
+///         Orientation::Horizontal,
+///     )
+///     .color(Color::rgb(60, 60, 60));
+///
+///     Graph::new(cx, Data::peak_buffer, (-32.0, 8.0), ValueScaling::Decibels)
+///         .color(Color::rgba(255, 255, 255, 160))
+///         .background_color(Color::rgba(255, 255, 255, 60));
+/// })
+/// .background_color(Color::rgb(16, 16, 16));
+/// ```
+///
+/// Note that both the `Graph` and `Grid` have the same range, which is necessary
+/// for them to scale correctly.
 pub struct Grid {
     scaling: ValueScaling,
     range: (f32, f32),

src/visualizers/lissajous.rs

@@ -19,6 +19,65 @@ lazy_static! {
     static ref TRANSLATE_COS: f32 = (PI / 4.).cos();
 }
 
+/// A lissajous for stereo audio data.
+///
+/// The further points are from the horizontal middle, the more stereo your signal
+/// is. If they are closer to the top or bottom, your signal has a positive or a
+/// negative offset, respectively. If the lissajous shows a straight horizontal
+/// line, your channels are fully out of phase. If it skews either way diagonally,
+/// your signal is more present on the left or right side, respectively.
+///
+/// For more information about lissajous curves, check out the
+/// [Wikipedia entry](https://en.wikipedia.org/wiki/Lissajous_curve) on them.
+///
+/// # Examples
+/// 
+/// ## Basic Lissajous
+///
+/// For this example, set up a [`RingBuffer<(f32, f32)>`](crate::utils::RingBuffer)
+/// that contains your stereo data as tuples of `f32`s.
+///
+/// ```
+/// Lissajous::new(cx, Data::lissajous_buffer).color(Color::rgb(160, 160, 160));
+/// ```
+/// 
+/// ## Grid and Labels
+///
+/// If you want to take it a step further, you can add a [`LissajousGrid`] and
+/// labels to your Lissajous.
+/// 
+/// ```
+/// ZStack::new(cx, |cx| {
+///     LissajousGrid::new(cx)
+///         .background_color(Color::rgb(32, 32, 32))
+///         .color(Color::rgb(60, 60, 60));
+///     Lissajous::new(cx, Data::lissajous_buffer).color(Color::rgb(160, 160, 160));
+///     ZStack::new(cx, |cx| {
+///         Label::new(cx, "+L").color(Color::rgb(160, 160, 160));
+///         Label::new(cx, "+R")
+///             .left(Percentage(100.))
+///             .transform(Transform::TranslateX(LengthOrPercentage::Percentage(-100.)))
+///             .color(Color::rgb(160, 160, 160));
+///         Label::new(cx, "-R")
+///             .top(Percentage(100.))
+///             .transform(Transform::TranslateY(LengthOrPercentage::Percentage(-100.)))
+///             .color(Color::rgb(160, 160, 160));
+///         Label::new(cx, "-L")
+///             .top(Percentage(100.))
+///             .left(Percentage(100.))
+///             .transform(vec![
+///                 Transform::TranslateX(LengthOrPercentage::Percentage(-100.)),
+///                 Transform::TranslateY(LengthOrPercentage::Percentage(-100.)),
+///             ])
+///             .color(Color::rgb(160, 160, 160));
+///     })
+///     .space(Pixels(16.));
+/// })
+/// .background_color(Color::rgb(16, 16, 16))
+/// .border_color(Color::rgb(80, 80, 80))
+/// .border_width(Pixels(1.))
+/// .width(Pixels(200.));
+/// ```
 pub struct Lissajous<L>
 where
     L: Lens<Target = Arc<Mutex<RingBuffer<(f32, f32)>>>>,
@@ -79,6 +138,7 @@ where
     }
 }
 
+/// A diamond-shaped grid that can serve as a backdrop for a [`Lissajous`]
 pub struct LissajousGrid {}
 
 impl LissajousGrid {

src/visualizers/meter.rs

@@ -5,6 +5,24 @@ use nih_plug_vizia::vizia::{prelude::*, vg};
 use crate::utils::ValueScaling;
 use crate::utils::VisualizerBuffer;
 
+/// A Meter that displays the data inside a [`VisualizerBuffer`].
+///
+/// Useful for peak meters, loudness meters, etc.
+///
+/// # Example
+///
+/// ```
+/// Meter::new(
+///     cx,
+///     Data::peak_buffer,
+///     (-32.0, 8.0),
+///     ValueScaling::Decibels,
+///     Orientation::Vertical,
+/// )
+/// .width(Pixels(24.0))
+/// .height(Pixels(128.0))
+/// .background_color(Color::rgb(100, 100, 100));
+/// ```
 pub struct Meter<L, I>
 where
     L: Lens<Target = Arc<Mutex<I>>>,

src/visualizers/oscilloscope.rs

@@ -7,15 +7,22 @@ use crate::utils::{ValueScaling, VisualizerBuffer, WaveformBuffer};
 /// A waveform display for real-time input.
 ///
 /// This visualizer is particularly useful when visualizing audio data at a
-/// high sample rate, such as 44.1kHz, in a much smaller view. It does not
+/// high sample rate, such as 44.1kHz, in a much smaller view. It does not naively
 /// downsample the audio, which is why, even for very small sizes, it still
 /// correctly displays the peak data.
 ///
-/// # How to use
+/// # Example
 ///
-/// To use this Visualizer, you need a [`WaveformBuffer`](`crate::utils::WaveformBuffer`)
-/// that you write to inside your plugin code, and then send to the editor
-/// thread - wrap it in an `Arc<Mutex>` to send it.
+/// ```
+/// Oscilloscope::new(
+///     cx,
+///     Data::oscilloscope_buffer,
+///     (-1.2, 1.2),
+///     ValueScaling::Linear,
+/// )
+/// .color(Color::rgba(0, 0, 0, 0))
+/// .background_color(Color::rgba(255, 255, 255, 120));
+/// ```
 ///
 pub struct Oscilloscope<B>
 where