# HG changeset patch # User cannam # Date 1175274856 0 # Node ID 933fee59d33aac77f0433116fbc340cbabacb36c # Parent 74822738965b855a5cf0f0411049f6b6a2f9b1ec * doc updates diff -r 74822738965b -r 933fee59d33a Doxyfile --- a/Doxyfile Wed Mar 21 14:15:25 2007 +0000 +++ b/Doxyfile Fri Mar 30 17:14:16 2007 +0000 @@ -138,7 +138,7 @@ # comments will behave just like the Qt-style comments (thus requiring an # explicit @brief command for a brief description. -JAVADOC_AUTOBRIEF = NO +JAVADOC_AUTOBRIEF = YES # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen # treat a multi-line C++ special comment block (i.e. a block of //! or /// @@ -153,7 +153,7 @@ # If set to NO, the detailed description appears after the member # documentation. -DETAILS_AT_TOP = NO +DETAILS_AT_TOP = YES # If the INHERIT_DOCS tag is set to YES (the default) then an undocumented # member inherits the documentation from any documented member that it @@ -450,7 +450,7 @@ # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = vamp vamp-sdk +INPUT = vamp vamp-sdk examples host # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp @@ -462,13 +462,14 @@ FILE_PATTERNS = *.h \ *.C \ *.cpp \ - *.cc + *.cc \ + doc-overview # The RECURSIVE tag can be used to turn specify whether or not subdirectories # should be searched for input files as well. Possible values are YES and NO. # If left blank NO is used. -RECURSIVE = YES +RECURSIVE = NO # The EXCLUDE tag can be used to specify files and/or directories that should # excluded from the INPUT source files. This way you can easily exclude a @@ -488,7 +489,9 @@ # against the file with absolute path, so to exclude all test directories # for example use the pattern */test/* -EXCLUDE_PATTERNS = *.moc.cpp \ +EXCLUDE_PATTERNS = qrc_*.cpp \ + moc_*.cpp \ + *.moc.cpp \ *_skel.cpp # The EXAMPLE_PATH tag can be used to specify one or more files or @@ -582,7 +585,7 @@ # tagging system (see http://www.gnu.org/software/global/global.html). You # will need version 4.8.6 or higher. -USE_HTAGS = NO +#USE_HTAGS = NO # If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen # will generate a verbatim copy of the header file for each class for @@ -604,7 +607,7 @@ # the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns # in which this list will be split (can be a number in the range [1..20]) -COLS_IN_ALPHA_INDEX = 5 +COLS_IN_ALPHA_INDEX = 3 # In case all classes in a project start with a common prefix, all # classes will be put under the same header in the alphabetical index. @@ -717,7 +720,7 @@ # Netscape 6.0+, Internet explorer 5.0+, or Konqueror). Windows users are # probably better off using the HTML help feature. -GENERATE_TREEVIEW = NO +GENERATE_TREEVIEW = YES # If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be # used to set the initial width (in pixels) of the frame in which the tree @@ -977,20 +980,20 @@ # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files # in the INCLUDE_PATH (see below) will be search if a #include is found. -SEARCH_INCLUDES = YES +SEARCH_INCLUDES = NO # The INCLUDE_PATH tag can be used to specify one or more directories that # contain include files that are not input files but should be processed by # the preprocessor. -INCLUDE_PATH = +INCLUDE_PATH = # You can use the INCLUDE_FILE_PATTERNS tag to specify one or more wildcard # patterns (like *.h and *.hpp) to filter out the header-files in the # directories. If left blank, the patterns specified with FILE_PATTERNS will # be used. -INCLUDE_FILE_PATTERNS = +INCLUDE_FILE_PATTERNS = # The PREDEFINED tag can be used to specify one or more macro names that # are defined before the preprocessor is started (similar to the -D option of @@ -1000,7 +1003,7 @@ # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = HAVE_ALSA HAVE_LIBJACK HAVE_DSSI HAVE_LADSPA HAVE_LIBLO HAVE_LIBLRDF HAVE_XFT HAVE_LIRC +PREDEFINED = HAVE_FFTW3F HAVE_FISHSOUND HAVE_JACK HAVE_LIBLO HAVE_LRDF HAVE_MAD HAVE_OGGZ HAVE_PORTAUDIO HAVE_SAMPLERATE HAVE_SNDFILE HAVE_VAMP # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. @@ -1071,7 +1074,7 @@ # fallback. It is recommended to install and use dot, since it yields more # powerful graphs. -CLASS_DIAGRAMS = YES +CLASS_DIAGRAMS = NO # If set to YES, the inheritance and collaboration graphs will hide # inheritance and usage relations if the target is undocumented @@ -1084,7 +1087,7 @@ # toolkit from AT&T and Lucent Bell Labs. The other options in this section # have no effect if this option is set to NO (the default) -HAVE_DOT = NO +HAVE_DOT = YES # If the CLASS_GRAPH and HAVE_DOT tags are set to YES then doxygen # will generate a graph for each documented class showing the direct and @@ -1098,7 +1101,7 @@ # indirect implementation dependencies (inheritance, containment, and # class references variables) of the class with other documented classes. -COLLABORATION_GRAPH = YES +COLLABORATION_GRAPH = NO # If the GROUP_GRAPHS and HAVE_DOT tags are set to YES then doxygen # will generate a graph for groups, showing the direct groups dependencies @@ -1208,7 +1211,7 @@ # makes dot run faster, but since only newer versions of dot (>1.8.10) # support this, this feature is disabled by default. -DOT_MULTI_TARGETS = NO +DOT_MULTI_TARGETS = YES # If the GENERATE_LEGEND tag is set to YES (the default) Doxygen will # generate a legend page explaining the meaning of the various boxes and diff -r 74822738965b -r 933fee59d33a examples/AmplitudeFollower.cpp --- a/examples/AmplitudeFollower.cpp Wed Mar 21 14:15:25 2007 +0000 +++ b/examples/AmplitudeFollower.cpp Fri Mar 30 17:14:16 2007 +0000 @@ -47,7 +47,7 @@ using std::cerr; using std::endl; -/* +/** * An implementation of SuperCollider's amplitude-follower algorithm * as a simple Vamp plugin. */ diff -r 74822738965b -r 933fee59d33a examples/AmplitudeFollower.h --- a/examples/AmplitudeFollower.h Wed Mar 21 14:15:25 2007 +0000 +++ b/examples/AmplitudeFollower.h Fri Mar 30 17:14:16 2007 +0000 @@ -39,6 +39,11 @@ #include "Plugin.h" +/** + * Example plugin implementing the SuperCollider amplitude follower + * function. + */ + class AmplitudeFollower : public Vamp::Plugin { public: diff -r 74822738965b -r 933fee59d33a examples/PercussionOnsetDetector.h --- a/examples/PercussionOnsetDetector.h Wed Mar 21 14:15:25 2007 +0000 +++ b/examples/PercussionOnsetDetector.h Fri Mar 30 17:14:16 2007 +0000 @@ -39,6 +39,10 @@ #include "Plugin.h" +/** + * Example plugin that detects percussive events. + */ + class PercussionOnsetDetector : public Vamp::Plugin { public: diff -r 74822738965b -r 933fee59d33a examples/SpectralCentroid.h --- a/examples/SpectralCentroid.h Wed Mar 21 14:15:25 2007 +0000 +++ b/examples/SpectralCentroid.h Fri Mar 30 17:14:16 2007 +0000 @@ -39,6 +39,11 @@ #include "Plugin.h" +/** + * Example plugin that calculates the centre of gravity of the + * frequency domain representation of each block of audio. + */ + class SpectralCentroid : public Vamp::Plugin { public: diff -r 74822738965b -r 933fee59d33a examples/ZeroCrossing.h --- a/examples/ZeroCrossing.h Wed Mar 21 14:15:25 2007 +0000 +++ b/examples/ZeroCrossing.h Fri Mar 30 17:14:16 2007 +0000 @@ -39,6 +39,11 @@ #include "Plugin.h" +/** + * Example plugin that calculates the positions and density of + * zero-crossing points in an audio waveform. +*/ + class ZeroCrossing : public Vamp::Plugin { public: diff -r 74822738965b -r 933fee59d33a vamp-sdk/doc-overview --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/vamp-sdk/doc-overview Fri Mar 30 17:14:16 2007 +0000 @@ -0,0 +1,94 @@ + +/** \mainpage Vamp Plugin SDK + +\section about About Vamp + +Vamp is an API for C and C++ plugins that process sampled audio data +to produce descriptive output (measurements or semantic observations). +Find more information at http://www.vamp-plugins.org/ . + +Although the official API for Vamp plugins is defined in C for maximum +binary compatibility, we strongly recommend using the provided C++ +classes in the SDK to implement your own plugins and hosts. + +\section plugins For Plugins + +Plugins should subclass Vamp::Plugin, and then use a +Vamp::PluginAdapter to expose the correct C API for the plugin. Read +the documentation for Vamp::PluginBase and Vamp::Plugin before +starting. + +Plugins should be compiled and linked into dynamic libraries using the +usual convention for your platform, and should link (preferably +statically) with -lvamp-sdk. Any number of plugins can reside in a +single dynamic library. See plugins.cpp in the example plugins +directory for the sort of code that will need to accompany your plugin +class or classes, to make it possible for a host to look up your +plugins properly. + +The following example plugins are provided: + + - ZeroCrossing calculates the positions and density of zero-crossing + points in an audio waveform. + + - SpectralCentroid calculates the centre of gravity of the frequency + domain representation of each block of audio. + + - AmplitudeFollower is an implementation of SuperCollider's + amplitude-follower algorithm as a simple Vamp plugin. + + - PercussionOnsetDetector estimates the locations of percussive + onsets using a simple method described in "Drum Source Separation + using Percussive Feature Detection and Spectral Modulation" by Dan + Barry, Derry Fitzgerald, Eugene Coyle and Bob Lawlor, ISSC 2005. + +\section hosts For Hosts + +Hosts will usually want to use a Vamp::PluginHostAdapter to convert +each plugin's exposed C API back into a useful Vamp::Plugin object. + +Hosts should link with -lvamp-hostsdk. + +The Vamp API does not officially specify how to load plugin libraries +or where to find them. However, the SDK does include a function +(Vamp::PluginHostAdapter::getPluginPath()) that returns a recommended +directory search path that hosts may use for plugin libraries. + +Our suggestion for a host is to search each directory in this path for +.DLL (on Windows), .so (on Linux, Solaris, BSD etc) or .dylib (on +OS/X) files, then to load each one and perform a dynamic name lookup +on the vampGetPluginDescriptor function to enumerate the plugins in +the library. The example host has some code that may help, but this +operation will necessarily be system-dependent. + +Vamp also has an informal convention for sorting plugins into +functional categories. In addition to the library file itself, a +plugin library may install a category file with the same name as the +library but .cat extension. The existence and format of this file are +not specified by the Vamp API, but by convention the file may contain +lines of the format + +\code +vamp:pluginlibrary:pluginname::General Category > Specific Category +\endcode + +which a host may read and use to assign plugins a location within a +category tree for display to the user. The expectation is that +advanced users may also choose to set up their own preferred category +trees, which is why this information is not queried as part of the +Vamp API itself. + +There is an example host in the "host" directory from +which code may be drawn. + +\section license License + +This plugin SDK is freely redistributable under a "new-style BSD" +licence. See the file COPYING for more details. In short, you may +modify and redistribute the SDK and example plugins within any +commercial or non-commercial, proprietary or open-source plugin or +application under almost any conditions, with no obligation to provide +source code, provided you retain the original copyright note. + + +*/ diff -r 74822738965b -r 933fee59d33a vamp/vamp.h --- a/vamp/vamp.h Wed Mar 21 14:15:25 2007 +0000 +++ b/vamp/vamp.h Fri Mar 30 17:14:16 2007 +0000 @@ -37,7 +37,22 @@ #ifndef VAMP_HEADER_INCLUDED #define VAMP_HEADER_INCLUDED -/* +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Plugin API version. This is incremented when a change is made that + * changes the binary layout of the descriptor records. When this + * happens, there should be a mechanism for retaining compatibility + * with older hosts and/or plugins. + * + * See also the vampApiVersion field in the plugin descriptor, and the + * hostApiVersion argument to the vampGetPluginDescriptor function. + */ +#define VAMP_API_VERSION 1 + +/** * C language API for Vamp plugins. * * This is the formal plugin API for Vamp. Plugin authors may prefer @@ -53,21 +68,6 @@ * plugin lifecycle documentation. */ -#ifdef __cplusplus -extern "C" { -#endif - -/** - * Plugin API version. This is incremented when a change is made that - * changes the binary layout of the descriptor records. When this - * happens, there should be a mechanism for retaining compatibility - * with older hosts and/or plugins. - * - * See also the vampApiVersion field in the plugin descriptor, and the - * hostApiVersion argument to the vampGetPluginDescriptor function. - */ -#define VAMP_API_VERSION 1 - typedef struct _VampParameterDescriptor { /** Computer-usable name of the parameter. Must not change. [a-zA-Z0-9_] */