Mercurial > hg > vamp-plugin-sdk

changeset 54:933fee59d33a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* doc updates
author cannam
date Fri, 30 Mar 2007 17:14:16 +0000
parents 74822738965b
children 0dad357a3406 9d3272c7db60
files Doxyfile examples/AmplitudeFollower.cpp examples/AmplitudeFollower.h examples/PercussionOnsetDetector.h examples/SpectralCentroid.h examples/ZeroCrossing.h vamp-sdk/doc-overview vamp/vamp.h
diffstat 8 files changed, 150 insertions(+), 34 deletions(-) [+]
line wrap: on
line diff
--- 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
--- 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.
  */
--- 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:
--- 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:
--- 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:
--- 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:
--- /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.
+
+
+*/
--- 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_] */