Chris@0: ////////////////////////////////////////////////////////////////////////////////////
Chris@0: //     /*!  \file FEAPI.h 
Chris@0: //          \brief interface of the feature extraction plugin. 
Chris@0: //        <br><br>
Chris@0: //        In the following, context function pointers typedefs are referred to as 
Chris@0: //        functions.<br>
Chris@0: //
Chris@0: //        
Chris@0: //        Create a new instance of the plugin with the function 
Chris@0: //        ::FEAPI_CreatePluginInstance. The call of this function is mandatory.
Chris@0: //        <br><br>
Chris@0: //
Chris@0: //        Initialize the plugin with the call of function
Chris@0: //        ::FEAPI_InitializePlugin.<br><br>
Chris@0: //
Chris@0: //        Information about the plugin can be requested via the following 
Chris@0: //        functions:<br>
Chris@0: //        ::FEAPI_GetPluginAPIVersion, <br>
Chris@0: //        ::FEAPI_GetPluginName, <br> 
Chris@0: //        ::FEAPI_GetPluginVendor, <br>
Chris@0: //        ::FEAPI_GetPluginVendorVersion, <br>
Chris@0: //        ::FEAPI_GetPluginCopyright, <br>
Chris@0: //        ::FEAPI_GetPluginDescription. <br>
Chris@0: //        The call of these functions is optional. Combined with a call to
Chris@0: //        ::FEAPI_GetPluginId, the plugin can be uniquely identified. <br><br>
Chris@0: //
Chris@0: //        The technical capabilities of the plugin can be requested via the call 
Chris@0: //        of the function
Chris@0: //        ::FEAPI_GetPluginProperty.<br><br>
Chris@0: //
Chris@0: //        To get the number of the features resp. results that are computed 
Chris@0: //        by the plugin, call the function <br>
Chris@0: //        ::FEAPI_GetPluginNumOfResults; <br>
Chris@0: //        the function <br>
Chris@0: //        ::FEAPI_GetPluginResultDescription gives you detailed information about the 
Chris@0: //        meaning and usage of every result (see structure ::_ResultDescription
Chris@0: //        for details). <br><br>
Chris@0: //
Chris@0: //        To get the number of the options/ parameter settings that can be 
Chris@0: //        done before processing, call the function <br>
Chris@0: //        ::FEAPI_GetPluginNumOfParameters; <br>
Chris@0: //        the function <br>
Chris@0: //        ::FEAPI_GetPluginParamDescription gives you detailed information about 
Chris@0: //        the meaning and usage of every single parameter (see structure 
Chris@0: //        ::FEAPI_ParameterDescription_t for details).<br><br>
Chris@0: //
Chris@0: //        To get or set a specific parameter value, call the function <br>
Chris@0: //        ::FEAPI_GetPluginParameter resp. <br>
Chris@0: //        ::FEAPI_SetPluginParameter. <br><br>
Chris@0: //
Chris@0: //        After the plugin is initialized, the actual processing can begin.
Chris@0: //        The ::FEAPI_ProcessPlugin <br>
Chris@0: //        function can be called to do the actual feature/result 
Chris@0: //        calculation. ::FEAPI_ProcessPlugin expects subsequently new blocks 
Chris@0: //        of audio data. Note that ::FEAPI_ProcessPlugin does not return 
Chris@0: //        computed feature values.<br>
Chris@0: //
Chris@0: //        After finishing one ::FEAPI_ProcessPlugin call, zero, one or more 
Chris@0: //        results can be available, depending on the plug-ins implementation. 
Chris@0: //        To query the available number of values for every feature/result, 
Chris@0: //        call <br>
Chris@0: //        ::FEAPI_GetPluginSizeOfResult, <br>
Chris@0: //        which returns the number of values for this
Chris@0: //        result. Afterwards, the result values for each result can
Chris@0: //        be requested via <br>
Chris@0: //        ::FEAPI_GetPluginResult. Note that the memory for the results has to be 
Chris@0: //        allocated by the host.<br><br>
Chris@0: //
Chris@0: //        To signal that no more audio data is available at the end (e.g. of
Chris@0: //        the audio file), call <br>
Chris@0: //        ::FEAPI_ProcessPluginDone and get the last results with 
Chris@0: //        ::FEAPI_GetPluginResult if available.<br><br>
Chris@0: //
Chris@0: //        To flush the internal buffers, the function <br>
Chris@0: //        ::FEAPI_ResetPlugin <br>
Chris@0: //        may be called.
Chris@0: //
Chris@0: //        After all processing has been done, destroy the instance of the 
Chris@0: //        plugin with the function <br>
Chris@0: //        ::FEAPI_DestroyPluginInstance. <br>
Chris@0: //        The call of this function is mandatory. <br><br>
Chris@0: //
Chris@0: //        <br><br><br>
Chris@0: //        The Feature Extraction plugin API is released under a BSD style
Chris@0: //        license. Please make all changes available to the authors.<br>
Chris@0: //        Contact information: lerch <at> zplane.de.
Chris@0: //
Chris@0: //     */
Chris@0: //
Chris@0: //        Copyright (c) 2004-2005, Alexander Lerch, zplane.development GbR
Chris@0: //        All rights reserved.
Chris@0: //
Chris@0: //        Redistribution and use in source and binary forms, with or without 
Chris@0: //        modification, are permitted provided that the following conditions 
Chris@0: //        are met:
Chris@0: //
Chris@0: //        *   Redistributions of source code must retain the above copyright 
Chris@0: //            notice, this list of conditions and the following disclaimer.
Chris@0: //        *   Redistributions in binary form must link to the FEAPI website
Chris@0: //            http://www.sf.net/projects/feapi,
Chris@0: //            reproduce this list of conditions and the following 
Chris@0: //            disclaimer in the documentation and/or other materials 
Chris@0: //            provided with the distribution.
Chris@0: //        *   The name of the contributors to this software must not be used 
Chris@0: //            to endorse or promote products derived from this software 
Chris@0: //            without specific prior written permission.
Chris@0: //
Chris@0: //        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
Chris@0: //        "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
Chris@0: //        LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
Chris@0: //        FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
Chris@0: //        COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 
Chris@0: //        INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
Chris@0: //        BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
Chris@0: //        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
Chris@0: //        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
Chris@0: //        LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
Chris@0: //        ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
Chris@0: //        POSSIBILITY OF SUCH DAMAGE.
Chris@0: //
Chris@0: ////////////////////////////////////////////////////////////////////////////////////
Chris@0: //  CVS INFORMATION
Chris@0: //
Chris@0: //  $RCSfile: FEAPI.h,v $
Chris@0: //  $Author: alex_lerch $
Chris@0: //  $Date: 2005/05/20 17:08:36 $
Chris@0: //
Chris@0: //  $Log: FEAPI.h,v $
Chris@0: //  Revision 1.2  2005/05/20 17:08:36  alex_lerch
Chris@0: //  - updated documentation
Chris@0: //  - added "signal" typedef for inputs and results
Chris@0: //  - changed function PluginCanDo to PluginGetProperty and changed the function itself to return values instead of bools
Chris@0: //  - cosmetic changes
Chris@0: //
Chris@0: //  Revision 1.1.1.1  2005/03/30 14:54:40  alex_lerch
Chris@0: //  first draft version requiring several updates:
Chris@0: //  - interface check
Chris@0: //  - check of plugin base class
Chris@0: //  - implementation of host base class
Chris@0: //  - update of outdated documentation
Chris@0: //
Chris@0: //
Chris@0: ////////////////////////////////////////////////////////////////////////////////////
Chris@0: ////////////////////////////////////////////////////////////////////////////////////
Chris@0: //                      !!!Do never ever edit this file!!!
Chris@0: ////////////////////////////////////////////////////////////////////////////////////
Chris@0: ////////////////////////////////////////////////////////////////////////////////////
Chris@0: 
Chris@0: /*! \brief avoid multiple header includes */
Chris@0: #if !defined(FEAPI_HEADER_INCLUDED) 
Chris@0: #define FEAPI_HEADER_INCLUDED
Chris@0: 
Chris@0: 
Chris@0: #ifdef __cplusplus
Chris@0: extern "C" {
Chris@0: #endif
Chris@0: 
Chris@0: /* Maximum string lengths. */
Chris@0: const unsigned int FEAPI_uiMaxNameLength        = 1024; //!< maximum number of characters for a name string (including null terminator)
Chris@0: const unsigned int FEAPI_uiMaxUnitLength        = 1024; //!< maximum number of characters for a unit string (including null terminator)
Chris@0: const unsigned int FEAPI_uiMaxDescriptionLength = 4096; //!< maximum number of characters for a description string (including null terminator)
Chris@0: 
Chris@0: ////////////////////////////////////////////////////////////////////////////////////
Chris@0: // interface structures and types
Chris@0: /** @defgroup types Interface Structures and Types
Chris@0:  *  @{
Chris@0:  */
Chris@0: 
Chris@0: 
Chris@0: /*! Structure describing properties and other information about one result/feature. */
Chris@0: typedef struct FEAPI_SignalDescription_t_tag
Chris@0: {
Chris@0:     char    acName[FEAPI_uiMaxNameLength];                //!< name of the result/feature (e.g. "Spectral Centroid", "Loudness", etc.) 
Chris@0:     char    acUnit[FEAPI_uiMaxUnitLength];                //!< unit of the result/feature (e.g. "dB", "sone", "Hz", etc.) 
Chris@0:     char    acDescription[FEAPI_uiMaxDescriptionLength];  //!< description of the result/feature (clear text description) 
Chris@0:     float   fRangeMin;              //!< minimum value of the result/feature (if no minimum value: minimum floating point value) 
Chris@0:     float   fRangeMax;              //!< maximum value of the result/feature (if no maximum value: maximum floating point value) 
Chris@0:     float   fQuantizedTo;           //!< quantization step size of the result/feature (e.g. 1 for integer result, -1 for no quantization) 
Chris@0:     float   fSampleRate;            //!< sample rate of the result/feature output in Hz; -1 if sample rate equals input block length, -2 for non-equidistant samples
Chris@0: } FEAPI_SignalDescription_t;
Chris@0: 
Chris@0: 
Chris@0: /*! Structure describing properties and other information about one parameter. */
Chris@0: typedef struct FEAPI_ParameterDescription_t_tag
Chris@0: {
Chris@0:     char    acName[FEAPI_uiMaxNameLength];                //!< name of the parameter (e.g. "Gain", "Sensitivity", etc.) 
Chris@0:     char    acUnit[FEAPI_uiMaxUnitLength];                //!< unit of the parameter (e.g. "dB", "Hz", etc.) 
Chris@0:     char    acDescription[FEAPI_uiMaxDescriptionLength];  //!< description of the parameter (clear text description) 
Chris@0:     float   fRangeMin,              //!< minimum value of the parameter (if no minimum value: minimum floating point value) 
Chris@0:             fRangeMax,              //!< maximum value of the parameter (if no maximum value: maximum floating point value) 
Chris@0:             fDefaultValue;          //!< default value for the parameter 
Chris@0:     float   fQuantizedTo;           //!< quantization step size of the parameter (e.g. 1 for integer quantization, -1 for no quantization) 
Chris@0:     int     bIsChangeableInRealTime;//!< 0/false if the parameter has to be set before the processing starts and can not be changed during processing, 1 if the parameter can be changed during processing
Chris@0: } FEAPI_ParameterDescription_t;
Chris@0: 
Chris@0: 
Chris@0: /*! Structure for user/vendor defined commands. */
Chris@0: typedef struct FEAPI_UserData_t_tag
Chris@0: {
Chris@0:     char    *pcUserString;          //!< user defined string value (memory could be freed by host after function call)
Chris@0:     void    *pcUserData;            //!< pointer to user defined data
Chris@0: } FEAPI_UserData_t;
Chris@0: 
Chris@0: 
Chris@0: /*! Typedef for the plugin instance handle. */
Chris@0: typedef void* FEAPI_PluginInstance_t;
Chris@0: 
Chris@0: 
Chris@0: /*! This typedef is used for time stamps in seconds. 
Chris@0:     For a block of data, the time stamp is defined to be the time at the beginning of the block. */
Chris@0: typedef double FEAPI_TimeStamp_t;
Chris@0: 
Chris@0: 
Chris@0: /*! This typedef is used for input and output data. 
Chris@0:     At least for this version of the API, this is exactly float. */
Chris@0: typedef float FEAPI_Signal_t;
Chris@0: 
Chris@0: 
Chris@0: /*! Enumerator for possible error return values, if any other value than FEAPI_kNoError is returned, 
Chris@0:     the function was not able to execute the specified operation(s).<br>
Chris@0:     All error defines are negative. */
Chris@0: typedef enum FEAPI_Error_t_tag
Chris@0: {
Chris@0:     FEAPI_kNoError           = 0,       //!< no error occurred
Chris@0:     FEAPI_kUnspecifiedError  = -1,      //!< an error occurred, but the type is not yet specified
Chris@0:     FEAPI_kUnknownError      = -9999    //!< an error occurred, but its type is not specifyable
Chris@0: } FEAPI_Error_t;
Chris@0: 
Chris@0: 
Chris@0: /*! Enumerator for retrieval of version info which can be resolved as major.minor.sub. */
Chris@0: typedef enum FEAPI_VersionInfo_t_tag
Chris@0: {
Chris@0:     FEAPI_kMajorVersion    = 0,        //!< indicates the major version
Chris@0:     FEAPI_kMinorVersion    = 1,        //!< indicates the minor version
Chris@0:     FEAPI_kSubVersion      = 2         //!< indicates the sub version or bug-fix version
Chris@0: } FEAPI_VersionInfo_t;
Chris@0: 
Chris@0: 
Chris@0: /*! Enumerator for retrieval of information about what the plug supports. */
Chris@0: typedef enum FEAPI_PluginProperty_t_tag
Chris@0: {
Chris@0:     FEAPI_kMinSampleRate    = 0,        //!< indicates the minimum sample rate
Chris@0:     FEAPI_kMaxSampleRate    = 1,        //!< indicates the maximum sample rate
Chris@0:     FEAPI_kMinChannels      = 2,        //!< indicates minimum number of channels
Chris@0:     FEAPI_kMaxChannels      = 3,        //!< indicates maximum number of channels
Chris@0:     FEAPI_kMinFrameSize     = 4,        //!< indicates minimum number of frames per process call
Chris@0:     FEAPI_kMaxFrameSize     = 5,        //!< indicates maximum number of frames per process call
Chris@0:     FEAPI_kOptFrameSize     = 6         //!< indicates optimal number of frames per process call
Chris@0: } FEAPI_PluginProperty_t;
Chris@0: 
Chris@0: /** @} */ 
Chris@0: 
Chris@0: ////////////////////////////////////////////////////////////////////////////////////
Chris@0: // API function declaration
Chris@0: /** @defgroup apifun API function pointers
Chris@0:  *  @{
Chris@0:  */
Chris@0: 
Chris@0:     /*!
Chris@0:      * Creates a new instance of the plugin
Chris@0:      *
Chris@0:      * @param phInstanceHandle : handle to the instance to be created
Chris@0:      * @return FEAPI_Error_t  : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t   (*FEAPI_CreatePluginInstance_t) ( FEAPI_PluginInstance_t *phInstanceHandle );
Chris@0: 
Chris@0:     /*!
Chris@0:      * Destroys an instance of the plugin.
Chris@0:      *
Chris@0:      * @param phInstanceHandle : handle to the instance to be destroyed
Chris@0:      * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t   (*FEAPI_DestroyPluginInstance_t) ( FEAPI_PluginInstance_t *phInstanceHandle );
Chris@0: 
Chris@0:     /*!
Chris@0:      * initializes a new instance of the plugin
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to the instance
Chris@0:      * @param fInputSampleRate : sample rate of input(s) in Hz
Chris@0:      * @param iNumberOfAudioChannels : number of input audio channels
Chris@0:      * @param iHostApiMajorVersion : major version number of host
Chris@0:      * @param pstUserData : pointer to user or vendor defined data (may be NULL)
Chris@0:      *
Chris@0:      * @return FEAPI_Error_t  : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t   (*FEAPI_InitializePlugin_t) (FEAPI_PluginInstance_t hInstanceHandle, 
Chris@0:                                                             float               fInputSampleRate, 
Chris@0:                                                             int                 iNumberOfAudioChannels,
Chris@0:                                                             int                 iHostApiMajorVersion,
Chris@0:                                                             FEAPI_UserData_t     *pstUserData);
Chris@0: 
Chris@0: 
Chris@0:     /*! 
Chris@0:      * Gets the version number (major, minor or subversion) of the API used by the plugin.
Chris@0:      * This is *not* the plugin version, therefore the function may be called without a previously 
Chris@0:      * created instance.
Chris@0:      * 
Chris@0:      * @param eAPIMajorMinorOrSubVersion : flag which version type is requested
Chris@0:      * @return int  : requested version number 
Chris@0:      */
Chris@0:     typedef int (*FEAPI_GetPluginAPIVersion_t) ( FEAPI_VersionInfo_t eAPIMajorMinorOrSubVersion ); //!< \todo change ints to (unsigned) ints where appropriate?
Chris@0: 
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets the name of the plugin.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param *pcPluginName : pointer to buffer of FEAPI_uiMaxNameLength chars, the name will be copied to this buffer
Chris@0:      * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t (*FEAPI_GetPluginName_t) ( FEAPI_PluginInstance_t hInstanceHandle, 
Chris@0:                                                                     char    *pcPluginName);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets the vendor name of the plugin.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param *pcPluginVendor : pointer to buffer of FEAPI_uiMaxNameLength chars, the vendor name will be copied to this buffer
Chris@0:      * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t (*FEAPI_GetPluginVendor_t) (FEAPI_PluginInstance_t hInstanceHandle, 
Chris@0:                                                                     char    *pcPluginVendor);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets an indication of the plugins capabilities.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param ePluginProperty : requested property 
Chris@0:      * @return float  : corresponding value
Chris@0:      */
Chris@0:     typedef float (*FEAPI_GetPluginProperty_t) (FEAPI_PluginInstance_t hInstanceHandle, 
Chris@0:                                                 FEAPI_PluginProperty_t ePluginProperty);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets the (vendor unique) plugin identification string.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param *pcPluginId : pointer to buffer of FEAPI_uiMaxNameLength chars, the id will be copied to this buffer
Chris@0:      * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t (*FEAPI_GetPluginId_t) (FEAPI_PluginInstance_t hInstanceHandle, 
Chris@0:                                                                     char *pcPluginId);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets the vendor version of the plugin.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param ePluginMajorMinorOrSubVersion : flag which version type is requested
Chris@0:      * @return int  : requested version number 
Chris@0:      */
Chris@0:     typedef int (*FEAPI_GetPluginVendorVersion_t) ( FEAPI_PluginInstance_t  hInstanceHandle, 
Chris@0:                                                     FEAPI_VersionInfo_t     ePluginMajorMinorOrSubVersion); 
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets the description of the plugin, containing information about what the plugin actually does.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param *pcPluginDescription : pointer to buffer of FEAPI_uiMaxDescriptionLength chars, the plugin description will be copied to this buffer
Chris@0:      * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t (*FEAPI_GetPluginDescription_t) (FEAPI_PluginInstance_t hInstanceHandle, 
Chris@0:                                                                             char *pcPluginDescription);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets the copyright information for the plugin.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param *pcPluginCopyright : pointer to buffer of FEAPI_uiMaxDescriptionLength chars, the plugin copyright information will be copied to this buffer
Chris@0:      * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t (*FEAPI_GetPluginCopyright_t) (FEAPI_PluginInstance_t hInstanceHandle, 
Chris@0:                                                                           char *pcPluginCopyright);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets the number of inputs for the plugin. This number will equal the 
Chris@0:      * number of audio channels in many cases, otherwise exceed the number of audio channels. 
Chris@0:      * The additional input channels are plugin developer specific and not recommended. If used,
Chris@0:      * they have to be routed host internally.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @return int  : number of inputs
Chris@0:      */
Chris@0:     typedef int (*FEAPI_GetPluginNumOfInputs_t) (FEAPI_PluginInstance_t hInstanceHandle);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets information about one of the possible inputs.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param iInputIndex : index of the input the description is requested for, index ranges from 0...NumOfInputs-1
Chris@0:      * @param *pstInputDescription : the requested description will be copied to this structure
Chris@0:      * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t (*FEAPI_GetPluginInputDescription_t) (FEAPI_PluginInstance_t      hInstanceHandle, 
Chris@0:                                                                 int                         iInputIndex, 
Chris@0:                                                                 FEAPI_SignalDescription_t   *pstInputDescription);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets the number of parameters.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @return int  : number of parameters
Chris@0:      */
Chris@0:     typedef int (*FEAPI_GetPluginNumOfParameters_t) (FEAPI_PluginInstance_t hInstanceHandle);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets information about one of the possible parameters.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param iParameterIndex : index of the parameter (setting) the description is requested for, index ranges from 0...NumOfParameters-1
Chris@0:      * @param *pstParameterDescription : the requested description will be copied to this structure
Chris@0:      * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t (*FEAPI_GetPluginParameterDescription_t) (FEAPI_PluginInstance_t          hInstanceHandle, 
Chris@0:                                                                     int                             iParameterIndex, 
Chris@0:                                                                     FEAPI_ParameterDescription_t    *pstParameterDescription);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Sets a parameter to a specified value.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param iParameterIndex : index of the parameter (setting) to be changed, index ranges from 0...NumOfParameters-1
Chris@0:      * @param fValue : new value of the parameter
Chris@0:      * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t (*FEAPI_SetPluginParameter_t) (   FEAPI_PluginInstance_t  hInstanceHandle, 
Chris@0:                                                             int                     iParameterIndex, 
Chris@0:                                                             float                   fValue);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets the current value of a parameter.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param iParameterIndex : index of the parameter (setting) requested, index ranges from 0...NumOfParameters-1
Chris@0:      * @return float  : value of the parameter with index iParameterIndex
Chris@0:      */
Chris@0:     typedef float (*FEAPI_GetPluginParameter_t) (FEAPI_PluginInstance_t hInstanceHandle, 
Chris@0:                                                                     int iParameterIndex);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Processes a block of audio data.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param **ppfInputBuffer : input audio data in the format [channels][samples]; audio samples have a range from -1.0...+1.0
Chris@0:      * @param *ptFEAPI_TimeStamp : time stamps in seconds for every input, may be NULL
Chris@0:      * @param iNumberOfFrames : number of frames in ppfInputBuffer
Chris@0:      * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t (*FEAPI_ProcessPlugin_t) (FEAPI_PluginInstance_t  hInstanceHandle, 
Chris@0:                                                     const FEAPI_Signal_t    **ppfInputBuffer, 
Chris@0:                                                     const FEAPI_TimeStamp_t *ptFEAPI_TimeStamp, 
Chris@0:                                                     int                     iNumberOfFrames);           
Chris@0: 
Chris@0:     /*!
Chris@0:      * Signals that no more input data is available (does the final processing).
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t (*FEAPI_ProcessPluginDone_t) (FEAPI_PluginInstance_t hInstanceHandle);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets the number of results/features to be calculated.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @return int  : number of results
Chris@0:      */
Chris@0:     typedef int (*FEAPI_GetPluginNumOfResults_t) (FEAPI_PluginInstance_t hInstanceHandle);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets information about one of the possible results/features.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param iResultIndex : index of the result (feature) the description is requested for, index ranges from 0...NumOfResults-1
Chris@0:      * @param *pstResultDescription : the requested description will be copied to this structure
Chris@0:      * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t (*FEAPI_GetPluginResultDescription_t) (   FEAPI_PluginInstance_t      hInstanceHandle, 
Chris@0:                                                                     int                         iResultIndex, 
Chris@0:                                                                     FEAPI_SignalDescription_t   *pstResultDescription);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets the size of one result in FEAPI_Signal_t values (4 bytes per value).
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param iResultIndex : index of the result/feature the size is requested for, index ranges from 0...NumOfResults-1
Chris@0:      * @return int : size of result in FEAPI_Signal_t values (4 bytes per value)
Chris@0:      */
Chris@0:     typedef int (*FEAPI_GetPluginSizeOfResult_t) (FEAPI_PluginInstance_t hInstanceHandle, 
Chris@0:                                                                     int iResultIndex);
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets one result.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param iResultIndex : index of the requested result/feature, index ranges from 0...NumOfResults-1
Chris@0:      * @param *pfResult : the result data is copied into this buffer
Chris@0:      * @param *ptFEAPI_TimeStamp : the time stamp of the result
Chris@0:      * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t (*FEAPI_GetPluginResult_t) (  FEAPI_PluginInstance_t  hInstanceHandle, 
Chris@0:                                                         int                     iResultIndex, 
Chris@0:                                                         FEAPI_Signal_t          *pfResult, 
Chris@0:                                                         FEAPI_TimeStamp_t       *ptFEAPI_TimeStamp);           
Chris@0: 
Chris@0:     /*!
Chris@0:      * Gets the maximum latency of one result. Since the host buffer size may vary, this is only the 
Chris@0:      * *internal* latency.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @param iResultIndex : index of the requested result (feature), index ranges from 0...NumOfResults-1
Chris@0:      * @return int  : number of samples (at audio input sample rate) which is required to calculate this result the first time (negative values are not allowed, 0 means undefined)
Chris@0:      */
Chris@0:     typedef int (*FEAPI_GetPluginResultLatency_t) (FEAPI_PluginInstance_t hInstanceHandle, int iResultIndex); 
Chris@0: 
Chris@0:     /*!
Chris@0:      * Resets/clears all internal buffers and states, so that the plugin is in a state where it can start processing a new audio stream.
Chris@0:      *
Chris@0:      * @param hInstanceHandle : handle to instance 
Chris@0:      * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0:      */
Chris@0:     typedef FEAPI_Error_t (*FEAPI_ResetPlugin_t) (FEAPI_PluginInstance_t hInstanceHandle);
Chris@0: 
Chris@0: /** @} */ 
Chris@0: 
Chris@0: 
Chris@0: #ifdef __cplusplus
Chris@0: }
Chris@0: #endif
Chris@0: 
Chris@0: 
Chris@0: #endif // #if !defined(FEAPI_HEADER_INCLUDED)