/* $Id: seclasses.h,v 1.1 1998/10/05 14:49:18 schwarz Exp $

   include/seclasses.h		1.10.1998	Diemo Schwarz

   Definition of class data structures for the spectral envelope library.

   $Log: seclasses.h,v $
 * Revision 1.1  1998/10/05  14:49:18  schwarz
 * Split up specenv.h into smaller include files seclasses.h,
 * sefiles.h, separa.h, seutil.h to facilitate selective including
 * and editing.
 *
 * New separate data structure seSpecEnv for spectral envelopes,
 * which is no longer part of the estimation parameter structures.
 *
*/

#ifndef _SECLASSES_H_
#define _SECLASSES_H_

#ifdef __cplusplus
extern "C" {
#endif


#include "seutil.h"	/* defines type aliases Frequency, Amplitude, etc. 
			   for float */



/*
// DATA GROUP:	    SPECTRAL ENVELOPE DATA TYPES
*/

/*DOC:
  Frequency scaling of estimation */
typedef enum { seScLinear, seScLog, seScNum }	seScale;

extern const char *seScaleName [seScNum];


/*DOC:
  Spectral envelope data structure */ 
typedef struct 
{
    Frequency  	maxfreq;   /* upper border of env (maxfreq = sampling rate/2 */
    int	    	numenv;	   /* number of points in envelope */
    Amplitude  	*env;	   /* numenv spectral envelope amplitude values */
    
    Frequency	fstep;	   /* size of bin in env  (fstep = sr / numenv) */
    seScale 	scale;	   /* frequency scale for storage */
    Frequency	breakfreq; /* break frequency for log scale */
}   seSpecEnv;


/*DOC:
  Spectral envelope data structure */ 
typedef struct 
{
    Frequency	centerfreq;
    Amplitude	amplitude;
    Frequency	bandwidth;
}   seFormant;


/*DOC:
  Precise formants data structure */ 
typedef struct 
{
    int		numformants;	/* number of precise formants */
    seFormant	*formant;	/* numformants precise formants */
    seSpecEnv	residual;	/* residual spectral envelope */
}   sePreciseFormants;


/*DOC:
  Formant region data structure */ 
typedef struct 
{
    Frequency	lower, center, upper;	/* region boundary frequencies (Hz) */
    float	salience;		/* how sure we are it is a formant */
}   seRegion;


/*DOC:
  Fuzzy formant data structure */ 
typedef struct 
{
    int		numregions;	/* number of precise formants */
    seRegion	*region;	/* numformants precise formants */
    seSpecEnv	specenv;	/* spectral envelope */
}   seFuzzyFormants;




/*
// FUNCTION GROUP:	Allocation and Deallocation of Spectral Envelopes 
*/

/*DOC:
  Create new spectral envelope in env. 
  [in]  num	number of bins
	sr	sampling rate, highest bin frequency is sr / 2 
	sc	frequency scale
	bf	break frequency in case of logarithmic scale
  [out] env	<i>address</i> of specenv pointer(!).  Will be set to NULL 
		if something goes wrong.  Call like this:

  <pre>
	seSpecEnv *env;
	seNewSpecEnv (&env, 512, 44100, seScLog, 5000);
  </pre>
*/
seReturn  seNewSpecEnv     (seSpecEnv **env, int num, Frequency sr, 
			    seScale sc, Frequency bf);

/*DOC:
  Create new spectral envelope in env with same parameters as envfrom. 
  [out] env	<i>address</i> of specenv pointer(!).  Will be set to NULL 
		if something goes wrong.
  [in]  envfrom model spectral envelope
*/
seReturn  seNewSpecEnvLike (seSpecEnv **env, seSpecEnv *envfrom);

/*DOC:
  Free spectral envelope */
seReturn  seDeleteSpecEnv  (seSpecEnv **env);

/*DOC:
  Unconditionally reallocate storage for newnum bins. */
seReturn  seReallocSpecEnv (seSpecEnv *env, int newnum);



/*
// FUNCTION GROUP:	ACCESS and MANIPULATION
*/

/*DOC:
  Copy spectral envelope data (check for same size if DEBUG) */
seReturn  seSpecEnvCopy    (seSpecEnv *from, seSpecEnv *to);

/*DOC:
  Set all bins of env to constant value ampl. */
seReturn  seSpecEnvConst   (seSpecEnv *env, Amplitude ampl);

/*DOC:
   Get (possibly interpolated) value of env at arbitrary frequency
   freq.  For frequencies greater than maxfreq, quickly fade out the
   envelope, since it is not defined there. */
Amplitude seAtFreq	  (seSpecEnv *env, Frequency freq);

/*DOC:
  Return sum of all bins of env. */
double    seSpecEnvSum	  (seSpecEnv *env);

/*DOC:
  Stretch env1 to env2 according to the parameters of env2 (numenv).
   Maxfreq will be copied from env1. Env2 must have been properly
   allocated with seNewSpecEnv.  */
seReturn  seResample	  (seSpecEnv *env1, seSpecEnv *env2);





#ifdef __cplusplus
}
#endif

#endif /* _SECLASSES_H_ */