documentation and cleanup

Author: l-Luna

Cargo.toml

@@ -2,6 +2,11 @@
 name = "scamble"
 version = "0.1.0"
 edition = "2024"
+license = "MIT"
+description = "Library for building FMOD DSPs"
+repository = "https://github.com/l-Luna/scamble"
+keywords = ["fmod", "dsp"]
+categories = ["multimedia::audio"]
 
 [workspace]
 members = ["tcp_effects", "cassette_player"]

README.md

@@ -0,0 +1,30 @@
+a rust library for writing FMOD DSPs
+
+a simple example:
+```rs
+#![feature(macro_metavar_expr)]
+#![feature(macro_metavar_expr_concat)]
+
+use scamble::expose_dsp;
+use scamble::dsp::*;
+use scamble::dsp::signal::*;
+
+pub struct Invert;
+
+impl Dsp for Invert{
+    fn name() -> &'static str { "Invert" }
+    fn version() -> u32 { 1 }
+    fn ty() -> DspType { DspType::Effect }
+    fn create() -> Self { Invert }
+    
+    fn read(&mut self, input: SignalConst, mut output: SignalMut) {
+        let in_data = input.samples();
+        let out_data = output.samples_mut();
+        for i in 0..in_data.len() {
+            out_data[i] = -in_data[i];
+        }
+    }
+}
+
+expose_dsp!(Invert);
+```

build.rs

@@ -1,11 +1,8 @@
 use bindgen::EnumVariation;
-use std::{env, fs};
+use std::env;
 use std::path::PathBuf;
 
 fn main() {
-    // println!("cargo:rustc-link-search=./libs/");
-    // println!("cargo:rustc-link-lib= fmod");
-
     let bindings = bindgen::Builder::default()
         .header("libs/wrapper.h")
         .default_enum_style(EnumVariation::Rust {
@@ -20,12 +17,4 @@ fn main() {
     bindings
         .write_to_file(target)
         .expect("Couldn't write bindings!");
-
-    // slightly hacky way to append the right link mode for windows
-    /*let mut st = fs::read_to_string(target).expect("Couldn't update bindings!");
-    st = st.replace(
-        "unsafe extern \"C\" {",
-        "#[cfg_attr(windows, link(name = \"fmod\", kind = \"raw-dylib\"))]\nunsafe extern \"C\" {"
-    );
-    fs::write(target, st).expect("Couldn't update bindings!");*/
 }

plot.png

@@ -1,10 +1,14 @@
+//! Data types used as DSP parameters.
+
+/// A 3D vector. Part of DSP parameter types.
 #[derive(Copy, Clone, Debug, PartialEq)]
 pub struct Vec3 {
     pub x: f32,
     pub y: f32,
     pub z: f32
 }
 
+/// A perspective in 3D. Part of DSP parameter types.
 #[derive(Copy, Clone, Debug, PartialEq)]
 pub struct _3DAttributes {
     pub position: Vec3,
@@ -13,38 +17,60 @@ pub struct _3DAttributes {
     pub up: Vec3
 }
 
+/// Multi-channel spectra, for use with [dsp::ParameterType::Fft].
 #[derive(Clone, Debug, PartialEq)]
 pub struct FftData {
+    /// Per-channel spectra, as a vector of per-channel data.
     pub data: Vec<Vec<f32>>
 }
 
+/// Dynamic response, for use with [dsp::ParameterType::DynamicResponse].
 #[derive(Clone, Debug, PartialEq)]
 pub struct DynamicResponseData {
+    /// Per-channel average (RMS) gain factor.
     pub rms: Vec<f32>
 }
 
+/// Overall gain, for use with [dsp::ParameterType::OverallGain]. FMOD reads this parameter type
+/// to determine when to virtualize voices.
 #[derive(Copy, Clone, Debug, PartialEq)]
 pub struct OverallGainData {
+    /// Overall linear gain applied to the signal.
     pub linear_gain: f32,
+    /// Overall additive gain applied to the signal.
     pub linear_gain_additive: f32
 }
 
+/// Listener attributes, for use with [dsp::ParameterType::ListenerAttributes]. FMOD sets this
+/// parameter type based on the listener's and event's locations automatically.
 #[derive(Copy, Clone, Debug, PartialEq)]
 pub struct ListenerAttributesData {
+    /// Relative position of the sound to the listener.
     pub relative: _3DAttributes,
+    /// Absolute position of the sound in the world.
     pub absolute: _3DAttributes
 }
 
+/// Listener attributes when multiple listeners exist, for use with [dsp::ParameterType::ListenerAttributesList].
+/// FMOD sets this parameter type based on the listeners' and event's locations automatically.
 #[derive(Clone, Debug, PartialEq)]
 pub struct ListenerAttributesListData {
+    /// The number of listeners, equal to the length of the `relative` and `weights` fields.
     pub count: usize,
+    /// Relative position of the sound to each listener.
     pub relative: Vec<_3DAttributes>,
+    /// Weight of each listener to the sound output, in the range 0..1.
     pub weights: Vec<f32>,
+    /// Absolute position of the sound in the world.
     pub absolute: _3DAttributes
 }
 
+/// Attenuation range of an event, for use with [dsp::ParameterType::AttenuationRange]. FMOD Studio
+/// sets and updates this parameter type based on the event's minimum and maximum distance.
 #[derive(Copy, Clone, Debug, PartialEq)]
 pub struct AttenuationRangeData {
+    /// Minimum distance for attenuation.
     pub min: f32,
+    /// Maximum distance for attenuation.
     pub max: f32
 }

src/data.rs

@@ -1,3 +1,5 @@
+//! Utilities for decoding samples from a plugin, for data inputs.
+
 use hound::{SampleFormat, WavReader};
 
 /// Decode a data buffer into mono samples, guessing the correct format.

src/dsp/decode.rs

@@ -1,7 +1,10 @@
+//! Wraps `scamble`'s DSP API into FMOD's API. Use `expose_dsp` or `expose_dsp_list` to create a
+//! standalone plugin binary, or use [into_desc] to pass a value directly to FMOD Core's API.
+
 use crate::raw_bindings::*;
 use crate::raw_bindings::FMOD_DSP_PARAMETER_DATA_TYPE::*;
 use crate::raw_bindings::FMOD_RESULT::{FMOD_ERR_DSP_DONTPROCESS, FMOD_ERR_DSP_SILENCE, FMOD_ERR_INVALID_PARAM, FMOD_ERR_PLUGIN, FMOD_OK};
-pub use crate::dsp::{Dsp, DspType, ParameterType, ProcessResult};
+use crate::dsp::{Dsp, DspType, ParameterType, ProcessResult};
 use crate::dsp::signal::{SignalConst, SignalMut};
 use std::{alloc, panic, ptr};
 use std::alloc::Layout;
@@ -11,6 +14,7 @@ use std::str::FromStr;
 
 // wrapping DSPs into FMOD's format
 
+/// Expose a DSP type to FMOD to be loaded as a dynamic library.
 #[macro_export]
 macro_rules! expose_dsp {
     ($t:tt) => {
@@ -41,6 +45,7 @@ macro_rules! expose_dsp {
     };
 }
 
+/// Expose multiple DSP types to FMOD to be loaded as a dynamic library.
 #[macro_export]
 macro_rules! expose_dsp_list {
     ($($t:ident $(,)?)*) => {
@@ -89,10 +94,9 @@ macro_rules! expose_dsp_list {
     };
 }
 
-pub(crate) use expose_dsp;
-pub(crate) use expose_dsp_list;
-
+/// Convert a DSP type into an FMOD DSP description, to be passed to the FMOD Core API.
 pub fn into_desc<D: Dsp>() -> FMOD_DSP_DESCRIPTION {
+    // TODO: set the hook in FMODGetPluginDescription[List] so it only applies for standalones
     panic::set_hook(Box::new(|it| {
         let mut desc = String::new();
         desc.push_str("Panic");
@@ -272,6 +276,8 @@ static DBGSTR: &'static str = "Rust DSP\0";
 static mut CUR_STATE: *mut FMOD_DSP_STATE = ptr::null_mut();
 static mut IN_LENGTH: usize = 0;
 
+/// Read a sidechain input from a DSP. Should only be called from [Dsp::read], only if a
+/// [ParameterType::Sidechain] is present and enabled, otherwise [None] will always be provided.
 pub fn with_sidechain<T>(f: impl FnOnce(Option<SignalConst>) -> T) -> T{
     let cur_state = unsafe { CUR_STATE };
     if cur_state.is_null() {