ref: 27cf83ad3cc3493951943efb7f0ee18e60805fd9
parent: 00e5f111f5c6d6cf6c58a81278b884b667d4e8f1
author: Matthew Wang <mjw7@princeton.edu>
date: Fri Mar 13 10:13:55 EDT 2020
building up documentation
--- a/Doxyfile
+++ b/Doxyfile
@@ -946,7 +946,7 @@
# that contain example code fragments that are included (see the \include
# command).
-EXAMPLE_PATH =
+EXAMPLE_PATH = Examples
# If the value of the EXAMPLE_PATH tag contains directories, you can use the
# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
binary files a/LEAF/.DS_Store b/LEAF/.DS_Store differ
--- a/LEAF/Inc/leaf-analysis.h
+++ b/LEAF/Inc/leaf-analysis.h
@@ -21,6 +21,14 @@
#include "leaf-filters.h"
#include "leaf-envelopes.h"
+ /*!
+ * @internal
+ * Header.
+ * @include basic-oscillators.h
+ * @example basic-oscillators.c
+ * An example.
+ */
+
//==============================================================================
/* Envelope Follower */
--- a/LEAF/Inc/leaf-delay.h
+++ b/LEAF/Inc/leaf-delay.h
@@ -18,6 +18,14 @@
#include "leaf-math.h"
#include "leaf-mempool.h"
+ /*!
+ * @internal
+ * Header.
+ * @include basic-oscillators.h
+ * @example basic-oscillators.c
+ * An example.
+ */
+
//==============================================================================
/* Non-interpolating delay, reimplemented from STK (Cook and Scavone). */
--- a/LEAF/Inc/leaf-distortion.h
+++ b/LEAF/Inc/leaf-distortion.h
@@ -19,6 +19,14 @@
#include "leaf-mempool.h"
#include "leaf-math.h"
+ /*!
+ * @internal
+ * Header.
+ * @include basic-oscillators.h
+ * @example basic-oscillators.c
+ * An example.
+ */
+
//==============================================================================
typedef struct _tSampleReducer
@@ -136,6 +144,7 @@
void tCrusher_setSamplingRatio (tCrusher* const, float ratio);
//==============================================================================
+
#ifdef __cplusplus
}
--- a/LEAF/Inc/leaf-dynamics.h
+++ b/LEAF/Inc/leaf-dynamics.h
@@ -21,6 +21,14 @@
#include "leaf-mempool.h"
#include "leaf-analysis.h"
+ /*!
+ * @internal
+ * Header.
+ * @include basic-oscillators.h
+ * @example basic-oscillators.c
+ * An example.
+ */
+
//==============================================================================
// ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
--- a/LEAF/Inc/leaf-effects.h
+++ b/LEAF/Inc/leaf-effects.h
@@ -21,6 +21,14 @@
#include "leaf-analysis.h"
#include "leaf-envelopes.h"
+ /*!
+ * @internal
+ * Header.
+ * @include basic-oscillators.h
+ * @example basic-oscillators.c
+ * An example.
+ */
+
//==============================================================================
/* tTalkbox */
--- a/LEAF/Inc/leaf-electrical.h
+++ b/LEAF/Inc/leaf-electrical.h
@@ -18,6 +18,14 @@
#include "leaf-math.h"
#include "leaf-mempool.h"
+ /*!
+ * @internal
+ * Header.
+ * @include basic-oscillators.h
+ * @example basic-oscillators.c
+ * An example.
+ */
+
//==============================================================================
typedef enum WDFComponentType
--- a/LEAF/Inc/leaf-envelopes.h
+++ b/LEAF/Inc/leaf-envelopes.h
@@ -24,6 +24,14 @@
#include "leaf-analysis.h"
#include "leaf-envelopes.h"
+ /*!
+ * @internal
+ * Header.
+ * @include basic-oscillators.h
+ * @example basic-oscillators.c
+ * An example.
+ */
+
// ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
/* Attack-Decay envelope */
--- a/LEAF/Inc/leaf-filters.h
+++ b/LEAF/Inc/leaf-filters.h
@@ -20,6 +20,14 @@
#include "leaf-delay.h"
#include "leaf-tables.h"
+ /*!
+ * @internal
+ * Header.
+ * @include basic-oscillators.h
+ * @example basic-oscillators.c
+ * An example.
+ */
+
//==============================================================================
/* tAllpass: Schroeder allpass. Comb-filter with feedforward and feedback. */
--- a/LEAF/Inc/leaf-global.h
+++ b/LEAF/Inc/leaf-global.h
@@ -18,27 +18,24 @@
#include "leaf-mempool.h"
/*!
- * @internal
- * @defgroup LEAF LEAF
- * @brief The LEAF instance. Contains global references and settings.
- * @{
+ * @ingroup leaf
+ * @brief The struct of the global LEAF instance `leaf`. Contains global variables and settings.
*/
- typedef struct LEAF
+ struct LEAF
{
- ///@{ @internal
- float sampleRate; //!< The current audio sample rate.
+ ///@{
+ float sampleRate; //!< The current audio sample rate. Set with LEAF_setSampleRate().
float invSampleRate; //!< The inverse of the current sample rate.
- int blockSize; //!< The size of the audio block and delay in sample between input and output.
+ int blockSize; //!< The audio block size.
float twoPiTimesInvSampleRate; //!< Two-pi times the inverse of the current sample rate.
- float (*random)(void); //!< A pointer to a random() function provided on initialization.
+ float (*random)(void); //!< A pointer to the random() function provided on initialization.
int clearOnAllocation; //!< A flag that determines whether memory allocated from the LEAF memory pool will be cleared.
- tMempool mempool;
+ tMempool mempool; //!< The default LEAF mempool object.
_tMempool _mempool;
- size_t header_size;
+ size_t header_size; //!< The size in bytes of memory region headers within mempools.
///@}
- } LEAF;
-
- /*! @} */
+ };
+ typedef struct LEAF LEAF;
extern LEAF leaf;
--- a/LEAF/Inc/leaf-instruments.h
+++ b/LEAF/Inc/leaf-instruments.h
@@ -21,6 +21,14 @@
#include "leaf-filters.h"
#include "leaf-envelopes.h"
+ /*!
+ * @internal
+ * Header.
+ * @include basic-oscillators.h
+ * @example basic-oscillators.c
+ * An example.
+ */
+
//==============================================================================
// 808 Cowbell
--- a/LEAF/Inc/leaf-mempool.h
+++ b/LEAF/Inc/leaf-mempool.h
@@ -54,8 +54,9 @@
//#define size_t unsigned long
- /**
- * @defgroup TMEMPOOL tMempool
+ /*!
+ * @defgroup tmempool tMempool
+ * @ingroup mempool
* An object that can contain an additional mempool for the allocation of LEAF objects.
* @{
*/
@@ -78,7 +79,7 @@
typedef _tMempool* tMempool;
- //! Initializes a tMempool for a given memory location and size to the default LEAF mempool.
+ //! Initialize a tMempool for a given memory location and size to the default LEAF mempool.
/*!
@param pool A pointer to the tMempool to be initialized.
@param memory A pointer to the chunk of memory to be used as a mempool.
@@ -87,7 +88,7 @@
void tMempool_init (tMempool* const pool, char* memory, size_t size);
- //! Frees a tMempool from the default LEAF mempool.
+ //! Free a tMempool from the default LEAF mempool.
/*!
@param pool A pointer to the tMempool to be freed.
*/
@@ -94,7 +95,7 @@
void tMempool_free (tMempool* const pool);
- //! Initializes a tMempool for a given memory location and size to a specified mempool.
+ //! Initialize a tMempool for a given memory location and size to a specified mempool.
/*!
@param pool A pointer to the tMempool to be initialized.
@param memory A pointer to the chunk of memory to be used as a mempool.
@@ -104,7 +105,7 @@
void tMempool_initToPool (tMempool* const pool, char* memory, size_t size, tMempool* const poolTo);
- //! Frees a tMempool from a specified mempool.
+ //! Free a tMempool from a specified mempool.
/*!
@param pool A pointer to the tMempool to be freed from the default LEAF mempool.
@param poolFrom A pointer to the tMempool from which a tMempool should be freed.
--- a/LEAF/Inc/leaf-midi.h
+++ b/LEAF/Inc/leaf-midi.h
@@ -20,10 +20,25 @@
#include "leaf-math.h"
#include "leaf-envelopes.h"
+ /*!
+ * @internal
+ * Header.
+ * @include basic-oscillators.h
+ * @example basic-oscillators.c
+ * An example.
+ */
+
//==============================================================================
// ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~
+ /*!
+ * @defgroup tstack tStack
+ * @ingroup midi
+ * @brief A basic stack of integers with a fixed max size of 128, used by tPoly to keep track of MIDI notes.
+ * @{
+ */
+
// STACK implementation (fixed size)
#define STACK_SIZE 128
typedef struct _tStack
@@ -38,22 +53,121 @@
typedef _tStack* tStack;
- void tStack_init (tStack* const);
- void tStack_free (tStack* const);
- void tStack_initToPool (tStack* const, tMempool* const);
- void tStack_freeFromPool (tStack* const, tMempool* const);
+ //! Initialize a tStack to the default LEAF mempool.
+ /*!
+ @param stack A pointer to the tStack to be initialized.
+ */
+ void tStack_init (tStack* const stack);
- void tStack_setCapacity (tStack* const, uint16_t cap);
- int tStack_addIfNotAlreadyThere (tStack* const, uint16_t item);
- void tStack_add (tStack* const, uint16_t item);
- int tStack_remove (tStack* const, uint16_t item);
- void tStack_clear (tStack* const);
- int tStack_first (tStack* const);
- int tStack_getSize (tStack* const);
- int tStack_contains (tStack* const, uint16_t item);
- int tStack_next (tStack* const);
- int tStack_get (tStack* const, int which);
+ //! Free a tStack from the default LEAF mempool.
+ /*!
+ @param stack A pointer to the tStack to be freed.
+ */
+ void tStack_free (tStack* const stack);
+
+
+ //! Initialize a tStack to a specified mempool.
+ /*!
+ @param stack A pointer to the tStack to be initialized.
+ @param pool A pointer to the tMempool to which the tStack should be initialized.
+ */
+ void tStack_initToPool (tStack* const stack, tMempool* const pool);
+
+
+ //! Free a tStack from a specified mempool.
+ /*!
+ @param stack A pointer to the tStack to be freed.
+ @param pool A pointer to the tMempool from which the tStack should be freed.
+ */
+ void tStack_freeFromPool (tStack* const stack, tMempool* const pool);
+
+ //! Set the capacity of the stack.
+ /*!
+ @param stack A pointer to the relevant tStack.
+ @param cap The new capacity.
+ */
+ void tStack_setCapacity (tStack* const stack, uint16_t cap);
+
+
+ //! Add a value to the stack only if that value is not already in the stack.
+ /*!
+ @param stack A pointer to the relevant tStack.
+ @param item The value to be added.
+ */
+ int tStack_addIfNotAlreadyThere (tStack* const stack, uint16_t item);
+
+
+ //! Add a value to the stack.
+ /*!
+ @param stack A pointer to the relevant tStack.
+ @param item The value to be added.
+ */
+ void tStack_add (tStack* const stack, uint16_t item);
+
+
+ //! Remove a single instance of a value from the stack.
+ /*!
+ @param stack A pointer to the relevant tStack.
+ @param item The value to be removed.
+ */
+ int tStack_remove (tStack* const stack, uint16_t item);
+
+
+ //! Clear the stack.
+ /*!
+ @param stack A pointer to the relevant tStack.
+ */
+ void tStack_clear (tStack* const stack);
+
+
+ //! Get the first value in the stack.
+ /*!
+ @param stack A pointer to the relevant tStack.
+ @return The first value in the stack.
+ */
+ int tStack_first (tStack* const stack);
+
+
+ //! Get the current size of the stack.
+ /*!
+ @param stack A pointer to the relevant tStack.
+ @return The current size of the stack.
+ */
+ int tStack_getSize (tStack* const stack);
+
+ //! Check if the stack contains a value, and if it does, get the index of that value.
+ /*!
+ @param stack A pointer to the relevant tStack.
+ @param item The value to check against the stack.
+ @return The index of the value or -1 if the stack does not contain the value.
+ */
+ int tStack_contains (tStack* const stack, uint16_t item);
+
+ //! Get the next value in the stack, starting from the earliest added values.
+ /*!
+ @param stack A pointer to the relevant tStack.
+ @return The next value in the stack or -1 if there are no values in the stack.
+ */
+ int tStack_next (tStack* const stack);
+
+ //! Get the value at a given index of the stack.
+ /*!
+ @param stack A pointer to the relevant tStack.
+ @param index The index of the stack from which to get a value.
+ @return The value at the given index.
+ */
+ int tStack_get (tStack* const stack, int index);
+
+ /*! @} */
+
+ /*!
+ * @defgroup tpoly tPoly
+ * @ingroup midi
+ * @brief An object for polyphonic handling.
+ * @{
+ */
+
/* tPoly */
typedef struct _tPoly
{
@@ -93,32 +207,159 @@
typedef _tPoly* tPoly;
/* MPoly*/
- void tPoly_init (tPoly* const, int maxNumVoices);
- void tPoly_free (tPoly* const);
- void tPoly_initToPool (tPoly* const, int maxNumVoices, tMempool* const);
- void tPoly_freeFromPool (tPoly* const, tMempool* const);
+ //! Initialize a tPoly to the default LEAF mempool.
+ /*!
+ @param poly A pointer to the tPoly to be initialized.
+ @param maxNumVoices The maximum number of voices this tPoly can handle at once.
+ */
+ void tPoly_init (tPoly* const poly, int maxNumVoices);
- //ADDING A NOTE
- int tPoly_noteOn (tPoly* const, int note, uint8_t vel);
- int tPoly_noteOff (tPoly* const, uint8_t note);
- void tPoly_orderedAddToStack (tPoly* const, uint8_t noteVal);
- void tPoly_setNumVoices (tPoly* const, uint8_t numVoices);
- void tPoly_setPitchBend (tPoly* const, float pitchBend);
- void tPoly_setPitchGlideActive (tPoly* const, oBool isActive);
- void tPoly_setPitchGlideTime (tPoly* const, float t);
- void tPoly_setBendGlideTime (tPoly* const polyh, float t);
- void tPoly_setBendSamplesPerTick (tPoly* const polyh, float t);
- void tPoly_tickPitch (tPoly* const);
- void tPoly_tickPitchGlide (tPoly* const);
- void tPoly_tickPitchBend (tPoly* const);
+ //! Free a tPoly from the default LEAF mempool.
+ /*!
+ @param poly A pointer to the tPoly to be freed.
+ */
+ void tPoly_free (tPoly* const poly);
- int tPoly_getNumVoices (tPoly* const);
- int tPoly_getNumActiveVoices (tPoly* const);
- float tPoly_getPitch (tPoly* const, uint8_t voice);
- int tPoly_getKey (tPoly* const, uint8_t voice);
- int tPoly_getVelocity (tPoly* const, uint8_t voice);
- int tPoly_isOn (tPoly* const, uint8_t voice);
+
+ //! Initialize a tPoly to a specified mempool.
+ /*!
+ @param poly A pointer to the tPoly to be initialized.
+ @param pool A pointer to the tMempool to which the tPoly should be initialized.
+ */
+ void tPoly_initToPool (tPoly* const poly, int maxNumVoices, tMempool* const pool);
+
+
+ //! Free a tPoly from a specified mempool.
+ /*!
+ @param poly A pointer to the tPoly to be freed.
+ @param pool A pointer to the tMempool from which the tPoly should be freed.
+ */
+ void tPoly_freeFromPool (tPoly* const poly, tMempool* const pool);
+
+ //! Add a note with a given velocity to the poly handler.
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ @param note The MIDI note number to add.
+ @param vel The MIDI velocity of the note to add.
+ @return The voice that will play the note.
+ */
+ int tPoly_noteOn (tPoly* const poly, int note, uint8_t vel);
+
+
+ //! Remove a note from the poly handler.
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ @param note The MIDI note number to remove.
+ @return The voice that was playing the removed note.
+ */
+ int tPoly_noteOff (tPoly* const poly, uint8_t note);
+
+ void tPoly_orderedAddToStack (tPoly* const poly, uint8_t note);
+
+
+ //! Set the number of voices available to play notes.
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ @param numVoices The new number of available voices. Cannot be greater than the max number voices given in tPoly_init().
+ */
+ void tPoly_setNumVoices (tPoly* const poly, uint8_t numVoices);
+
+ //! Set whether pitch glide over note changes in voices is active.
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ @param isActive Whether pitch glide should be active or not.
+ */
+ void tPoly_setPitchGlideActive (tPoly* const poly, oBool isActive);
+
+ //! Set how long pitch glide over note changes in voices takes.
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ @param t The time to glide in milliseconds.
+ */
+ void tPoly_setPitchGlideTime (tPoly* const poly, float t);
+
+ //! Set the amount of pitch bend
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ @param pitchBend The new amount of pitch bend.
+ */
+ void tPoly_setPitchBend (tPoly* const poly, float pitchBend);
+ void tPoly_setBendGlideTime (tPoly* const poly, float t);
+ void tPoly_setBendSamplesPerTick (tPoly* const poly, float t);
+
+
+ //! Execute all tick-rate changes in the poly handler's pitch, including glide and bend.
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ */
+ void tPoly_tickPitch (tPoly* const poly);
+
+
+ //! Execute the tick-rate change of the poly handler's pitch glide.
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ */
+ void tPoly_tickPitchGlide (tPoly* const poly);
+
+
+ //! Execute the tick-rate change of the poly handler's pitch bend.
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ */
+ void tPoly_tickPitchBend (tPoly* const poly);
+
+
+ //! Get the current number of voices available to play notes.
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ @return The current number of voices available to play notes.
+ */
+ int tPoly_getNumVoices (tPoly* const poly);
+
+ //! Get the number of voices currently playing notes.
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ @return The number of voices currently playing notes.
+ */
+ int tPoly_getNumActiveVoices (tPoly* const poly);
+
+ //! Get the current pitch of a given voice.
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ @param voice The voice to get the pitch of.
+ @return The current pitch of the given voice as a fractional MIDI note number.
+ */
+ float tPoly_getPitch (tPoly* const poly, uint8_t voice);
+
+
+ //! Get the current MIDI note number of a given voice.
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ @param voice The voice to get the MIDI note number of.
+ @return The MIDI note number of the given voice.
+ */
+ int tPoly_getKey (tPoly* const poly, uint8_t voice);
+
+
+ //! Get the current MIDI velocity of a given voice.
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ @param voice The voice to get the MIDI velocity of.
+ @return The current MIDI velocity of the given voice.
+ */
+ int tPoly_getVelocity (tPoly* const poly, uint8_t voice);
+
+
+ //! Get the current play state of a given voice.
+ /*!
+ @param poly A pointer to the relevant tPoly.
+ @param voice The voice to get the state of.
+ @return The current play state of the given voice.
+ */
+ int tPoly_isOn (tPoly* const poly, uint8_t voice);
+
+ /*! @} */
//==============================================================================
--- a/LEAF/Inc/leaf-oscillators.h
+++ b/LEAF/Inc/leaf-oscillators.h
@@ -24,19 +24,8 @@
* An example.
*/
- /*!
- * @defgroup oscillators Oscillators
- */
-
//==============================================================================
- /*!
- * @ingroup oscillators
- * @defgroup tcycle tCycle
- * A cycle/sine waveform oscillator. Uses wavetable synthesis.
- * @{
- */
-
typedef struct _tCycle
{
// Underlying phasor
@@ -47,14 +36,21 @@
typedef _tCycle* tCycle;
- //! Initializes a tCycle to the default LEAF mempool.
/*!
+ * @defgroup tcycle tCycle
+ * @ingroup oscillators
+ * @brief A cycle/sine waveform oscillator. Uses wavetable synthesis.
+ * @{
+ */
+
+ //! Initialize a tCycle to the default LEAF mempool.
+ /*!
@param osc A pointer to the tCycle to be initialized.
*/
void tCycle_init (tCycle* const osc);
- //! Frees a tCycle from the default LEAF mempool.
+ //! Free a tCycle from the default LEAF mempool.
/*!
@param osc A pointer to the tCycle to be freed.
*/
@@ -61,7 +57,7 @@
void tCycle_free (tCycle* const osc);
- //! Initializes a tCycle to a specified mempool.
+ //! Initialize a tCycle to a specified mempool.
/*!
@param osc A pointer to the tCycle to be initialized.
@param pool A pointer to the tMempool to which the tCycle should be initialized.
@@ -69,7 +65,7 @@
void tCycle_initToPool (tCycle* const osc, tMempool* const pool);
- //! Frees a tCycle from a specified mempool.
+ //! Free a tCycle from a specified mempool.
/*!
@param osc A pointer to the tCycle to be freed.
@param pool A pointer to the tMempool from which the tCycle should be freed.
@@ -80,7 +76,7 @@
//! Tick a tCycle oscillator.
/*!
@param osc A pointer to the relevant tCycle.
- @return The ticked sample.
+ @return The ticked sample as a float from -1 to 1.
*/
float tCycle_tick (tCycle* const osc);
@@ -94,15 +90,9 @@
/*! @} */
+
//==============================================================================
- /*!
- * @ingroup oscillators
- * @defgroup ttriangle tTriangle
- * An anti-aliased triangle waveform oscillator. Uses wavetable synthesis.
- * @{
- */
-
/* tTriangle: Anti-aliased Triangle waveform using wavetable interpolation. Wavetables constructed from sine components. */
typedef struct _tTriangle
{
@@ -114,14 +104,21 @@
typedef _tTriangle* tTriangle;
- //! Initializes a tTriangle to the default LEAF mempool.
/*!
+ * @defgroup ttriangle tTriangle
+ * @ingroup oscillators
+ * @brief An anti-aliased triangle waveform oscillator. Uses wavetable synthesis.
+ * @{
+ */
+
+ //! Initialize a tTriangle to the default LEAF mempool.
+ /*!
@param osc A pointer to the tTriangle to be initialized.
*/
void tTriangle_init (tTriangle* const osc);
- //! Frees a tTriangle from the default LEAF mempool.
+ //! Free a tTriangle from the default LEAF mempool.
/*!
@param osc A pointer to the tTriangle to be freed.
*/
@@ -128,7 +125,7 @@
void tTriangle_free (tTriangle* const osc);
- //! Initializes a tTriangle to a specified mempool.
+ //! Initialize a tTriangle to a specified mempool.
/*!
@param osc A pointer to the tTriangle to be initialized.
@param pool A pointer to the tMempool to which the tTriangle should be initialized.
@@ -136,7 +133,7 @@
void tTriangle_initToPool (tTriangle* const osc, tMempool* const pool);
- //! Frees a tTriangle from a specified mempool.
+ //! Free a tTriangle from a specified mempool.
/*!
@param osc A pointer to the tTriangle to be freed.
@param pool A pointer to the tMempool from which the tTriangle should be freed.
@@ -147,7 +144,7 @@
//! Tick a tTriangle oscillator.
/*!
@param osc A pointer to the relevant tTriangle.
- @return The ticked sample.
+ @return The ticked sample as a float from -1 to 1.
*/
float tTriangle_tick (tTriangle* const osc);
@@ -163,13 +160,6 @@
//==============================================================================
- /*!
- * @ingroup oscillators
- * @defgroup tsquare tSquare
- * An anti-aliased square waveform oscillator. Uses wavetable synthesis.
- * @{
- */
-
/* tSquare: Anti-aliased Square waveform using wavetable interpolation. Wavetables constructed from sine components. */
typedef struct _tSquare
{
@@ -181,14 +171,21 @@
typedef _tSquare* tSquare;
- //! Initializes a tSquare to the default LEAF mempool.
/*!
+ * @defgroup tsquare tSquare
+ * @ingroup oscillators
+ * @brief An anti-aliased square waveform oscillator. Uses wavetable synthesis.
+ * @{
+ */
+
+ //! Initialize a tSquare to the default LEAF mempool.
+ /*!
@param osc A pointer to the tSquare to be initialized.
*/
void tSquare_init (tSquare* const osc);
- //! Frees a tSquare from the default LEAF mempool.
+ //! Free a tSquare from the default LEAF mempool.
/*!
@param osc A pointer to the tSquare to be freed.
*/
@@ -195,7 +192,7 @@
void tSquare_free (tSquare* const osc);
- //! Initializes a tSquare to a specified mempool.
+ //! Initialize a tSquare to a specified mempool.
/*!
@param osc A pointer to the tSquare to be initialized.
@param pool A pointer to the tMempool to which the tSquare should be initialized.
@@ -203,7 +200,7 @@
void tSquare_initToPool (tSquare* const osc, tMempool* const);
- //! Frees a tSquare from a specified mempool.
+ //! Free a tSquare from a specified mempool.
/*!
@param osc A pointer to the tSquare to be freed.
@param pool A pointer to the tMempool from which the tSquare should be freed.
@@ -214,7 +211,7 @@
//! Tick a tSquare oscillator.
/*!
@param osc A pointer to the relevant tSquare.
- @return The ticked sample.
+ @return The ticked sample as a float from -1 to 1.
*/
float tSquare_tick (tSquare* const osc);
@@ -226,6 +223,8 @@
*/
int tSquare_setFreq (tSquare* const osc, float freq);
+ /*! @} */
+
//==============================================================================
/* tSawtooth: Anti-aliased Sawtooth waveform using wavetable interpolation. Wavetables constructed from sine components. */
@@ -239,14 +238,60 @@
typedef _tSawtooth* tSawtooth;
+ /*!
+ * @defgroup tsawtooth tSawtooth
+ * @ingroup oscillators
+ * @brief An anti-aliased sawtooth waveform oscillator. Uses wavetable synthesis.
+ * @{
+ */
+
+ //! Initialize a tSawtooth to the default LEAF mempool.
+ /*!
+ @param osc A pointer to the tSawtooth to be initialized.
+ */
void tSawtooth_init (tSawtooth* const osc);
+
+
+ //! Free a tSawtooth from the default LEAF mempool.
+ /*!
+ @param osc A pointer to the tSawtooth to be freed.
+ */
void tSawtooth_free (tSawtooth* const osc);
- void tSawtooth_initToPool (tSawtooth* const osc, tMempool* const);
- void tSawtooth_freeFromPool (tSawtooth* const osc, tMempool* const);
+
+ //! Initialize a tSawtooth to a specified mempool.
+ /*!
+ @param osc A pointer to the tSawtooth to be initialized.
+ @param pool A pointer to the tMempool to which the tSawtooth should be initialized.
+ */
+ void tSawtooth_initToPool (tSawtooth* const osc, tMempool* const pool);
+
+
+ //! Free a tSawtooth from a specified mempool.
+ /*!
+ @param osc A pointer to the tSawtooth to be freed.
+ @param pool A pointer to the tMempool from which the tSawtooth should be freed.
+ */
+ void tSawtooth_freeFromPool (tSawtooth* const osc, tMempool* const pool);
+
+
+ //! Tick a tSawtooth oscillator.
+ /*!
+ @param osc A pointer to the relevant tSawtooth.
+ @return The ticked sample as a float from -1 to 1.
+ */
float tSawtooth_tick (tSawtooth* const osc);
+
+
+ //! Set the frequency of a tSawtooth oscillator.
+ /*!
+ @param osc A pointer to the relevant tSawtooth.
+ @param freq The frequency to set the oscillator to.
+ */
int tSawtooth_setFreq (tSawtooth* const osc, float freq);
+ /*! @} */
+
//==============================================================================
/* tPhasor: Aliasing phasor [0.0, 1.0) */
@@ -259,24 +304,82 @@
typedef _tPhasor* tPhasor;
+ /*!
+ * @defgroup tphasor Phasor
+ * @ingroup oscillators
+ * @brief An aliasing phasor.
+ * @{
+ */
+
+ //! Initialize a tPhasor to the default LEAF mempool.
+ /*!
+ @param osc A pointer to the tPhasor to be initialized.
+ */
void tPhasor_init (tPhasor* const osc);
+
+
+ //! Free a tPhasor from the default LEAF mempool.
+ /*!
+ @param osc A pointer to the tPhasor to be freed.
+ */
void tPhasor_free (tPhasor* const osc);
+
+
+ //! Initialize a tPhasor to a specified mempool.
+ /*!
+ @param osc A pointer to the tPhasor to be initialized.
+ @param pool A pointer to the tMempool to which the tPhasor should be initialized.
+ */
void tPhasor_initToPool (tPhasor* const osc, tMempool* const);
+
+
+ //! Free a tPhasor from a specified mempool.
+ /*!
+ @param osc A pointer to the tPhasor to be freed.
+ @param pool A pointer to the tMempool from which the tPhasor should be freed.
+ */
void tPhasor_freeFromPool(tPhasor* const osc, tMempool* const);
+
+ //! Tick a tPhasor oscillator.
+ /*!
+ @param osc A pointer to the relevant tPhasor.
+ @return The ticked sample as a float from 0 to 1.
+ */
float tPhasor_tick (tPhasor* const osc);
+
+
+ //! Set the frequency of a tPhasor oscillator.
+ /*!
+ @param osc A pointer to the relevant tPhasor.
+ @param freq The frequency to set the oscillator to.
+ */
int tPhasor_setFreq (tPhasor* const osc, float freq);
+ /*! @} */
+
//==============================================================================
+ /*!
+ * @defgroup tnoise tNoise
+ * @ingroup oscillators
+ * @brief A noise generator.
+ * @{
+ */
+
/* tNoise. WhiteNoise, PinkNoise. */
- typedef enum NoiseType
+ /*!
+ * Noise types
+ */
+ enum NoiseType
{
- WhiteNoise=0,
- PinkNoise,
+ WhiteNoise, //!< White noise. Full spectrum.
+ PinkNoise, //!< Pink noise. Inverse frequency-proportional spectrum.
NoiseTypeNil,
- } NoiseType;
+ };
+ typedef enum NoiseType NoiseType;
+
typedef struct _tNoise
{
NoiseType type;
@@ -287,23 +390,65 @@
typedef _tNoise* tNoise;
+ //! Initialize a tNoise to the default LEAF mempool.
+ /*!
+ @param osc A pointer to the tNoise to be initialized.
+ */
void tNoise_init (tNoise* const noise, NoiseType type);
+
+
+ //! Free a tNoise from the default LEAF mempool.
+ /*!
+ @param osc A pointer to the tNoise to be freed.
+ */
void tNoise_free (tNoise* const noise);
+
+
+ //! Initialize a tNoise to a specified mempool.
+ /*!
+ @param osc A pointer to the tNoise to be initialized.
+ @param pool A pointer to the tMempool to which the tNoise should be initialized.
+ */
void tNoise_initToPool (tNoise* const noise, NoiseType type, tMempool* const);
+
+
+ //! Free a tNoise from a specified mempool.
+ /*!
+ @param osc A pointer to the tNoise to be freed.
+ @param pool A pointer to the tMempool from which the tNoise should be freed.
+ */
void tNoise_freeFromPool (tNoise* const noise, tMempool* const);
+
+ //! Tick a tNoise oscillator.
+ /*!
+ @param osc A pointer to the relevant tNoise.
+ @return The ticked sample as a float from -1 to 1.
+ */
float tNoise_tick (tNoise* const noise);
+ /*! @} */
+
//==============================================================================
- /* tNeuron */
- typedef enum NeuronMode
+ /*!
+ * @defgroup tneuron tNeuron
+ * @ingroup oscillators
+ * @brief A model of a neuron, adapted to act as an oscillator.
+ * @{
+ */
+
+ /*!
+ * Neuron modes
+ */
+ enum NeuronMode
{
- NeuronNormal = 0,
- NeuronTanh,
- NeuronAaltoShaper,
+ NeuronNormal, //!< Normal operation
+ NeuronTanh, //!< Tanh voltage shaping
+ NeuronAaltoShaper, //!< Aalto voltage shaping
NeuronModeNil
- } NeuronMode;
+ };
+ typedef enum NeuronMode NeuronMode;
typedef struct _tNeuron
{
@@ -324,23 +469,131 @@
typedef _tNeuron* tNeuron;
+ //! Initialize a tNeuron to the default LEAF mempool.
+ /*!
+ @param neuron A pointer to the tNeuron to be initialized.
+ */
void tNeuron_init (tNeuron* const neuron);
+
+
+ //! Free a tNeuron from the default LEAF mempool.
+ /*!
+ @param neuron A pointer to the tNeuron to be freed.
+ */
void tNeuron_free (tNeuron* const neuron);
- void tNeuron_initToPool (tNeuron* const neuron, tMempool* const);
- void tNeuron_freeFromPool(tNeuron* const neuron, tMempool* const);
+
+ //! Initialize a tNeuron to a specified mempool.
+ /*!
+ @param neuron A pointer to the tNeuron to be initialized.
+ @param pool A pointer to the tMempool to which the tNeuron should be initialized.
+ */
+ void tNeuron_initToPool (tNeuron* const neuron, tMempool* const pool);
+
+
+ //! Free a tNeuron from a specified mempool.
+ /*!
+ @param neuron A pointer to the tNeuron to be freed.
+ @param pool A pointer to the tMempool from which the tNeuron should be freed.
+ */
+ void tNeuron_freeFromPool(tNeuron* const neuron, tMempool* const pool);
+
+
+ //! Reset the neuron model.
+ /*!
+ @param neuron A pointer to the relevant tNeuron.
+ */
void tNeuron_reset (tNeuron* const neuron);
+
+
+ //! Tick a tNeuron oscillator.
+ /*!
+ @param neuron A pointer to the relevant tNeuron.
+ @return The ticked sample as a float from -1 to 1.
+ */
float tNeuron_tick (tNeuron* const neuron);
+
+
+ //! Set the tNeuron shaping mode.
+ /*!
+ @param neuron A pointer to the relevant tNeuron.
+ @param mode The mode to set the tNeuron to.
+ */
void tNeuron_setMode (tNeuron* const neuron, NeuronMode mode);
+
+
+ //! Set the current.
+ /*!
+ @param neuron A pointer to the relevant tNeuron.
+ @param current The new current.
+ */
void tNeuron_setCurrent (tNeuron* const neuron, float current);
+
+
+ //! Set the potassium value.
+ /*!
+ @param neuron A pointer to the relevant tNeuron.
+ @param K The new potassium.
+ */
void tNeuron_setK (tNeuron* const neuron, float K);
+
+
+ //! Set the chloride value.
+ /*!
+ @param neuron A pointer to the relevant tNeuron.
+ @param L The new chloride value.
+ */
void tNeuron_setL (tNeuron* const neuron, float L);
+
+
+ //! Set the sodium value.
+ /*!
+ @param neuron A pointer to the relevant tNeuron.
+ @param N The new sodium value.
+ */
void tNeuron_setN (tNeuron* const neuron, float N);
+
+
+ //! Set the calcium value.
+ /*!
+ @param neuron A pointer to the relevant tNeuron.
+ @param C The new calcium.
+ */
void tNeuron_setC (tNeuron* const neuron, float C);
+
+
+ //! Set the V1 value.
+ /*!
+ @param neuron A pointer to the relevant tNeuron.
+ @param V1 The new V1.
+ */
void tNeuron_setV1 (tNeuron* const neuron, float V1);
+
+
+ //! Set the V2 value.
+ /*!
+ @param neuron A pointer to the relevant tNeuron.
+ @param V2 The new V2.
+ */
void tNeuron_setV2 (tNeuron* const neuron, float V2);
+
+
+ //! Set the V3 value.
+ /*!
+ @param neuron A pointer to the relevant tNeuron.
+ @param V3 The new V3.
+ */
void tNeuron_setV3 (tNeuron* const neuron, float V3);
+
+
+ //! Set the time step.
+ /*!
+ @param neuron A pointer to the relevant tNeuron.
+ @param timestep The new time step
+ */
void tNeuron_setTimeStep (tNeuron* const neuron, float timestep);
+
+ /*! @} */
//==============================================================================
--- a/LEAF/Inc/leaf-physical.h
+++ b/LEAF/Inc/leaf-physical.h
@@ -26,6 +26,14 @@
#include "leaf-envelopes.h"
#include "leaf-dynamics.h"
+ /*!
+ * @internal
+ * Header.
+ * @include basic-oscillators.h
+ * @example basic-oscillators.c
+ * An example.
+ */
+
//==============================================================================
/* Karplus Strong model */
--- a/LEAF/Inc/leaf-reverb.h
+++ b/LEAF/Inc/leaf-reverb.h
@@ -22,6 +22,14 @@
#include "leaf-filters.h"
#include "leaf-oscillators.h"
+ /*!
+ * @internal
+ * Header.
+ * @include basic-oscillators.h
+ * @example basic-oscillators.c
+ * An example.
+ */
+
//==============================================================================
/* PRCReverb: Reverb, reimplemented from STK (Cook and Scavone). */
--- a/LEAF/Inc/leaf-sampling.h
+++ b/LEAF/Inc/leaf-sampling.h
@@ -23,6 +23,14 @@
#include "leaf-mempool.h"
#include "leaf-analysis.h"
+ /*!
+ * @internal
+ * Header.
+ * @include basic-oscillators.h
+ * @example basic-oscillators.c
+ * An example.
+ */
+
//==============================================================================
typedef enum RecordMode
--- a/LEAF/Src/leaf-oscillators.c
+++ b/LEAF/Src/leaf-oscillators.c
@@ -26,9 +26,7 @@
void tCycle_free(tCycle* const cy)
{
- _tCycle* c = *cy;
-
- leaf_free(c);
+ tCycle_freeFromPool(cy, &leaf.mempool);
}
void tCycle_initToPool (tCycle* const cy, tMempool* const mp)
@@ -96,17 +94,12 @@
/* Triangle */
void tTriangle_init(tTriangle* const cy)
{
- _tTriangle* c = *cy = (_tTriangle*) leaf_alloc(sizeof(_tTriangle));
-
- c->inc = 0.0f;
- c->phase = 0.0f;
+ tTriangle_initToPool(cy, &leaf.mempool);
}
void tTriangle_free(tTriangle* const cy)
{
- _tTriangle* c = *cy;
-
- leaf_free(c);
+ tTriangle_freeFromPool(cy, &leaf.mempool);
}
void tTriangle_initToPool (tTriangle* const cy, tMempool* const mp)
@@ -227,17 +220,12 @@
/* Square */
void tSquare_init(tSquare* const cy)
{
- _tSquare* c = *cy = (_tSquare*) leaf_alloc(sizeof(_tSquare));
-
- c->inc = 0.0f;
- c->phase = 0.0f;
+ tSquare_initToPool(cy, &leaf.mempool);
}
void tSquare_free(tSquare* const cy)
{
- _tSquare* c = *cy;
-
- leaf_free(c);
+ tSquare_freeFromPool(cy, &leaf.mempool);
}
void tSquare_initToPool (tSquare* const cy, tMempool* const mp)
@@ -356,17 +344,12 @@
// Sawtooth
void tSawtooth_init(tSawtooth* const cy)
{
- _tSawtooth* c = *cy = (_tSawtooth*) leaf_alloc(sizeof(_tSawtooth));
-
- c->inc = 0.0f;
- c->phase = 0.0f;
+ tSawtooth_initToPool(cy, &leaf.mempool);
}
void tSawtooth_free(tSawtooth* const cy)
{
- _tSawtooth* c = *cy;
-
- leaf_free(c);
+ tSawtooth_freeFromPool(cy, &leaf.mempool);
}
void tSawtooth_initToPool (tSawtooth* const cy, tMempool* const mp)
@@ -493,17 +476,12 @@
void tPhasor_init(tPhasor* const ph)
{
- _tPhasor* p = *ph = (_tPhasor*) leaf_alloc(sizeof(_tPhasor));
-
- p->phase = 0.0f;
- p->inc = 0.0f;
+ tPhasor_initToPool(ph, &leaf.mempool);
}
void tPhasor_free(tPhasor* const ph)
{
- _tPhasor* p = *ph;
-
- leaf_free(p);
+ tPhasor_freeFromPool(ph, &leaf.mempool);
}
void tPhasor_initToPool (tPhasor* const ph, tMempool* const mp)
@@ -549,17 +527,12 @@
/* Noise */
void tNoise_init(tNoise* const ns, NoiseType type)
{
- _tNoise* n = *ns = (_tNoise*) leaf_alloc(sizeof(_tNoise));
-
- n->type = type;
- n->rand = leaf.random;
+ tNoise_initToPool(ns, type, &leaf.mempool);
}
void tNoise_free(tNoise* const ns)
{
- _tNoise* n = *ns;
-
- leaf_free(n);
+ tNoise_freeFromPool(ns, &leaf.mempool);
}
void tNoise_initToPool (tNoise* const ns, NoiseType type, tMempool* const mp)
@@ -610,41 +583,12 @@
void tNeuron_init(tNeuron* const nr)
{
- _tNeuron* n = *nr = (_tNeuron*) leaf_alloc(sizeof(_tNeuron));
-
- tPoleZero_init(&n->f);
-
- tPoleZero_setBlockZero(&n->f, 0.99f);
-
- n->timeStep = 1.0f / 50.0f;
-
- n->current = 0.0f; // 100.0f for sound
- n->voltage = 0.0f;
-
- n->mode = NeuronNormal;
-
- n->P[0] = 0.0f;
- n->P[1] = 0.0f;
- n->P[2] = 1.0f;
-
- n->V[0] = -12.0f;
- n->V[1] = 115.0f;
- n->V[2] = 10.613f;
-
- n->gK = 36.0f;
- n->gN = 120.0f;
- n->gL = 0.3f;
- n->C = 1.0f;
-
- n->rate[2] = n->gL/n->C;
+ tNeuron_initToPool(nr, &leaf.mempool);
}
void tNeuron_free(tNeuron* const nr)
{
- _tNeuron* n = *nr;
-
- tPoleZero_free(&n->f);
- leaf_free(n);
+ tNeuron_freeFromPool(nr, &leaf.mempool);
}
void tNeuron_initToPool (tNeuron* const nr, tMempool* const mp)
--- a/LEAF/leaf.h
+++ b/LEAF/leaf.h
@@ -1,13 +1,13 @@
/*
- ==============================================================================
+ ==============================================================================
+
+ leaf.h
+ Created: 20 Jan 2017 12:07:26pm
+ Author: Michael R Mulshine
+
+ ==============================================================================
+ */
- leaf.h
- Created: 20 Jan 2017 12:07:26pm
- Author: Michael R Mulshine
-
- ==============================================================================
-*/
-
#ifndef LEAF_H_INCLUDED
#define LEAF_H_INCLUDED
@@ -74,16 +74,64 @@
* etc...
*/
+/*!
+ * @defgroup leaf LEAF
+ * @defgroup oscillators Oscillators
+ * @defgroup filters Filters
+ * @defgroup delay Delay
+ * @defgroup reverb Reverb
+ * @defgroup distortion Distortion
+ * @defgroup effects Effects
+ * @defgroup envelopes Envelopes
+ * @defgroup dynamics Dynamics
+ * @defgroup analysis Analysis
+ * @defgroup instruments Instruments
+ * @defgroup midi MIDI
+ * @defgroup sampling Sampling
+ * @defgroup physical Physical Models
+ * @defgroup electrical Electrical Models
+ * @defgroup mempool Mempool
+ * @defgroup math Math
+ */
+
#ifdef __cplusplus
extern "C" {
#endif
-void LEAF_init (float sampleRate, int blocksize, char* memory, size_t memorysize, float(*randomNumberFunction)(void));
-void LEAF_setSampleRate (float sampleRate);
-float LEAF_getSampleRate (void);
-
+ /*!
+ * @ingroup leaf
+ * @{
+ */
+
+ //! Initialize the LEAF instance.
+ /*!
+ @param sampleRate The audio sample rate.
+ @param blockSize The audio block size.
+ @param memory A pointer to the memory that will make up the default LEAF mempool.
+ @param memorySize The size of the memory that will make up the default LEAF mempool.
+ @param random A pointer to a random number function. Should return a float >= 0 and < 1.
+ */
+ void LEAF_init (float sampleRate, int blockSize, char* memory, size_t memorySize, float(*random)(void));
+
+ //! Set the sample rate of LEAF.
+ /*!
+ @param sampleRate The new audio sample rate.
+ */
+ void LEAF_setSampleRate (float sampleRate);
+
+ //! Get the sample rate of LEAF.
+ /*!
+ @return The current sample rate as a float.
+ */
+ float LEAF_getSampleRate (void);
+
+ /*!
+ * @}
+ */
+
#ifdef __cplusplus
}
#endif
#endif // LEAF_H_INCLUDED
+