annotate vamp-hostsdk/host-c.h @ 402:f23dd109144f

And another
author Chris Cannam
date Tue, 16 Jun 2015 12:59:57 +0100
parents 632c662e95e7
children
rev   line source
Chris@389 1 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*- vi:set ts=8 sts=4 sw=4: */
Chris@389 2
Chris@389 3 /*
Chris@389 4 Vamp
Chris@389 5
Chris@389 6 An API for audio analysis and feature extraction plugins.
Chris@389 7
Chris@389 8 Centre for Digital Music, Queen Mary, University of London.
Chris@389 9 Copyright 2006-2015 Chris Cannam and QMUL.
Chris@389 10
Chris@389 11 Permission is hereby granted, free of charge, to any person
Chris@389 12 obtaining a copy of this software and associated documentation
Chris@389 13 files (the "Software"), to deal in the Software without
Chris@389 14 restriction, including without limitation the rights to use, copy,
Chris@389 15 modify, merge, publish, distribute, sublicense, and/or sell copies
Chris@389 16 of the Software, and to permit persons to whom the Software is
Chris@389 17 furnished to do so, subject to the following conditions:
Chris@389 18
Chris@389 19 The above copyright notice and this permission notice shall be
Chris@389 20 included in all copies or substantial portions of the Software.
Chris@389 21
Chris@389 22 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
Chris@389 23 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
Chris@389 24 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
Chris@389 25 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR
Chris@389 26 ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
Chris@389 27 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
Chris@389 28 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Chris@389 29
Chris@389 30 Except as contained in this notice, the names of the Centre for
Chris@389 31 Digital Music; Queen Mary, University of London; and Chris Cannam
Chris@389 32 shall not be used in advertising or otherwise to promote the sale,
Chris@389 33 use or other dealings in this Software without prior written
Chris@389 34 authorization.
Chris@389 35 */
Chris@389 36
Chris@389 37 /*
Chris@389 38 This file defines a low-level API for enumerating and loading
Chris@389 39 plugin libraries using C calling conventions. It could be used in
Chris@393 40 C programs, or in languages with C-compatible foreign-function
Chris@393 41 interfaces. Note that this works by calling to the C++ Vamp host
Chris@393 42 SDK, so any program using this interface must still link against
Chris@393 43 the rest of the Vamp plugin library and the C++ standard library.
Chris@389 44
Chris@389 45 This is not the simplest or easiest interface for hosting Vamp
Chris@389 46 plugins -- if you have the capability to use the C++ API, please
Chris@389 47 do that instead. (Most programs should not even include this
Chris@389 48 header.)
Chris@389 49
Chris@389 50 The C and C++ interfaces provide different abstraction levels:
Chris@389 51
Chris@389 52 In the C++ interface, the class PluginLoader provides a list of
Chris@389 53 keys corresponding to the installed plugins (where a key combines
Chris@389 54 the plugin's library name and plugin identifier into a single
Chris@389 55 string) plus a method to load a single plugin based on its key
Chris@389 56 (obtaining an instance of class Plugin). With the C++ interface
Chris@389 57 you go straight from the key to a live instance of the plugin. The
Chris@389 58 PluginLoader also provides various facilities to adapt the plugin
Chris@389 59 based on your requirements (e.g. to do time- to frequency-domain
Chris@393 60 conversion for you if the plugin requires it).
Chris@389 61
Chris@389 62 This low-level C interface, on the other hand, deals only in
Chris@389 63 plugin libraries and static descriptors, not in plugin
Chris@389 64 instances. You can enumerate the installed libraries, getting just
Chris@389 65 the base .soname of each library. Then you can retrieve each of
Chris@389 66 the raw C plugin descriptors from a library, and use the
Chris@389 67 descriptor (whose interface is defined in vamp/vamp.h) to
Chris@393 68 instantiate the plugin.
Chris@393 69
Chris@393 70 So this header corresponds to the first part of the PluginLoader
Chris@393 71 class interface: finding and loading plugin libraries and
Chris@393 72 retrieving plugin descriptors from them. But it does not do any of
Chris@393 73 the rest, i.e. instantiating and adapting the plugins themselves.
Chris@393 74 Although this makes the API appear very simple, it means the
Chris@393 75 resulting plugins are relatively hard to use compared to those
Chris@393 76 obtained by the PluginLoader API. There is no way to get to the
Chris@393 77 full C++ abstraction using this API.
Chris@389 78
Chris@389 79 This API is not thread-safe; use it from a single application
Chris@389 80 thread, or guard access to it with a mutex.
Chris@389 81
Chris@389 82 This header was introduced in version 2.6 of the Vamp plugin SDK.
Chris@389 83 */
Chris@389 84
Chris@389 85 #ifndef VAMPHOST_C_H_INCLUDED
Chris@389 86 #define VAMPHOST_C_H_INCLUDED
Chris@389 87
Chris@389 88 #include <vamp/vamp.h>
Chris@389 89
Chris@389 90 #ifdef __cplusplus
Chris@389 91 extern "C" {
Chris@389 92 #endif
Chris@389 93
Chris@389 94 typedef struct vhLibrary_t *vhLibrary;
Chris@389 95
Chris@389 96 /**
Chris@389 97 * Return the number of Vamp plugin libraries discovered in the
Chris@389 98 * installation path. This number will remain fixed after the first
Chris@389 99 * call -- plugins are only discovered once, the first time this
Chris@389 100 * function is called.
Chris@389 101 */
Chris@389 102 extern int vhGetLibraryCount();
Chris@389 103
Chris@389 104 /**
Chris@389 105 * Return the library name (base soname) of the library with the given
Chris@389 106 * index, in the range 0..(vhGetLibraryCount()-1).
Chris@389 107 */
Chris@389 108 extern const char *vhGetLibraryName(int library);
Chris@389 109
Chris@389 110 /**
Chris@393 111 * Return the library index for the given library name, or -1 if the
Chris@393 112 * name is not known.
Chris@393 113 */
Chris@393 114 extern int vhGetLibraryIndex(const char *name);
Chris@393 115
Chris@393 116 /**
Chris@393 117 * Load the library with the given index. If the library cannot be
Chris@389 118 * loaded for any reason, the return value is 0; otherwise it is an
Chris@389 119 * opaque pointer suitable for passing to other functions in this API.
Chris@389 120 */
Chris@393 121 extern vhLibrary vhLoadLibrary(int library);
Chris@389 122
Chris@389 123 /**
Chris@389 124 * Return the number of Vamp plugins in the given library.
Chris@389 125 */
Chris@389 126 extern int vhGetPluginCount(vhLibrary library);
Chris@389 127
Chris@389 128 /**
Chris@389 129 * Return a Vamp plugin descriptor for a plugin in a given
Chris@393 130 * library. This simply calls the vampGetPluginDescriptor function in
Chris@393 131 * that library with the given plugin index and returns the
Chris@393 132 * result. See vamp/vamp.h for details about the plugin descriptor.
Chris@389 133 */
Chris@389 134 extern const VampPluginDescriptor *vhGetPluginDescriptor(vhLibrary library,
Chris@389 135 int plugin);
Chris@389 136
Chris@389 137 /**
Chris@389 138 * Unload a plugin library. Do not do this while any of its plugins
Chris@389 139 * are still in use.
Chris@389 140 */
Chris@389 141 extern void vhUnloadLibrary(vhLibrary);
Chris@389 142
Chris@389 143 #ifdef __cplusplus
Chris@389 144 }
Chris@389 145 #endif
Chris@389 146
Chris@389 147 #endif