Main Page | Modules | Alphabetical List | Data Structures | Directories | File List | Data Fields | Globals | Related Pages

FEAPI.h

Go to the documentation of this file.
00001 
00002 //     /*!  \file FEAPI.h 
00003 //          \brief Feature Extraction plugin API interface file
00004 //
00005 //        In the following, context function pointers typedefs are referred to as 
00006 //        functions.<br>
00007 //
00008 //    
00009 //        ::FEAPI_CreatePluginInstance is used to create a new instance of the plugin. 
00010 //        Calling this function is mandatory. <br><br>
00011 //
00012 //        ::FEAPI_InitializePlugin is then used to initialize the plugin. 
00013 //        Calling this function is mandatory. <br><br>
00014 //
00015 //        Information about the plugin can be requested through the following 
00016 //        functions: <br>
00017 //        ::FEAPI_GetPluginAPIVersion, <br>
00018 //        ::FEAPI_GetPluginName, <br> 
00019 //        ::FEAPI_GetPluginVendor, <br>
00020 //        ::FEAPI_GetPluginVendorVersion, <br>
00021 //        ::FEAPI_GetPluginCopyright, <br>
00022 //        ::FEAPI_GetPluginDescription. <br>
00023 //        Calling these functions is optional. <br>
00024 //        ::FEAPI_GetPluginId can be combined with these functions to uniquely 
00025 //        identify the plugin. <br><br>
00026 //
00027 //        ::FEAPI_GetPluginProperty provides information about the technical 
00028 //        capabilities of the plugin. <br><br>
00029 //
00030 //        ::FEAPI_GetPluginNumOfResults is used to obtain the number of the 
00031 //        features/results that are computed by the plugin. <br>
00032 //        ::FEAPI_GetPluginResultDescription provides detailed information about the 
00033 //        meaning and usage of every result (see structure ::FEAPI_SignalDescription_t 
00034 //        for details). <br><br>
00035 //
00036 //        ::FEAPI_GetPluginNumOfParameters is used to obtain the number of parameters 
00037 //        that can be set for the plugin. <br>
00038 //        ::FEAPI_GetPluginParamDescription provides detailed information about 
00039 //        the meaning and usage of every single parameter (see structure 
00040 //        ::FEAPI_ParameterDescription_t for details). <br><br>
00041 //
00042 //        To get or set a plugin parameter, the following functions are used: <br>
00043 //        ::FEAPI_GetPluginParameter <br>
00044 //        ::FEAPI_SetPluginParameter <br><br>
00045 //
00046 //        After the plugin is properly initialized, the actual processing can begin. <br>
00047 //        ::FEAPI_ProcessPlugin is called to do the actual feature/result 
00048 //        calculation. It expects subsequently new blocks of audio data. Note that 
00049 //        the function does not return computed feature values by itself. <br><br>
00050 //
00051 //        After finishing one ::FEAPI_ProcessPlugin call, zero, one or more 
00052 //        results may be available, depending on the plugin implementation. <br>
00053 //        ::FEAPI_GetPluginSizeOfResult is used at that point to query the available 
00054 //        number of values for each feature/result. <br>
00055 //        ::FEAPI_GetPluginResult is then used to obtain the actual values for each 
00056 //        result. Note that the memory needed to store the results must be allocated 
00057 //        by the host. <br><br>
00058 //
00059 //        ::FEAPI_ProcessPluginDone should be called to signal the plugin that no 
00060 //        more audio data is available (e.g. at the end of an audio file). <br>
00061 //        ::FEAPI_GetPluginResult can then be used to obtain the last results 
00062 //        (if available). <br><br>
00063 //
00064 //        ::FEAPI_ResetPlugin is used to flush the internal buffers of the plugin, 
00065 //        and to prepare it for a new audio stream. <br><br>
00066 //
00067 //        ::FEAPI_DestroyPluginInstance is finally used to destroy the plugin instance 
00068 //        after all processing has been done. Calling this function is mandatory. <br><br>
00069 //
00070 //        <br><br>
00071 //        The Feature Extraction plugin API is released under a BSD 
00072 //        license. Please make all changes available to the authors. <br>
00073 //        Contact information: <br>
00074 //        web: http://feapi.sourceforge.net <br>
00075 //        email: feapi-discussion@lists.sourceforge.net <br>
00076 //
00077 //     */
00078 //
00079 //        Copyright (c) 2004-2007, FEAPI development team
00080 //        All rights reserved.
00081 //
00082 //        Redistribution and use in source and binary forms, with or without 
00083 //        modification, are permitted provided that the following conditions 
00084 //        are met:
00085 //
00086 //        *   Redistributions of source code must retain the above copyright 
00087 //            notice, this list of conditions and the following disclaimer. 
00088 //        *   Redistributions in binary form must reproduce the above 
00089 //            copyright notice, this list of conditions and the following 
00090 //            disclaimer in the documentation and/or other materials 
00091 //            provided with the distribution. 
00092 //        *   Neither the name of the FEAPI development team nor the names 
00093 //            of its contributors may be used to endorse or promote products 
00094 //            derived from this software without specific prior written 
00095 //            permission. 
00096 //
00097 //        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
00098 //        "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
00099 //        LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
00100 //        FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
00101 //        COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 
00102 //        INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
00103 //        BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
00104 //        LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
00105 //        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
00106 //        LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
00107 //        ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
00108 //        POSSIBILITY OF SUCH DAMAGE.
00109 //
00112 //                      !!!Do never ever edit this file!!!
00115 
00117 #if !defined(FEAPI_HEADER_INCLUDED) 
00118 #define FEAPI_HEADER_INCLUDED
00119 
00120 #ifdef __cplusplus
00121 extern "C" {
00122 #endif
00123 
00125 // interface structures and types
00131 typedef enum FEAPI_MaxStringLengths_t_tag
00132 {
00133     FEAPI_kMaxNameLength        = 1024,    
00134     FEAPI_kMaxUnitLength        = 1024,    
00135     FEAPI_kMaxDescriptionLength = 4096     
00136 
00137 } FEAPI_MaxStringLengths_t;
00138 
00140 typedef struct FEAPI_SignalDescription_t_tag
00141 {
00142     char    acName[FEAPI_kMaxNameLength];                
00143     char    acUnit[FEAPI_kMaxUnitLength];                
00144     char    acDescription[FEAPI_kMaxDescriptionLength];  
00145     float   fRangeMin;              
00146     float   fRangeMax;              
00147     float   fQuantizedTo;           
00148     float   fSampleRate;            
00149 } FEAPI_SignalDescription_t;
00150 
00151 
00153 typedef struct FEAPI_ParameterDescription_t_tag
00154 {
00155     char    acName[FEAPI_kMaxNameLength];                
00156     char    acUnit[FEAPI_kMaxUnitLength];                
00157     char    acDescription[FEAPI_kMaxDescriptionLength];  
00158     float   fRangeMin,              
00159             fRangeMax,              
00160             fDefaultValue;          
00161     float   fQuantizedTo;           
00162     int     bIsChangeableInRealTime;
00163 } FEAPI_ParameterDescription_t;
00164 
00165 
00167 typedef struct FEAPI_UserData_t_tag
00168 {
00169     char    *pcUserString;          
00170     void    *pcUserData;            
00171 } FEAPI_UserData_t;
00172 
00173 
00175 typedef void* FEAPI_PluginInstance_t;
00176 
00177 
00180 typedef double FEAPI_TimeStamp_t;
00181 
00182 
00185 typedef float FEAPI_Signal_t;
00186 
00187 
00192 typedef enum FEAPI_Error_t_tag
00193 {
00194     FEAPI_kNoError              = 0,        
00195     FEAPI_kUnspecifiedError     = -1,       
00196     FEAPI_kIndexOutOfRangeError = -2,       
00197     FEAPI_kInvalidPointerError  = -3,       
00198     FEAPI_kUnknownError         = -9999     
00199 } FEAPI_Error_t;
00200 
00201 
00203 typedef enum FEAPI_VersionInfo_t_tag
00204 {
00205     FEAPI_kMajorVersion    = 0,        
00206     FEAPI_kMinorVersion    = 1,        
00207     FEAPI_kSubVersion      = 2         
00208 } FEAPI_VersionInfo_t;
00209 
00210 
00212 typedef enum FEAPI_PluginProperty_t_tag
00213 {
00214     FEAPI_kMinSampleRate    = 0,        
00215     FEAPI_kMaxSampleRate    = 1,        
00216     FEAPI_kMinChannels      = 2,        
00217     FEAPI_kMaxChannels      = 3,        
00218     FEAPI_kMinFrameSize     = 4,        
00219     FEAPI_kMaxFrameSize     = 5,        
00220     FEAPI_kOptFrameSize     = 6         
00221 } FEAPI_PluginProperty_t;
00222 
00225 
00226 // API function declaration
00239     typedef FEAPI_Error_t   (*FEAPI_CreatePluginInstance_t) ( FEAPI_PluginInstance_t *phInstanceHandle );
00240 
00247     typedef FEAPI_Error_t   (*FEAPI_DestroyPluginInstance_t) ( FEAPI_PluginInstance_t *phInstanceHandle );
00248 
00261     typedef FEAPI_Error_t   (*FEAPI_InitializePlugin_t) (FEAPI_PluginInstance_t hInstanceHandle, 
00262                                                             float               fInputSampleRate, 
00263                                                             int                 iNumberOfAudioChannels,
00264                                                             int                 iHostApiMajorVersion,
00265                                                             FEAPI_UserData_t     *pstUserData);
00266 
00267 
00276     typedef unsigned int (*FEAPI_GetPluginAPIVersion_t) ( FEAPI_VersionInfo_t eAPIMajorMinorOrSubVersion );
00277 
00278 
00286     typedef FEAPI_Error_t (*FEAPI_GetPluginName_t) ( FEAPI_PluginInstance_t hInstanceHandle, 
00287                                                                     char    *pcPluginName);
00288 
00296     typedef FEAPI_Error_t (*FEAPI_GetPluginVendor_t) (FEAPI_PluginInstance_t hInstanceHandle, 
00297                                                                     char    *pcPluginVendor);
00298 
00306     typedef float (*FEAPI_GetPluginProperty_t) (FEAPI_PluginInstance_t hInstanceHandle, 
00307                                                 FEAPI_PluginProperty_t ePluginProperty);
00308 
00316     typedef FEAPI_Error_t (*FEAPI_GetPluginId_t) (FEAPI_PluginInstance_t hInstanceHandle, 
00317                                                                     char *pcPluginId);
00318 
00326     typedef unsigned int (*FEAPI_GetPluginVendorVersion_t) ( FEAPI_PluginInstance_t  hInstanceHandle, 
00327                                                     FEAPI_VersionInfo_t     ePluginMajorMinorOrSubVersion); 
00328 
00336     typedef FEAPI_Error_t (*FEAPI_GetPluginDescription_t) (FEAPI_PluginInstance_t hInstanceHandle, 
00337                                                                             char *pcPluginDescription);
00338 
00346     typedef FEAPI_Error_t (*FEAPI_GetPluginCopyright_t) (FEAPI_PluginInstance_t hInstanceHandle, 
00347                                                                           char *pcPluginCopyright);
00348 
00358     typedef unsigned int (*FEAPI_GetPluginNumOfInputs_t) (FEAPI_PluginInstance_t hInstanceHandle);
00359 
00368     typedef FEAPI_Error_t (*FEAPI_GetPluginInputDescription_t) (FEAPI_PluginInstance_t      hInstanceHandle, 
00369                                                                 int                         iInputIndex, 
00370                                                                 FEAPI_SignalDescription_t   *pstInputDescription);
00371 
00378     typedef unsigned int (*FEAPI_GetPluginNumOfParameters_t) (FEAPI_PluginInstance_t hInstanceHandle);
00379 
00388     typedef FEAPI_Error_t (*FEAPI_GetPluginParameterDescription_t) (FEAPI_PluginInstance_t          hInstanceHandle, 
00389                                                                     int                             iParameterIndex, 
00390                                                                     FEAPI_ParameterDescription_t    *pstParameterDescription);
00391 
00400     typedef FEAPI_Error_t (*FEAPI_SetPluginParameter_t) (   FEAPI_PluginInstance_t  hInstanceHandle, 
00401                                                             int                     iParameterIndex, 
00402                                                             float                   fValue);
00403 
00411     typedef float (*FEAPI_GetPluginParameter_t) (FEAPI_PluginInstance_t hInstanceHandle, 
00412                                                                     int iParameterIndex);
00413 
00423     typedef FEAPI_Error_t (*FEAPI_ProcessPlugin_t) (FEAPI_PluginInstance_t  hInstanceHandle, 
00424                                                     const FEAPI_Signal_t    **ppfInputBuffer, 
00425                                                     const FEAPI_TimeStamp_t *ptFEAPI_TimeStamp, 
00426                                                     int                     iNumberOfFrames);           
00427 
00434     typedef FEAPI_Error_t (*FEAPI_ProcessPluginDone_t) (FEAPI_PluginInstance_t hInstanceHandle);
00435 
00442     typedef unsigned int (*FEAPI_GetPluginNumOfResults_t) (FEAPI_PluginInstance_t hInstanceHandle);
00443 
00452     typedef FEAPI_Error_t (*FEAPI_GetPluginResultDescription_t) (   FEAPI_PluginInstance_t      hInstanceHandle, 
00453                                                                     int                         iResultIndex, 
00454                                                                     FEAPI_SignalDescription_t   *pstResultDescription);
00455 
00463     typedef int (*FEAPI_GetPluginSizeOfResult_t) (FEAPI_PluginInstance_t hInstanceHandle, 
00464                                                                     int iResultIndex);
00465 
00475     typedef FEAPI_Error_t (*FEAPI_GetPluginResult_t) (  FEAPI_PluginInstance_t  hInstanceHandle, 
00476                                                         int                     iResultIndex, 
00477                                                         FEAPI_Signal_t          *pfResult, 
00478                                                         FEAPI_TimeStamp_t       *ptFEAPI_TimeStamp);           
00479 
00488     typedef int (*FEAPI_GetPluginResultLatency_t) (FEAPI_PluginInstance_t hInstanceHandle, int iResultIndex); 
00489 
00496     typedef FEAPI_Error_t (*FEAPI_ResetPlugin_t) (FEAPI_PluginInstance_t hInstanceHandle);
00497 
00501 #ifdef __cplusplus
00502 }
00503 #endif
00504 
00505 
00506 #endif // #if !defined(FEAPI_HEADER_INCLUDED)

Generated on Fri Mar 23 10:28:52 2007 for FEAPI Documentation by  doxygen 1.3.9.1