# OvertoneDistribution class

Container for data describing the overtones of a sound.

### Contents

This object contains:

- A list of Partial objects representing the overtones of a sound, ordered by ascending frequency ratio to the fundamental partial.
- A Partial object representing the fundamental partial, initialized with real frequency (in Hz) and amplitude (or loudness) values.
- The mute status of both the entire overtone distribution and inidividual partials.

## Constructors, destructors, conversion operators

- OvertoneDistribution ()
- Creates an empty OvertoneDistribution object.
- OvertoneDistribution (const OvertoneDistribution& otherDistribution)
- Creates a copy of an existing OvertoneDistribution object.
- ~OvertoneDistribution ()
- Destructor.

## Public functions

- auto operator= (const OvertoneDistribution& otherDistribution) -> OvertoneDistribution&
- Copy assignment operator.
- auto numPartials () const -> int noexcept
- Returns the number of partials in the distribution including the fundamental.
- void setDistributionName (String newName) noexcept
- Sets a name for the overtone distribution.
- auto getName () const -> String noexcept
- Returns the overtone distribution's name.
- void addPartial ()
- Adds an empty partial.
- void addPartial (float FreqRatio, float AmpRatio)
- Adds a new partial and sorts partials by ascending frequency.
- void setFreqRatio (int partialNum, float newFreqRatio)
- Sets a partial's frequency relative to the fundamental frequency.
- void setAmpRatio (int partialNum, float newAmpRatio)
- Sets a partial's amplitude relative to the amplitude of the fundamental.
- auto getFreqRatio (int partialNum) const -> float
- Returns a partial's frequency relative to the fundamental frequency.
- auto getAmpRatio (int partialNum) const -> float
- Returns a partial's amplitude relative to the fundamental's amplitude.
- auto getRealFreq (int partialNum) const -> float
- Returns a partial's real frequency in Hz.
- auto getRealAmp (int partialNum) const -> float
- Returns a partial's real amplitude.
- void removePartial (int partialNum)
- Removes a partial.
- void clearPartials ()
- Removes all partials.
- void setFundamental (float fundamentalFreq, float fundamentalAmp) noexcept
- Sets values for the fundamental's frequency and amplitude.
- void setFundamentalFreq (float newFundamentalFreq) noexcept
- Sets a real value for the fundamental frequency.
- void setFundamentalAmp (float newFundamentalAmp) noexcept
- Sets a real value for the fundamental's amplitude.
- auto getFundamentalFreq () const -> float noexcept
- Returns the fundamental frequency.
- auto getFundamentalAmp () const -> float noexcept
- Returns the fundamental's amplitude.
- void mute (bool mute) noexcept
- Sets the mute status of the overtone distribution.
- void mutePartial (int partialNum, bool mute)
- Sets whether to mute a partial, excluding it from dissonance calculations.
- void muteFundamental (bool mute) noexcept
- Sets the mute status of the fundamental.
- auto isMuted () const -> bool noexcept
- Returns true if the overtone distribution should be muted or excluded from dissonance calculations.
- auto partialIsMuted (int partialNum) const -> bool
- Returns true if the partial should be muted and excluded from dissonance calculations.
- auto fundamentalIsMuted () const -> bool noexcept
- Returns true if the fundamental is muted.
- void addPartialDissonance (int partialNum, float dissonanceToAdd)
- Adds dissonance to partial's dissonance value.
- void addDissonanceToFundamental (float dissonanceToAdd) noexcept
- Adds dissonance to the total dissonance of the fundamental partial.
- auto getPartialDissonance (int partialNum) const -> float
- Returns the dissonance of a partial.
- auto getDissonanceOfFundamental () const -> float noexcept
- Returns the dissonance of the fundamental partial.
- auto getTotalDissonance () const -> float noexcept
- Returns the sum of all partial dissonances.
- void clearPartialDissonances ()
- Sets all partial dissonance values to zero.
- void setMinInterval (float newMinInteval) noexcept
- Sets the minimum frequency interval between any two partials.
- auto getMinInterval () const -> float noexcept
- Returns the minimum frequency interval between any two partials.

## Protected functions

- auto alreadyContains (double freqToCheck) const -> bool
- Returns true if a partial in the distribution already has the input frequency.
- auto tooCloseToOther (double freqToCheck) const -> bool
- Returns true if the input partial is closer in frequency to another partial than the minimum interval permits.

## Function documentation

###
void OvertoneDistribution:: addPartial ()

Adds an empty partial.

The partial's frequency and amplitude ratios must be set by calling setFreqRatio and setAmpRatio before dissonance calculations can use the distribution.

###
void OvertoneDistribution:: addPartial (float FreqRatio,
float AmpRatio)

Adds a new partial and sorts partials by ascending frequency.

Frequencies and amplitudes of overtone partials should have values greater than zero that represent a ratio to the fundamental's (or the most salient partial's) frequency and amplitude, as in

and

###
void OvertoneDistribution:: setFreqRatio (int partialNum,
float newFreqRatio)

Sets a partial's frequency relative to the fundamental frequency.

Parameters | |
---|---|

partialNum | The index of the partial whose frequency is being set. |

newFreqRatio | The new frequency ratio between this partial and the fundamental. |

###
void OvertoneDistribution:: setAmpRatio (int partialNum,
float newAmpRatio)

Sets a partial's amplitude relative to the amplitude of the fundamental.

###
float OvertoneDistribution:: getRealFreq (int partialNum) const

Returns a partial's real frequency in Hz.

Multiplies the partial's frequency ratio by the distribution's fundamental frequency.

###
float OvertoneDistribution:: getRealAmp (int partialNum) const

Returns a partial's real amplitude.

Multiplies the partial's amplitude ratio by the amplitude of the distribution's fundamental.

###
void OvertoneDistribution:: removePartial (int partialNum)

Removes a partial.

If removing from the middle of the partials array, all following partials will have their index shifted. Whenever this is called, be sure refresh your GUI or update anything that could attempt to access an incorrect or non-existant partial.

###
void OvertoneDistribution:: setFundamental (float fundamentalFreq,
float fundamentalAmp) noexcept

Sets values for the fundamental's frequency and amplitude.

For most dissonance models, the fundamental partial will need to be initialized with a real frequency value, in Hz.

In some cases, amplitudes may need to have a value denoting a sound pressure level (dB, dB(SPL)) or loudness estimation (sones, LFKS). For some, it may be acceptable to use frequency and amplitude ratios.

###
void OvertoneDistribution:: setFundamentalFreq (float newFundamentalFreq) noexcept

Sets a real value for the fundamental frequency.

Parameters | |
---|---|

newFundamentalFreq | The frequency (very likely in Hz) of the fundamental frequency. |

###
void OvertoneDistribution:: setFundamentalAmp (float newFundamentalAmp) noexcept

Sets a real value for the fundamental's amplitude.

Parameters | |
---|---|

newFundamentalAmp | The amplitude of the fundamental. Different models may require different units. Check the documentation of the models you will be using. |

###
float OvertoneDistribution:: getFundamentalFreq () const noexcept

Returns the fundamental frequency.

###
float OvertoneDistribution:: getFundamentalAmp () const noexcept

Returns the fundamental's amplitude.

###
void OvertoneDistribution:: mute (bool mute) noexcept

Sets the mute status of the overtone distribution.

For this library, muting is used to exlude overtone distributions from dissonance calculations. It could also be used to mute distributions in synthesis, or to isolate timbral elements if incorporated into a larger Timbre class.

###
void OvertoneDistribution:: mutePartial (int partialNum,
bool mute)

Sets whether to mute a partial, excluding it from dissonance calculations.

Parameters | |
---|---|

partialNum | The index of the partial to mute or unmute. |

mute | Set to true to mute, false to unmute. |

###
void OvertoneDistribution:: muteFundamental (bool mute) noexcept

Sets the mute status of the fundamental.

###
bool OvertoneDistribution:: partialIsMuted (int partialNum) const

Returns true if the partial should be muted and excluded from dissonance calculations.

Parameters | |
---|---|

partialNum | The index of the partial whose mute status will be checked. |

###
bool OvertoneDistribution:: fundamentalIsMuted () const noexcept

Returns true if the fundamental is muted.

###
void OvertoneDistribution:: addPartialDissonance (int partialNum,
float dissonanceToAdd)

Adds dissonance to partial's dissonance value.

Parameters | |
---|---|

partialNum | |

dissonanceToAdd | This amount is added to the partial's total dissonance. |

This should be called anytime that a partial contributes to the dissonance of a chord while DissonanceCalc::sumPartialDissonances is set to true.

###
void OvertoneDistribution:: addDissonanceToFundamental (float dissonanceToAdd) noexcept

Adds dissonance to the total dissonance of the fundamental partial.

Parameters | |
---|---|

dissonanceToAdd | This amount is added to the fundamental's total dissonance. |

This should be called anytime that the fundamental contributes to the dissonance of a chord while DissonanceCalc::sumPartialDissonances is set to true.

###
float OvertoneDistribution:: getPartialDissonance (int partialNum) const

Returns the dissonance of a partial.

This usually reflects the amount of dissonance that a partial has contributed to the overall dissonance of a distribution or chord.

###
float OvertoneDistribution:: getDissonanceOfFundamental () const noexcept

Returns the dissonance of the fundamental partial.

This usually reflects the amount of dissonance that the fundamental partial contributes to the overall dissonance of a distribution or chord.

###
float OvertoneDistribution:: getTotalDissonance () const noexcept

Returns the sum of all partial dissonances.

This usually reflects the amount of dissonance that an overtone distribution contributes to the overall dissonance of a chord.

###
void OvertoneDistribution:: clearPartialDissonances ()

Sets all partial dissonance values to zero.

This should be called at the beginning of a dissonance calculation for a new chord, unless you are intending to use data from previous frames in your dissonance calculations.

###
void OvertoneDistribution:: setMinInterval (float newMinInteval) noexcept

Sets the minimum frequency interval between any two partials.

This value represents the frequency ratio between any two partials and should be greater than or equal to 1. A value of 1 means that there is no minimum. Although an overtone distribution may not have a minimum partial interval, distributions cannot have two partials with the same frequency.

###
float OvertoneDistribution:: getMinInterval () const noexcept

Returns the minimum frequency interval between any two partials.

###
bool OvertoneDistribution:: tooCloseToOther (double freqToCheck) const protected

Returns true if the input partial is closer in frequency to another partial than the minimum interval permits.