annotate plugin/api/FEAPI.h @ 0:da6937383da8

initial import
author Chris Cannam
date Tue, 10 Jan 2006 16:33:16 +0000
parents
children
rev   line source
Chris@0 1 ////////////////////////////////////////////////////////////////////////////////////
Chris@0 2 // /*! \file FEAPI.h
Chris@0 3 // \brief interface of the feature extraction plugin.
Chris@0 4 // <br><br>
Chris@0 5 // In the following, context function pointers typedefs are referred to as
Chris@0 6 // functions.<br>
Chris@0 7 //
Chris@0 8 //
Chris@0 9 // Create a new instance of the plugin with the function
Chris@0 10 // ::FEAPI_CreatePluginInstance. The call of this function is mandatory.
Chris@0 11 // <br><br>
Chris@0 12 //
Chris@0 13 // Initialize the plugin with the call of function
Chris@0 14 // ::FEAPI_InitializePlugin.<br><br>
Chris@0 15 //
Chris@0 16 // Information about the plugin can be requested via the following
Chris@0 17 // functions:<br>
Chris@0 18 // ::FEAPI_GetPluginAPIVersion, <br>
Chris@0 19 // ::FEAPI_GetPluginName, <br>
Chris@0 20 // ::FEAPI_GetPluginVendor, <br>
Chris@0 21 // ::FEAPI_GetPluginVendorVersion, <br>
Chris@0 22 // ::FEAPI_GetPluginCopyright, <br>
Chris@0 23 // ::FEAPI_GetPluginDescription. <br>
Chris@0 24 // The call of these functions is optional. Combined with a call to
Chris@0 25 // ::FEAPI_GetPluginId, the plugin can be uniquely identified. <br><br>
Chris@0 26 //
Chris@0 27 // The technical capabilities of the plugin can be requested via the call
Chris@0 28 // of the function
Chris@0 29 // ::FEAPI_GetPluginProperty.<br><br>
Chris@0 30 //
Chris@0 31 // To get the number of the features resp. results that are computed
Chris@0 32 // by the plugin, call the function <br>
Chris@0 33 // ::FEAPI_GetPluginNumOfResults; <br>
Chris@0 34 // the function <br>
Chris@0 35 // ::FEAPI_GetPluginResultDescription gives you detailed information about the
Chris@0 36 // meaning and usage of every result (see structure ::_ResultDescription
Chris@0 37 // for details). <br><br>
Chris@0 38 //
Chris@0 39 // To get the number of the options/ parameter settings that can be
Chris@0 40 // done before processing, call the function <br>
Chris@0 41 // ::FEAPI_GetPluginNumOfParameters; <br>
Chris@0 42 // the function <br>
Chris@0 43 // ::FEAPI_GetPluginParamDescription gives you detailed information about
Chris@0 44 // the meaning and usage of every single parameter (see structure
Chris@0 45 // ::FEAPI_ParameterDescription_t for details).<br><br>
Chris@0 46 //
Chris@0 47 // To get or set a specific parameter value, call the function <br>
Chris@0 48 // ::FEAPI_GetPluginParameter resp. <br>
Chris@0 49 // ::FEAPI_SetPluginParameter. <br><br>
Chris@0 50 //
Chris@0 51 // After the plugin is initialized, the actual processing can begin.
Chris@0 52 // The ::FEAPI_ProcessPlugin <br>
Chris@0 53 // function can be called to do the actual feature/result
Chris@0 54 // calculation. ::FEAPI_ProcessPlugin expects subsequently new blocks
Chris@0 55 // of audio data. Note that ::FEAPI_ProcessPlugin does not return
Chris@0 56 // computed feature values.<br>
Chris@0 57 //
Chris@0 58 // After finishing one ::FEAPI_ProcessPlugin call, zero, one or more
Chris@0 59 // results can be available, depending on the plug-ins implementation.
Chris@0 60 // To query the available number of values for every feature/result,
Chris@0 61 // call <br>
Chris@0 62 // ::FEAPI_GetPluginSizeOfResult, <br>
Chris@0 63 // which returns the number of values for this
Chris@0 64 // result. Afterwards, the result values for each result can
Chris@0 65 // be requested via <br>
Chris@0 66 // ::FEAPI_GetPluginResult. Note that the memory for the results has to be
Chris@0 67 // allocated by the host.<br><br>
Chris@0 68 //
Chris@0 69 // To signal that no more audio data is available at the end (e.g. of
Chris@0 70 // the audio file), call <br>
Chris@0 71 // ::FEAPI_ProcessPluginDone and get the last results with
Chris@0 72 // ::FEAPI_GetPluginResult if available.<br><br>
Chris@0 73 //
Chris@0 74 // To flush the internal buffers, the function <br>
Chris@0 75 // ::FEAPI_ResetPlugin <br>
Chris@0 76 // may be called.
Chris@0 77 //
Chris@0 78 // After all processing has been done, destroy the instance of the
Chris@0 79 // plugin with the function <br>
Chris@0 80 // ::FEAPI_DestroyPluginInstance. <br>
Chris@0 81 // The call of this function is mandatory. <br><br>
Chris@0 82 //
Chris@0 83 // <br><br><br>
Chris@0 84 // The Feature Extraction plugin API is released under a BSD style
Chris@0 85 // license. Please make all changes available to the authors.<br>
Chris@0 86 // Contact information: lerch <at> zplane.de.
Chris@0 87 //
Chris@0 88 // */
Chris@0 89 //
Chris@0 90 // Copyright (c) 2004-2005, Alexander Lerch, zplane.development GbR
Chris@0 91 // All rights reserved.
Chris@0 92 //
Chris@0 93 // Redistribution and use in source and binary forms, with or without
Chris@0 94 // modification, are permitted provided that the following conditions
Chris@0 95 // are met:
Chris@0 96 //
Chris@0 97 // * Redistributions of source code must retain the above copyright
Chris@0 98 // notice, this list of conditions and the following disclaimer.
Chris@0 99 // * Redistributions in binary form must link to the FEAPI website
Chris@0 100 // http://www.sf.net/projects/feapi,
Chris@0 101 // reproduce this list of conditions and the following
Chris@0 102 // disclaimer in the documentation and/or other materials
Chris@0 103 // provided with the distribution.
Chris@0 104 // * The name of the contributors to this software must not be used
Chris@0 105 // to endorse or promote products derived from this software
Chris@0 106 // without specific prior written permission.
Chris@0 107 //
Chris@0 108 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
Chris@0 109 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
Chris@0 110 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
Chris@0 111 // FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
Chris@0 112 // COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
Chris@0 113 // INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
Chris@0 114 // BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
Chris@0 115 // LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
Chris@0 116 // CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
Chris@0 117 // LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
Chris@0 118 // ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
Chris@0 119 // POSSIBILITY OF SUCH DAMAGE.
Chris@0 120 //
Chris@0 121 ////////////////////////////////////////////////////////////////////////////////////
Chris@0 122 // CVS INFORMATION
Chris@0 123 //
Chris@0 124 // $RCSfile: FEAPI.h,v $
Chris@0 125 // $Author: alex_lerch $
Chris@0 126 // $Date: 2005/05/20 17:08:36 $
Chris@0 127 //
Chris@0 128 // $Log: FEAPI.h,v $
Chris@0 129 // Revision 1.2 2005/05/20 17:08:36 alex_lerch
Chris@0 130 // - updated documentation
Chris@0 131 // - added "signal" typedef for inputs and results
Chris@0 132 // - changed function PluginCanDo to PluginGetProperty and changed the function itself to return values instead of bools
Chris@0 133 // - cosmetic changes
Chris@0 134 //
Chris@0 135 // Revision 1.1.1.1 2005/03/30 14:54:40 alex_lerch
Chris@0 136 // first draft version requiring several updates:
Chris@0 137 // - interface check
Chris@0 138 // - check of plugin base class
Chris@0 139 // - implementation of host base class
Chris@0 140 // - update of outdated documentation
Chris@0 141 //
Chris@0 142 //
Chris@0 143 ////////////////////////////////////////////////////////////////////////////////////
Chris@0 144 ////////////////////////////////////////////////////////////////////////////////////
Chris@0 145 // !!!Do never ever edit this file!!!
Chris@0 146 ////////////////////////////////////////////////////////////////////////////////////
Chris@0 147 ////////////////////////////////////////////////////////////////////////////////////
Chris@0 148
Chris@0 149 /*! \brief avoid multiple header includes */
Chris@0 150 #if !defined(FEAPI_HEADER_INCLUDED)
Chris@0 151 #define FEAPI_HEADER_INCLUDED
Chris@0 152
Chris@0 153
Chris@0 154 #ifdef __cplusplus
Chris@0 155 extern "C" {
Chris@0 156 #endif
Chris@0 157
Chris@0 158 /* Maximum string lengths. */
Chris@0 159 const unsigned int FEAPI_uiMaxNameLength = 1024; //!< maximum number of characters for a name string (including null terminator)
Chris@0 160 const unsigned int FEAPI_uiMaxUnitLength = 1024; //!< maximum number of characters for a unit string (including null terminator)
Chris@0 161 const unsigned int FEAPI_uiMaxDescriptionLength = 4096; //!< maximum number of characters for a description string (including null terminator)
Chris@0 162
Chris@0 163 ////////////////////////////////////////////////////////////////////////////////////
Chris@0 164 // interface structures and types
Chris@0 165 /** @defgroup types Interface Structures and Types
Chris@0 166 * @{
Chris@0 167 */
Chris@0 168
Chris@0 169
Chris@0 170 /*! Structure describing properties and other information about one result/feature. */
Chris@0 171 typedef struct FEAPI_SignalDescription_t_tag
Chris@0 172 {
Chris@0 173 char acName[FEAPI_uiMaxNameLength]; //!< name of the result/feature (e.g. "Spectral Centroid", "Loudness", etc.)
Chris@0 174 char acUnit[FEAPI_uiMaxUnitLength]; //!< unit of the result/feature (e.g. "dB", "sone", "Hz", etc.)
Chris@0 175 char acDescription[FEAPI_uiMaxDescriptionLength]; //!< description of the result/feature (clear text description)
Chris@0 176 float fRangeMin; //!< minimum value of the result/feature (if no minimum value: minimum floating point value)
Chris@0 177 float fRangeMax; //!< maximum value of the result/feature (if no maximum value: maximum floating point value)
Chris@0 178 float fQuantizedTo; //!< quantization step size of the result/feature (e.g. 1 for integer result, -1 for no quantization)
Chris@0 179 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 180 } FEAPI_SignalDescription_t;
Chris@0 181
Chris@0 182
Chris@0 183 /*! Structure describing properties and other information about one parameter. */
Chris@0 184 typedef struct FEAPI_ParameterDescription_t_tag
Chris@0 185 {
Chris@0 186 char acName[FEAPI_uiMaxNameLength]; //!< name of the parameter (e.g. "Gain", "Sensitivity", etc.)
Chris@0 187 char acUnit[FEAPI_uiMaxUnitLength]; //!< unit of the parameter (e.g. "dB", "Hz", etc.)
Chris@0 188 char acDescription[FEAPI_uiMaxDescriptionLength]; //!< description of the parameter (clear text description)
Chris@0 189 float fRangeMin, //!< minimum value of the parameter (if no minimum value: minimum floating point value)
Chris@0 190 fRangeMax, //!< maximum value of the parameter (if no maximum value: maximum floating point value)
Chris@0 191 fDefaultValue; //!< default value for the parameter
Chris@0 192 float fQuantizedTo; //!< quantization step size of the parameter (e.g. 1 for integer quantization, -1 for no quantization)
Chris@0 193 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 194 } FEAPI_ParameterDescription_t;
Chris@0 195
Chris@0 196
Chris@0 197 /*! Structure for user/vendor defined commands. */
Chris@0 198 typedef struct FEAPI_UserData_t_tag
Chris@0 199 {
Chris@0 200 char *pcUserString; //!< user defined string value (memory could be freed by host after function call)
Chris@0 201 void *pcUserData; //!< pointer to user defined data
Chris@0 202 } FEAPI_UserData_t;
Chris@0 203
Chris@0 204
Chris@0 205 /*! Typedef for the plugin instance handle. */
Chris@0 206 typedef void* FEAPI_PluginInstance_t;
Chris@0 207
Chris@0 208
Chris@0 209 /*! This typedef is used for time stamps in seconds.
Chris@0 210 For a block of data, the time stamp is defined to be the time at the beginning of the block. */
Chris@0 211 typedef double FEAPI_TimeStamp_t;
Chris@0 212
Chris@0 213
Chris@0 214 /*! This typedef is used for input and output data.
Chris@0 215 At least for this version of the API, this is exactly float. */
Chris@0 216 typedef float FEAPI_Signal_t;
Chris@0 217
Chris@0 218
Chris@0 219 /*! Enumerator for possible error return values, if any other value than FEAPI_kNoError is returned,
Chris@0 220 the function was not able to execute the specified operation(s).<br>
Chris@0 221 All error defines are negative. */
Chris@0 222 typedef enum FEAPI_Error_t_tag
Chris@0 223 {
Chris@0 224 FEAPI_kNoError = 0, //!< no error occurred
Chris@0 225 FEAPI_kUnspecifiedError = -1, //!< an error occurred, but the type is not yet specified
Chris@0 226 FEAPI_kUnknownError = -9999 //!< an error occurred, but its type is not specifyable
Chris@0 227 } FEAPI_Error_t;
Chris@0 228
Chris@0 229
Chris@0 230 /*! Enumerator for retrieval of version info which can be resolved as major.minor.sub. */
Chris@0 231 typedef enum FEAPI_VersionInfo_t_tag
Chris@0 232 {
Chris@0 233 FEAPI_kMajorVersion = 0, //!< indicates the major version
Chris@0 234 FEAPI_kMinorVersion = 1, //!< indicates the minor version
Chris@0 235 FEAPI_kSubVersion = 2 //!< indicates the sub version or bug-fix version
Chris@0 236 } FEAPI_VersionInfo_t;
Chris@0 237
Chris@0 238
Chris@0 239 /*! Enumerator for retrieval of information about what the plug supports. */
Chris@0 240 typedef enum FEAPI_PluginProperty_t_tag
Chris@0 241 {
Chris@0 242 FEAPI_kMinSampleRate = 0, //!< indicates the minimum sample rate
Chris@0 243 FEAPI_kMaxSampleRate = 1, //!< indicates the maximum sample rate
Chris@0 244 FEAPI_kMinChannels = 2, //!< indicates minimum number of channels
Chris@0 245 FEAPI_kMaxChannels = 3, //!< indicates maximum number of channels
Chris@0 246 FEAPI_kMinFrameSize = 4, //!< indicates minimum number of frames per process call
Chris@0 247 FEAPI_kMaxFrameSize = 5, //!< indicates maximum number of frames per process call
Chris@0 248 FEAPI_kOptFrameSize = 6 //!< indicates optimal number of frames per process call
Chris@0 249 } FEAPI_PluginProperty_t;
Chris@0 250
Chris@0 251 /** @} */
Chris@0 252
Chris@0 253 ////////////////////////////////////////////////////////////////////////////////////
Chris@0 254 // API function declaration
Chris@0 255 /** @defgroup apifun API function pointers
Chris@0 256 * @{
Chris@0 257 */
Chris@0 258
Chris@0 259 /*!
Chris@0 260 * Creates a new instance of the plugin
Chris@0 261 *
Chris@0 262 * @param phInstanceHandle : handle to the instance to be created
Chris@0 263 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 264 */
Chris@0 265 typedef FEAPI_Error_t (*FEAPI_CreatePluginInstance_t) ( FEAPI_PluginInstance_t *phInstanceHandle );
Chris@0 266
Chris@0 267 /*!
Chris@0 268 * Destroys an instance of the plugin.
Chris@0 269 *
Chris@0 270 * @param phInstanceHandle : handle to the instance to be destroyed
Chris@0 271 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 272 */
Chris@0 273 typedef FEAPI_Error_t (*FEAPI_DestroyPluginInstance_t) ( FEAPI_PluginInstance_t *phInstanceHandle );
Chris@0 274
Chris@0 275 /*!
Chris@0 276 * initializes a new instance of the plugin
Chris@0 277 *
Chris@0 278 * @param hInstanceHandle : handle to the instance
Chris@0 279 * @param fInputSampleRate : sample rate of input(s) in Hz
Chris@0 280 * @param iNumberOfAudioChannels : number of input audio channels
Chris@0 281 * @param iHostApiMajorVersion : major version number of host
Chris@0 282 * @param pstUserData : pointer to user or vendor defined data (may be NULL)
Chris@0 283 *
Chris@0 284 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 285 */
Chris@0 286 typedef FEAPI_Error_t (*FEAPI_InitializePlugin_t) (FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 287 float fInputSampleRate,
Chris@0 288 int iNumberOfAudioChannels,
Chris@0 289 int iHostApiMajorVersion,
Chris@0 290 FEAPI_UserData_t *pstUserData);
Chris@0 291
Chris@0 292
Chris@0 293 /*!
Chris@0 294 * Gets the version number (major, minor or subversion) of the API used by the plugin.
Chris@0 295 * This is *not* the plugin version, therefore the function may be called without a previously
Chris@0 296 * created instance.
Chris@0 297 *
Chris@0 298 * @param eAPIMajorMinorOrSubVersion : flag which version type is requested
Chris@0 299 * @return int : requested version number
Chris@0 300 */
Chris@0 301 typedef int (*FEAPI_GetPluginAPIVersion_t) ( FEAPI_VersionInfo_t eAPIMajorMinorOrSubVersion ); //!< \todo change ints to (unsigned) ints where appropriate?
Chris@0 302
Chris@0 303
Chris@0 304 /*!
Chris@0 305 * Gets the name of the plugin.
Chris@0 306 *
Chris@0 307 * @param hInstanceHandle : handle to instance
Chris@0 308 * @param *pcPluginName : pointer to buffer of FEAPI_uiMaxNameLength chars, the name will be copied to this buffer
Chris@0 309 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 310 */
Chris@0 311 typedef FEAPI_Error_t (*FEAPI_GetPluginName_t) ( FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 312 char *pcPluginName);
Chris@0 313
Chris@0 314 /*!
Chris@0 315 * Gets the vendor name of the plugin.
Chris@0 316 *
Chris@0 317 * @param hInstanceHandle : handle to instance
Chris@0 318 * @param *pcPluginVendor : pointer to buffer of FEAPI_uiMaxNameLength chars, the vendor name will be copied to this buffer
Chris@0 319 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 320 */
Chris@0 321 typedef FEAPI_Error_t (*FEAPI_GetPluginVendor_t) (FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 322 char *pcPluginVendor);
Chris@0 323
Chris@0 324 /*!
Chris@0 325 * Gets an indication of the plugins capabilities.
Chris@0 326 *
Chris@0 327 * @param hInstanceHandle : handle to instance
Chris@0 328 * @param ePluginProperty : requested property
Chris@0 329 * @return float : corresponding value
Chris@0 330 */
Chris@0 331 typedef float (*FEAPI_GetPluginProperty_t) (FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 332 FEAPI_PluginProperty_t ePluginProperty);
Chris@0 333
Chris@0 334 /*!
Chris@0 335 * Gets the (vendor unique) plugin identification string.
Chris@0 336 *
Chris@0 337 * @param hInstanceHandle : handle to instance
Chris@0 338 * @param *pcPluginId : pointer to buffer of FEAPI_uiMaxNameLength chars, the id will be copied to this buffer
Chris@0 339 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 340 */
Chris@0 341 typedef FEAPI_Error_t (*FEAPI_GetPluginId_t) (FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 342 char *pcPluginId);
Chris@0 343
Chris@0 344 /*!
Chris@0 345 * Gets the vendor version of the plugin.
Chris@0 346 *
Chris@0 347 * @param hInstanceHandle : handle to instance
Chris@0 348 * @param ePluginMajorMinorOrSubVersion : flag which version type is requested
Chris@0 349 * @return int : requested version number
Chris@0 350 */
Chris@0 351 typedef int (*FEAPI_GetPluginVendorVersion_t) ( FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 352 FEAPI_VersionInfo_t ePluginMajorMinorOrSubVersion);
Chris@0 353
Chris@0 354 /*!
Chris@0 355 * Gets the description of the plugin, containing information about what the plugin actually does.
Chris@0 356 *
Chris@0 357 * @param hInstanceHandle : handle to instance
Chris@0 358 * @param *pcPluginDescription : pointer to buffer of FEAPI_uiMaxDescriptionLength chars, the plugin description will be copied to this buffer
Chris@0 359 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 360 */
Chris@0 361 typedef FEAPI_Error_t (*FEAPI_GetPluginDescription_t) (FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 362 char *pcPluginDescription);
Chris@0 363
Chris@0 364 /*!
Chris@0 365 * Gets the copyright information for the plugin.
Chris@0 366 *
Chris@0 367 * @param hInstanceHandle : handle to instance
Chris@0 368 * @param *pcPluginCopyright : pointer to buffer of FEAPI_uiMaxDescriptionLength chars, the plugin copyright information will be copied to this buffer
Chris@0 369 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 370 */
Chris@0 371 typedef FEAPI_Error_t (*FEAPI_GetPluginCopyright_t) (FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 372 char *pcPluginCopyright);
Chris@0 373
Chris@0 374 /*!
Chris@0 375 * Gets the number of inputs for the plugin. This number will equal the
Chris@0 376 * number of audio channels in many cases, otherwise exceed the number of audio channels.
Chris@0 377 * The additional input channels are plugin developer specific and not recommended. If used,
Chris@0 378 * they have to be routed host internally.
Chris@0 379 *
Chris@0 380 * @param hInstanceHandle : handle to instance
Chris@0 381 * @return int : number of inputs
Chris@0 382 */
Chris@0 383 typedef int (*FEAPI_GetPluginNumOfInputs_t) (FEAPI_PluginInstance_t hInstanceHandle);
Chris@0 384
Chris@0 385 /*!
Chris@0 386 * Gets information about one of the possible inputs.
Chris@0 387 *
Chris@0 388 * @param hInstanceHandle : handle to instance
Chris@0 389 * @param iInputIndex : index of the input the description is requested for, index ranges from 0...NumOfInputs-1
Chris@0 390 * @param *pstInputDescription : the requested description will be copied to this structure
Chris@0 391 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 392 */
Chris@0 393 typedef FEAPI_Error_t (*FEAPI_GetPluginInputDescription_t) (FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 394 int iInputIndex,
Chris@0 395 FEAPI_SignalDescription_t *pstInputDescription);
Chris@0 396
Chris@0 397 /*!
Chris@0 398 * Gets the number of parameters.
Chris@0 399 *
Chris@0 400 * @param hInstanceHandle : handle to instance
Chris@0 401 * @return int : number of parameters
Chris@0 402 */
Chris@0 403 typedef int (*FEAPI_GetPluginNumOfParameters_t) (FEAPI_PluginInstance_t hInstanceHandle);
Chris@0 404
Chris@0 405 /*!
Chris@0 406 * Gets information about one of the possible parameters.
Chris@0 407 *
Chris@0 408 * @param hInstanceHandle : handle to instance
Chris@0 409 * @param iParameterIndex : index of the parameter (setting) the description is requested for, index ranges from 0...NumOfParameters-1
Chris@0 410 * @param *pstParameterDescription : the requested description will be copied to this structure
Chris@0 411 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 412 */
Chris@0 413 typedef FEAPI_Error_t (*FEAPI_GetPluginParameterDescription_t) (FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 414 int iParameterIndex,
Chris@0 415 FEAPI_ParameterDescription_t *pstParameterDescription);
Chris@0 416
Chris@0 417 /*!
Chris@0 418 * Sets a parameter to a specified value.
Chris@0 419 *
Chris@0 420 * @param hInstanceHandle : handle to instance
Chris@0 421 * @param iParameterIndex : index of the parameter (setting) to be changed, index ranges from 0...NumOfParameters-1
Chris@0 422 * @param fValue : new value of the parameter
Chris@0 423 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 424 */
Chris@0 425 typedef FEAPI_Error_t (*FEAPI_SetPluginParameter_t) ( FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 426 int iParameterIndex,
Chris@0 427 float fValue);
Chris@0 428
Chris@0 429 /*!
Chris@0 430 * Gets the current value of a parameter.
Chris@0 431 *
Chris@0 432 * @param hInstanceHandle : handle to instance
Chris@0 433 * @param iParameterIndex : index of the parameter (setting) requested, index ranges from 0...NumOfParameters-1
Chris@0 434 * @return float : value of the parameter with index iParameterIndex
Chris@0 435 */
Chris@0 436 typedef float (*FEAPI_GetPluginParameter_t) (FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 437 int iParameterIndex);
Chris@0 438
Chris@0 439 /*!
Chris@0 440 * Processes a block of audio data.
Chris@0 441 *
Chris@0 442 * @param hInstanceHandle : handle to instance
Chris@0 443 * @param **ppfInputBuffer : input audio data in the format [channels][samples]; audio samples have a range from -1.0...+1.0
Chris@0 444 * @param *ptFEAPI_TimeStamp : time stamps in seconds for every input, may be NULL
Chris@0 445 * @param iNumberOfFrames : number of frames in ppfInputBuffer
Chris@0 446 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 447 */
Chris@0 448 typedef FEAPI_Error_t (*FEAPI_ProcessPlugin_t) (FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 449 const FEAPI_Signal_t **ppfInputBuffer,
Chris@0 450 const FEAPI_TimeStamp_t *ptFEAPI_TimeStamp,
Chris@0 451 int iNumberOfFrames);
Chris@0 452
Chris@0 453 /*!
Chris@0 454 * Signals that no more input data is available (does the final processing).
Chris@0 455 *
Chris@0 456 * @param hInstanceHandle : handle to instance
Chris@0 457 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 458 */
Chris@0 459 typedef FEAPI_Error_t (*FEAPI_ProcessPluginDone_t) (FEAPI_PluginInstance_t hInstanceHandle);
Chris@0 460
Chris@0 461 /*!
Chris@0 462 * Gets the number of results/features to be calculated.
Chris@0 463 *
Chris@0 464 * @param hInstanceHandle : handle to instance
Chris@0 465 * @return int : number of results
Chris@0 466 */
Chris@0 467 typedef int (*FEAPI_GetPluginNumOfResults_t) (FEAPI_PluginInstance_t hInstanceHandle);
Chris@0 468
Chris@0 469 /*!
Chris@0 470 * Gets information about one of the possible results/features.
Chris@0 471 *
Chris@0 472 * @param hInstanceHandle : handle to instance
Chris@0 473 * @param iResultIndex : index of the result (feature) the description is requested for, index ranges from 0...NumOfResults-1
Chris@0 474 * @param *pstResultDescription : the requested description will be copied to this structure
Chris@0 475 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 476 */
Chris@0 477 typedef FEAPI_Error_t (*FEAPI_GetPluginResultDescription_t) ( FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 478 int iResultIndex,
Chris@0 479 FEAPI_SignalDescription_t *pstResultDescription);
Chris@0 480
Chris@0 481 /*!
Chris@0 482 * Gets the size of one result in FEAPI_Signal_t values (4 bytes per value).
Chris@0 483 *
Chris@0 484 * @param hInstanceHandle : handle to instance
Chris@0 485 * @param iResultIndex : index of the result/feature the size is requested for, index ranges from 0...NumOfResults-1
Chris@0 486 * @return int : size of result in FEAPI_Signal_t values (4 bytes per value)
Chris@0 487 */
Chris@0 488 typedef int (*FEAPI_GetPluginSizeOfResult_t) (FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 489 int iResultIndex);
Chris@0 490
Chris@0 491 /*!
Chris@0 492 * Gets one result.
Chris@0 493 *
Chris@0 494 * @param hInstanceHandle : handle to instance
Chris@0 495 * @param iResultIndex : index of the requested result/feature, index ranges from 0...NumOfResults-1
Chris@0 496 * @param *pfResult : the result data is copied into this buffer
Chris@0 497 * @param *ptFEAPI_TimeStamp : the time stamp of the result
Chris@0 498 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 499 */
Chris@0 500 typedef FEAPI_Error_t (*FEAPI_GetPluginResult_t) ( FEAPI_PluginInstance_t hInstanceHandle,
Chris@0 501 int iResultIndex,
Chris@0 502 FEAPI_Signal_t *pfResult,
Chris@0 503 FEAPI_TimeStamp_t *ptFEAPI_TimeStamp);
Chris@0 504
Chris@0 505 /*!
Chris@0 506 * Gets the maximum latency of one result. Since the host buffer size may vary, this is only the
Chris@0 507 * *internal* latency.
Chris@0 508 *
Chris@0 509 * @param hInstanceHandle : handle to instance
Chris@0 510 * @param iResultIndex : index of the requested result (feature), index ranges from 0...NumOfResults-1
Chris@0 511 * @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 512 */
Chris@0 513 typedef int (*FEAPI_GetPluginResultLatency_t) (FEAPI_PluginInstance_t hInstanceHandle, int iResultIndex);
Chris@0 514
Chris@0 515 /*!
Chris@0 516 * 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 517 *
Chris@0 518 * @param hInstanceHandle : handle to instance
Chris@0 519 * @return FEAPI_Error_t : FEAPI_kNoError when no error
Chris@0 520 */
Chris@0 521 typedef FEAPI_Error_t (*FEAPI_ResetPlugin_t) (FEAPI_PluginInstance_t hInstanceHandle);
Chris@0 522
Chris@0 523 /** @} */
Chris@0 524
Chris@0 525
Chris@0 526 #ifdef __cplusplus
Chris@0 527 }
Chris@0 528 #endif
Chris@0 529
Chris@0 530
Chris@0 531 #endif // #if !defined(FEAPI_HEADER_INCLUDED)