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