Ead.h

/*
 * Ead.h
 *
 * Adapted from ead~.c puredata external (creb library)
 *
 * This file is part of Mozzi.
 *
 * Copyright (c) 2000-2003 by Tom Schouten
 * Copyright 2012 Tim Barrass
 * Copyright 2012-2024 Tim Barrass and the Mozzi Team
 *
 * Mozzi is licensed under the GNU Lesser General Public Licence (LGPL) Version 2.1 or later.
 *
 */

#ifndef EAD_H_
#define EAD_H_

#include "math.h"
#include "mozzi_fixmath.h"


/** Exponential attack decay envelope. This produces a natural sounding
envelope. It calculates a new value each time next() is called, which can be
mapped to other parameters to change the amplitude or timbre of a sound.
@note Currently doesn't work at audio rate... may need larger number 
types for Q8n8attack and Q8n8decay ?
*/

class Ead
{

public:

	/** Constructor
	@param update_rate
	Usually this will be MOZZI_CONTROL_RATE or MOZZI_AUDIO_RATE, unless you
	design another scheme for updating. One such alternative scheme could take turns
	for various control changes in a rotating schedule to spread out calculations
	made in successive updateControl() routines. 
	*/
	Ead(unsigned int update_rate) : UPDATE_RATE(update_rate)
	{
		;
	}

	/** Set the attack time in milliseconds.
	@param attack_ms The time taken for values returned by successive calls of
	the next() method to change from 0 to 255.
	*/
	inline
	void setAttack(unsigned int attack_ms)
	{
		Q8n8attack = float_to_Q8n8(millisToOneMinusRealPole(attack_ms));
	}


	/** Set the decay time in milliseconds.
	@param decay_ms The time taken for values returned by successive calls of
	the next() method to change from 255 to 0. 
	*/
	inline
	void setDecay(unsigned int decay_ms)
	{
		Q8n8decay = float_to_Q8n8(millisToOneMinusRealPole(decay_ms));
	}


	/** Set attack and decay times in milliseconds.
	@param attack_ms The time taken for values returned by successive calls of
	the next() method to change from 0 to 255.
	@param decay_ms The time taken for values returned by successive calls of
	the next() method to change from 255 to 0.
	*/
	inline
	void set(unsigned int attack_ms, unsigned int decay_ms)
	{
		setAttack(attack_ms);
		setDecay(decay_ms);
	}


	/** Start the envelope from the beginning. 
	This can be used at any time, even if the previous envelope is not finished. 
	*/
	inline
	void start()
	{
		Q8n24state = 0;
		attack_phase = true;
	}


	/** Set attack and decay times in milliseconds, and start the envelope from the beginning. 
	This can be used at any time, even if the previous envelope is not finished. 
	@param attack_ms The time taken for values returned by successive calls of
	the next() method to change from 0 to 255.
	@param decay_ms The time taken for values returned by successive calls of
	the next() method to change from 255 to 0.
	*/
	inline
	void start(unsigned int attack_ms, unsigned int decay_ms)
	{
		set(attack_ms, decay_ms);
		//Q8n24state = 0; // don't restart from 0, just go from whatever the current level is, to avoid glitches
		attack_phase = true;
	}


	/** Calculate and return the next envelope value, in the range -128 to 127
	@note Timing: 5us
	*/

	inline
	uint8_t next()
	{
		if(attack_phase)
		{
			// multiply A(a1,b1) * A(a2,b2) = A(a1+a2, b1+b2)
			Q8n24state += (((Q8n24)(Q8n24_FIX1 - Q8n24state) * Q8n8attack)) >> 8; // Q8n24, shifts all back into n24
			if (Q8n24state >= Q8n24_FIX1-256)
			{
				Q8n24state = Q8n24_FIX1-256;
				attack_phase = false;
			}
		}else{ /* decay phase */
			Q8n24state -= (Q8n24state * Q8n8decay)>>8;
		}
		return Q8n24_to_Q0n8(Q8n24state);
	}


private:

	Q8n8 Q8n8attack;
	Q8n8 Q8n8decay;
	Q8n24 Q8n24state;
	bool attack_phase;
	const unsigned int UPDATE_RATE;


	/* convert milliseconds to 1-p, with p a real pole */
	inline
	float millisToOneMinusRealPole(unsigned int milliseconds)
	{
		static const float NUMERATOR = 1000.0f * log(0.001f);
		return  -expm1(NUMERATOR / ((float)UPDATE_RATE * milliseconds));
	}


	// Compute exp(x) - 1 without loss of precision for small values of x.
	inline
	float expm1(float x)
	{
		if (fabs(x) < 1e-5)
		{
			return x + 0.5*x*x;
		}
		else
		{
			return exp(x) - 1.0;
		}
	}

};

/**
@example 07.Envelopes/Ead_Envelope/Ead_Envelope.ino
This is an example of how to use the Ead class.
*/

#endif /* EAD_H_ */