Chris@389: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
Chris@389: 
Chris@389: /*
Chris@389:     Vamp
Chris@389: 
Chris@389:     An API for audio analysis and feature extraction plugins.
Chris@389: 
Chris@389:     Centre for Digital Music, Queen Mary, University of London.
Chris@389:     Copyright 2006-2015 Chris Cannam and QMUL.
Chris@389:   
Chris@389:     Permission is hereby granted, free of charge, to any person
Chris@389:     obtaining a copy of this software and associated documentation
Chris@389:     files (the "Software"), to deal in the Software without
Chris@389:     restriction, including without limitation the rights to use, copy,
Chris@389:     modify, merge, publish, distribute, sublicense, and/or sell copies
Chris@389:     of the Software, and to permit persons to whom the Software is
Chris@389:     furnished to do so, subject to the following conditions:
Chris@389: 
Chris@389:     The above copyright notice and this permission notice shall be
Chris@389:     included in all copies or substantial portions of the Software.
Chris@389: 
Chris@389:     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
Chris@389:     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
Chris@389:     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
Chris@389:     NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
Chris@389:     ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
Chris@389:     CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
Chris@389:     WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Chris@389: 
Chris@389:     Except as contained in this notice, the names of the Centre for
Chris@389:     Digital Music; Queen Mary, University of London; and Chris Cannam
Chris@389:     shall not be used in advertising or otherwise to promote the sale,
Chris@389:     use or other dealings in this Software without prior written
Chris@389:     authorization.
Chris@389: */
Chris@389: 
Chris@389: /*
Chris@389:     This file defines a low-level API for enumerating and loading
Chris@389:     plugin libraries using C calling conventions. It could be used in
Chris@393:     C programs, or in languages with C-compatible foreign-function
Chris@393:     interfaces. Note that this works by calling to the C++ Vamp host
Chris@393:     SDK, so any program using this interface must still link against
Chris@393:     the rest of the Vamp plugin library and the C++ standard library.
Chris@389: 
Chris@389:     This is not the simplest or easiest interface for hosting Vamp
Chris@389:     plugins -- if you have the capability to use the C++ API, please
Chris@389:     do that instead. (Most programs should not even include this
Chris@389:     header.)
Chris@389: 
Chris@389:     The C and C++ interfaces provide different abstraction levels:
Chris@389: 
Chris@389:     In the C++ interface, the class PluginLoader provides a list of
Chris@389:     keys corresponding to the installed plugins (where a key combines
Chris@389:     the plugin's library name and plugin identifier into a single
Chris@389:     string) plus a method to load a single plugin based on its key
Chris@389:     (obtaining an instance of class Plugin). With the C++ interface
Chris@389:     you go straight from the key to a live instance of the plugin. The
Chris@389:     PluginLoader also provides various facilities to adapt the plugin
Chris@389:     based on your requirements (e.g. to do time- to frequency-domain
Chris@393:     conversion for you if the plugin requires it).
Chris@389: 
Chris@389:     This low-level C interface, on the other hand, deals only in
Chris@389:     plugin libraries and static descriptors, not in plugin
Chris@389:     instances. You can enumerate the installed libraries, getting just
Chris@389:     the base .soname of each library. Then you can retrieve each of
Chris@389:     the raw C plugin descriptors from a library, and use the
Chris@389:     descriptor (whose interface is defined in vamp/vamp.h) to
Chris@393:     instantiate the plugin.
Chris@393: 
Chris@393:     So this header corresponds to the first part of the PluginLoader
Chris@393:     class interface: finding and loading plugin libraries and
Chris@393:     retrieving plugin descriptors from them. But it does not do any of
Chris@393:     the rest, i.e. instantiating and adapting the plugins themselves.
Chris@393:     Although this makes the API appear very simple, it means the
Chris@393:     resulting plugins are relatively hard to use compared to those
Chris@393:     obtained by the PluginLoader API. There is no way to get to the
Chris@393:     full C++ abstraction using this API.
Chris@389: 
Chris@389:     This API is not thread-safe; use it from a single application
Chris@389:     thread, or guard access to it with a mutex.
Chris@389: 
Chris@389:     This header was introduced in version 2.6 of the Vamp plugin SDK.
Chris@389: */
Chris@389: 
Chris@389: #ifndef VAMPHOST_C_H_INCLUDED
Chris@389: #define VAMPHOST_C_H_INCLUDED
Chris@389: 
Chris@389: #include <vamp/vamp.h>
Chris@389: 
Chris@389: #ifdef __cplusplus
Chris@389: extern "C" {
Chris@389: #endif
Chris@389: 
Chris@389: typedef struct vhLibrary_t *vhLibrary;
Chris@389: 
Chris@389: /**
Chris@389:  * Return the number of Vamp plugin libraries discovered in the
Chris@389:  * installation path. This number will remain fixed after the first
Chris@389:  * call -- plugins are only discovered once, the first time this
Chris@389:  * function is called.
Chris@389:  */
Chris@389: extern int vhGetLibraryCount();
Chris@389: 
Chris@389: /**
Chris@389:  * Return the library name (base soname) of the library with the given
Chris@389:  * index, in the range 0..(vhGetLibraryCount()-1).
Chris@389:  */
Chris@389: extern const char *vhGetLibraryName(int library);
Chris@389: 
Chris@389: /**
Chris@393:  * Return the library index for the given library name, or -1 if the
Chris@393:  * name is not known.
Chris@393:  */
Chris@393: extern int vhGetLibraryIndex(const char *name);
Chris@393:     
Chris@393: /**
Chris@393:  * Load the library with the given index. If the library cannot be
Chris@389:  * loaded for any reason, the return value is 0; otherwise it is an
Chris@389:  * opaque pointer suitable for passing to other functions in this API.
Chris@389:  */
Chris@393: extern vhLibrary vhLoadLibrary(int library);
Chris@389: 
Chris@389: /**
Chris@389:  * Return the number of Vamp plugins in the given library.
Chris@389:  */
Chris@389: extern int vhGetPluginCount(vhLibrary library);
Chris@389: 
Chris@389: /**
Chris@389:  * Return a Vamp plugin descriptor for a plugin in a given
Chris@393:  * library. This simply calls the vampGetPluginDescriptor function in
Chris@393:  * that library with the given plugin index and returns the
Chris@393:  * result. See vamp/vamp.h for details about the plugin descriptor.
Chris@389:  */ 
Chris@389: extern const VampPluginDescriptor *vhGetPluginDescriptor(vhLibrary library,
Chris@389: 							 int plugin);
Chris@389: 
Chris@389: /**
Chris@389:  * Unload a plugin library. Do not do this while any of its plugins
Chris@389:  * are still in use.
Chris@389:  */
Chris@389: extern void vhUnloadLibrary(vhLibrary);
Chris@389:     
Chris@389: #ifdef __cplusplus
Chris@389: }
Chris@389: #endif
Chris@389: 
Chris@389: #endif