Various documentation updates in preparation for the 2.1.0 release.

Makefile.in

@@ -9,7 +9,7 @@ OBJECTS	= RtMidi.o
 LIBNAME = librtmidi
 STATIC = $(LIBNAME).a
 SHARED = @sharedlib@
-RELEASE = 2.0.1
+RELEASE = 2.1.0
 MAJOR = 2
 LIBRARIES = $(STATIC) $(SHARED)
 

RtMidi.h

@@ -154,9 +154,6 @@ class RtMidi
   //! Pure virtual closePort() function.
   virtual void closePort( void ) = 0;
 
-  //! A basic error reporting function for RtMidi classes.
-  //  static void error( RtMidiError::Type type, std::string &errorString );
-
   //! Returns true if a port is open and false if not.
   virtual bool isPortOpen( void ) const = 0;
 
@@ -185,9 +182,9 @@ class RtMidi
     retrieval using the getMessage() function or immediately passed to
     a user-specified callback function.  Create multiple instances of
     this class to connect to more than one MIDI device at the same
-    time.  With the OS-X and Linux ALSA MIDI APIs, it is also possible
-    to open a virtual input port to which other MIDI software clients
-    can connect.
+    time.  With the OS-X, Linux ALSA, and JACK MIDI APIs, it is also
+    possible to open a virtual input port to which other MIDI software
+    clients can connect.
 
     by Gary P. Scavone, 2003-2014.
 */
@@ -223,13 +220,13 @@ class RtMidiIn : public RtMidi
     incoming messages will be ignored.
 
     If no API argument is specified and multiple API support has been
-    compiled, the default order of use is JACK, ALSA (Linux) and CORE,
-    JACK (OS-X).
+    compiled, the default order of use is JACK, ALSA (Linux) and JACK,
+    CORE (OS-X).
 
     \param api        An optional API id can be specified.
-    \param clientName An optional Client name can be specified. This
+    \param clientName An optional client name can be specified. This
                       will be used to group the ports that are created
-		      by the application.
+                      by the application.
     \param queueSizeLimit An optional size of the MIDI input queue can be specified.
   */
   RtMidiIn( RtMidi::Api api=UNSPECIFIED,
@@ -245,8 +242,8 @@ class RtMidiIn : public RtMidi
   //! Open a MIDI input connection given by enumeration number.
   /*!
     \param portNumber An optional port number greater than 0 can be specified.
-    Otherwise, the default or first port found is opened.
-    \param portName An optional name for the applicaction port that is used to connect to portId can be specified.
+                      Otherwise, the default or first port found is opened.
+    \param portName An optional name for the application port that is used to connect to portId can be specified.
   */
   void openPort( unsigned int portNumber = 0, const std::string portName = std::string( "RtMidi Input" ) );
 
@@ -257,8 +254,8 @@ class RtMidiIn : public RtMidi
     is currently only supported by the Macintosh OS-X, any JACK,
     and Linux ALSA APIs (the function returns an error for the other APIs).
 
-    \param portName An optional name for the applicaction port that is
-           used to connect to portId can be specified.
+    \param portName An optional name for the application port that is
+                    used to connect to portId can be specified.
   */
   void openVirtualPort( const std::string portName = std::string( "RtMidi Input" ) );
 
@@ -270,8 +267,8 @@ class RtMidiIn : public RtMidi
     leaving some messages in the queue.
 
     \param callback A callback function must be given.
-    \param userData Opitionally, a pointer to additional data can be
-           passed to the callback function whenever it is called.
+    \param userData Optionally, a pointer to additional data can be
+                    passed to the callback function whenever it is called.
   */
   void setCallback( RtMidiCallback callback, void *userData = 0 );
 
@@ -290,7 +287,7 @@ class RtMidiIn : public RtMidi
 
   //! Return the number of available MIDI input ports.
   /*!
-    \return This function returns the number of midi ports of the selected API.
+    \return This function returns the number of MIDI ports of the selected API.
   */
   unsigned int getPortCount();
 
@@ -303,7 +300,7 @@ class RtMidiIn : public RtMidi
 
   //! Specify whether certain MIDI message types should be queued or ignored during input.
   /*!
-    o      By default, MIDI timing and active sensing messages are ignored
+    By default, MIDI timing and active sensing messages are ignored
     during message input because of their relative high data rates.
     MIDI sysex messages are ignored by default as well.  Variable
     values of "true" imply that the respective message type will be
@@ -342,7 +339,7 @@ class RtMidiIn : public RtMidi
     connect to one such port, and to send MIDI bytes immediately over
     the connection.  Create multiple instances of this class to
     connect to more than one MIDI device at the same time.  With the
-    OS-X and Linux ALSA MIDI APIs, it is also possible to open a
+    OS-X, Linux ALSA and JACK MIDI APIs, it is also possible to open a
     virtual port to which other MIDI software clients can connect.
 
     by Gary P. Scavone, 2003-2014.
@@ -358,8 +355,8 @@ class RtMidiOut : public RtMidi
     An exception will be thrown if a MIDI system initialization error occurs.
 
     If no API argument is specified and multiple API support has been
-    compiled, the default order of use is JACK, ALSA (Linux) and CORE,
-    JACK (OS-X).
+    compiled, the default order of use is JACK, ALSA (Linux) and JACK,
+    CORE (OS-X).
   */
   RtMidiOut( RtMidi::Api api=UNSPECIFIED,
              const std::string clientName = std::string( "RtMidi Output Client") );
@@ -385,14 +382,14 @@ class RtMidiOut : public RtMidi
   //! Returns true if a port is open and false if not.
   virtual bool isPortOpen() const;
 
-  //! Create a virtual output port, with optional name, to allow software connections (OS X and ALSA only).
+  //! Create a virtual output port, with optional name, to allow software connections (OS X, JACK and ALSA only).
   /*!
       This function creates a virtual MIDI output port to which other
       software applications can connect.  This type of functionality
-      is currently only supported by the Macintosh OS-X and Linux ALSA
-      APIs (the function does nothing with the other APIs).  An
-      exception is thrown if an error occurs while attempting to create
-      the virtual port.
+      is currently only supported by the Macintosh OS-X, Linux ALSA
+      and JACK APIs (the function does nothing with the other APIs).
+      An exception is thrown if an error occurs while attempting to
+      create the virtual port.
   */
   void openVirtualPort( const std::string portName = std::string( "RtMidi Output" ) );
 

configure.ac

@@ -1,5 +1,5 @@
 # Process this file with autoconf to produce a configure script.
-AC_INIT(RtMidi, 2.0.1, gary@music.mcgill.ca, rtmidi)
+AC_INIT(RtMidi, 2.1.0, gary@music.mcgill.ca, rtmidi)
 AC_CONFIG_AUX_DIR(config)
 AC_CONFIG_SRCDIR(RtMidi.cpp)
 AC_CONFIG_FILES([rtmidi-config librtmidi.pc Makefile tests/Makefile])

doc/doxygen/footer.html

@@ -1,7 +1,7 @@
 <HR>
 
 <table><tr><td><img src="../images/mcgill.gif" width=165></td>
-  <td>&copy;2003-2012 Gary P. Scavone, McGill University. All Rights Reserved.<br>
+  <td>&copy;2003-2014 Gary P. Scavone, McGill University. All Rights Reserved.<br>
   Maintained by Gary P. Scavone, gary at music.mcgill.ca</td></tr>
 </table>
 

doc/doxygen/tutorial.txt

@@ -4,12 +4,12 @@
 
 \section intro Introduction
 
-RtMidi is a set of C++ classes (RtMidiIn, RtMidiOut and API-specific classes) that provides a common API (Application Programming Interface) for realtime MIDI input/output across Linux (ALSA & Jack), Macintosh OS X (CoreMidi & Jack), and Windows (Multimedia Library & Kernel Streaming) operating systems.  RtMidi significantly simplifies the process of interacting with computer MIDI hardware and software.  It was designed with the following goals:
+RtMidi is a set of C++ classes (RtMidiIn, RtMidiOut and API-specific classes) that provides a common API (Application Programming Interface) for realtime MIDI input/output across Linux (ALSA & JACK), Macintosh OS X (CoreMIDI & JACK), and Windows (Multimedia Library & Kernel Streaming) operating systems.  RtMidi significantly simplifies the process of interacting with computer MIDI hardware and software.  It was designed with the following goals:
 
 <UL>
   <LI>object oriented C++ design</LI>
   <LI>simple, common API across all supported platforms</LI>
-  <LI>only two header files and one source file for easy inclusion in programming projects</LI>
+  <LI>only one header and one source file for easy inclusion in programming projects</LI>
   <LI>MIDI device enumeration</LI>
 </UL>
 
@@ -25,7 +25,7 @@ No incompatable API changes were made in version 2.0, however, support for multi
 
 \section download Download
 
-Latest Release (?? January 2014): <A href="http://www.music.mcgill.ca/~gary/rtmidi/release/rtmidi-2.1.0.tar.gz">Version 2.1.0</A>
+Latest Release (?? March 2014): <A href="http://www.music.mcgill.ca/~gary/rtmidi/release/rtmidi-2.1.0.tar.gz">Version 2.1.0</A>
 
 \section start Getting Started
 
@@ -58,24 +58,24 @@ Obviously, this example doesn't demonstrate any of the real functionality of RtM
 
 \section error Error Handling
 
-RtMidi uses a C++ exception handler called RtMidiError, which is declared
-and defined in RtMidi.h.  The RtMidiError class is quite simple but it
-does allow errors to be "caught" by RtMidiError::Type.  Many RtMidi
-methods can "throw" an RtMidiError, most typically if a driver error
-occurs or an invalid function argument is specified.  There are a
-number of cases within RtMidi where warning messages may be displayed
-but an exception is not thrown.  There is a protected RtMidi method,
-error(), that can be modified to globally control how these messages
-are handled and reported.  By default, error messages are not
-automatically displayed in RtMidi unless the preprocessor definition
-__RTMIDI_DEBUG__ is defined during compilation.  Messages associated
-with caught exceptions can be displayed with, for example, the
-RtMidiError::printMessage() function.
+RtMidi uses a C++ exception handler called RtMidiError, which is
+declared and defined in RtMidi.h.  The RtMidiError class is quite
+simple but it does allow errors to be "caught" by RtMidiError::Type.
+Many RtMidi methods can "throw" an RtMidiError, most typically if a
+driver error occurs or an invalid function argument is specified.
+There are a number of cases within RtMidi where warning messages may
+be displayed but an exception is not thrown.  A client error callback
+function can be specified (via the RtMidi::setErrorCallback function)
+that is invoked when an error occurs. By default, error messages are
+not automatically displayed in RtMidi unless the preprocessor
+definition __RTMIDI_DEBUG__ is defined during compilation.  Messages
+associated with caught exceptions can be displayed with, for example,
+the RtMidiError::printMessage() function.
 
 
 \section probing Probing Ports
 
-A programmer may wish to query the available MIDI ports before deciding which to use.  The following example outlines how this can be done.
+A client generally must query the available MIDI ports before deciding which to use.  The following example outlines how this can be done.
 
 \code
 // midiprobe.cpp
@@ -214,7 +214,7 @@ int main()
 
 The RtMidiIn class uses an internal callback function or thread to receive incoming MIDI messages from a port or device.  These messages are then either queued and read by the user via calls to the RtMidiIn::getMessage() function or immediately passed to a user-specified callback function (which must be "registered" using the RtMidiIn::setCallback() function).  We'll provide examples of both usages.
 
-The RtMidiIn class provides the RtMidiIn::ignoreTypes() function to specify that certain MIDI message types be ignored.  By default, sysem exclusive, timing, and active sensing messages are ignored.
+The RtMidiIn class provides the RtMidiIn::ignoreTypes() function to specify that certain MIDI message types be ignored.  By default, system exclusive, timing, and active sensing messages are ignored.
 
 \subsection qmidiin Queued MIDI Input
 
@@ -334,7 +334,7 @@ int main()
 
 \section virtual Virtual Ports
 
-The Linux ALSA and Macintosh CoreMIDI APIs allow for the establishment of virtual input and output MIDI ports to which other software clients can connect.  RtMidi incorporates this functionality with the RtMidiIn::openVirtualPort() and RtMidiOut::openVirtualPort() functions.  Any messages sent with the RtMidiOut::sendMessage() function will also be transmitted through an open virtual output port.  If a virtual input port is open and a user callback function is set, the callback function will be invoked when messages arrive via that port.  If a callback function is not set, the user must poll the input queue to check whether messages have arrived.  No notification is provided for the establishment of a client connection via a virtual port.
+The Linux ALSA, Macintosh CoreMIDI and JACK APIs allow for the establishment of virtual input and output MIDI ports to which other software clients can connect.  RtMidi incorporates this functionality with the RtMidiIn::openVirtualPort() and RtMidiOut::openVirtualPort() functions.  Any messages sent with the RtMidiOut::sendMessage() function will also be transmitted through an open virtual output port.  If a virtual input port is open and a user callback function is set, the callback function will be invoked when messages arrive via that port.  If a callback function is not set, the user must poll the input queue to check whether messages have arrived.  No notification is provided for the establishment of a client connection via a virtual port.
 
 \section compiling Compiling
 
@@ -358,16 +358,16 @@ In order to compile RtMidi for a specific OS and API, it is necessary to supply
 </TR>
 <TR>
   <TD>Linux or Mac</TD>
-  <TD>Jack MIDI</TD>
+  <TD>JACK MIDI</TD>
   <TD>__UNIX_JACK__</TD>
   <TD><TT>jack</TT></TD>
   <TD><TT>g++ -Wall -D__UNIX_JACK__ -o midiprobe midiprobe.cpp RtMidi.cpp -ljack</TT></TD>
 </TR>
 <TR>
   <TD>Macintosh OS X</TD>
-  <TD>CoreMidi</TD>
+  <TD>CoreMIDI</TD>
   <TD>__MACOSX_CORE__</TD>
-  <TD><TT>CoreMidi, CoreAudio, CoreFoundation</TT></TD>
+  <TD><TT>CoreMIDI, CoreAudio, CoreFoundation</TT></TD>
   <TD><TT>g++ -Wall -D__MACOSX_CORE__ -o midiprobe midiprobe.cpp RtMidi.cpp -framework CoreMIDI -framework CoreAudio -framework CoreFoundation</TT></TD>
 </TR>
 <TR>
@@ -391,11 +391,11 @@ The example compiler statements above could be used to compile the <TT>midiprobe
 
 \section debug Debugging
 
-If you are having problems getting RtMidi to run on your system, try passing the preprocessor definition <TT>__RTMIDI_DEBUG__</TT> to the compiler (or define it in RtMidi.h).  A variety of warning messages will be displayed that may help in determining the problem.  Also try using the programs included in the <tt>test</tt> directory.  The program <tt>midiprobe</tt> displays the queried capabilities of all MIDI ports found.
+If you are having problems getting RtMidi to run on your system, try passing the preprocessor definition <TT>__RTMIDI_DEBUG__</TT> to the compiler (or define it in RtMidi.h).  A variety of warning messages will be displayed that may help in determining the problem.  Also try using the programs included in the <tt>tests</tt> directory.  The program <tt>midiprobe</tt> displays the queried capabilities of all MIDI ports found.
 
 \section multi Using Simultaneous Multiple APIs
 
-Support for each MIDI API is encapsulated in specific MidiInApi or MidiOutApi subclasses, making it possible to compile and instantiate multiple API-specific subclasses on a given operating system.  For example, one can compile both the CoreMIDI and Jack support on the OS-X operating system by providing the appropriate preprocessor definitions for each.  In a run-time situation, one might first attempt to determine whether any Jack ports are available.  This can be done by specifying the api argument RtMidi::UNIX_JACK when attempting to create an instance of RtMidiIn or RtMidiOut.  If no available ports are found, then an instance of RtMidi with the api argument RtMidi::MACOSX_CORE can be created.  Alternately, if no api argument is specified, RtMidi will first look for CoreMIDI ports and if none are found, then Jack ports (in linux, the search order is ALSA and then Jack; in windows, the search order is WinMM and then WinKS).  In theory, it should also be possible to have separate instances of RtMidi open at the same time with different underlying API support, though this has not been tested.
+Support for each MIDI API is encapsulated in specific MidiInApi or MidiOutApi subclasses, making it possible to compile and instantiate multiple API-specific subclasses on a given operating system.  For example, one can compile both CoreMIDI and JACK support on the OS-X operating system by providing the appropriate preprocessor definitions for each.  In a run-time situation, one might first attempt to determine whether any JACK ports are available.  This can be done by specifying the api argument RtMidi::UNIX_JACK when attempting to create an instance of RtMidiIn or RtMidiOut.  If no available ports are found, then an instance of RtMidi with the api argument RtMidi::MACOSX_CORE can be created.  Alternately, if no api argument is specified, RtMidi will first look for JACK ports and if none are found, then CoreMIDI ports (in linux, the search order is JACK and then ALSA; in Windows, the search order is WinMM and then WinKS).  In theory, it should also be possible to have separate instances of RtMidi open at the same time with different underlying API support, though this has not been tested.
 
 The static function RtMidi::getCompiledApi() is provided to determine the available compiled API support.  The function RtMidi::getCurrentApi() indicates the API selected for a given RtMidi instance.
 
@@ -405,13 +405,13 @@ RtMidi is designed to provide a common API across the various supported operatin
 
 \subsection linux Linux:
 
-RtMidi for Linux was developed using the Fedora distribution.  Two different MIDI APIs are supported on Linux platforms: <A href="http://www.alsa-project.org/">ALSA</A> and <A href="http://jackit.sourceforge.net/">Jack</A>. A decision was made to not include support for the OSS API because the OSS API provides such limited functionality and because <A href="http://www.alsa-project.org/">ALSA</A> support is now incorporated in the Linux kernel.  The ALSA sequencer and Jack APIs allows for virtual software input and output ports. 
+RtMidi for Linux was developed using the Fedora distribution.  Two different MIDI APIs are supported on Linux platforms: <A href="http://www.alsa-project.org/">ALSA</A> and <A href="http://jackit.sourceforge.net/">JACK</A>. A decision was made to not include support for the OSS API because the OSS API provides very limited functionality and because <A href="http://www.alsa-project.org/">ALSA</A> support is now incorporated in the Linux kernel.  The ALSA sequencer and JACK APIs allows for virtual software input and output ports. 
 
 \subsection macosx Macintosh OS X (CoreAudio):
 
-The Apple CoreMidi API allows for the establishment of virtual input and output ports to which other software applications can connect.
+The Apple CoreMIDI API allows for the establishment of virtual input and output ports to which other software applications can connect.
 
-The RtMidi Jack support can be compiled on Macintosh OS-X systems, as well as in Linux.
+The RtMidi JACK support can be compiled on Macintosh OS-X systems, as well as in Linux.
 
 \subsection windowsds Windows (Multimedia Library):
 
@@ -419,15 +419,17 @@ The \c configure script provides support for the MinGW compiler.
 
 The Windows Multimedia library MIDI calls used in RtMidi do not make use of streaming functionality.   Incoming system exclusive messages read by RtMidiIn are limited to a length as defined by the preprocessor definition RT_SYSEX_BUFFER_SIZE (set in RtMidi.cpp).  The default value is 1024.  There is no such limit for outgoing sysex messages via RtMidiOut.
 
-RtMidi was originally developed with Visual C++ version 6.0.
+RtMidi was originally developed with Visual C++ version 6.0 but has been tested with Virtual Studio 2010.
 
 The \c configure script provides support for the MinGW compiler.
 
-\section acknowledge Acknowledgements
+\section acknowledge Development & Acknowledgements
 
-Many thanks to the following people for providing bug fixes and improvements:
+RtMidi is on github (https://github.com/thestk/rtmidi).  Many thanks to the developers that are helping to maintain and improve RtMidi.
+
+In years past, the following people provided bug fixes and improvements:
 <UL>
-<LI>Sebastien Alaiwan (Jack memory leaks, Windows kernel streaming)</LI>
+<LI>Sebastien Alaiwan (JACK memory leaks, Windows kernel streaming)</LI>
 <LI>Jean-Baptiste Berruchon (Windows sysex code)</LI>
 <LI>Pedro Lopez-Cabanillas (ALSA sequencer API, client naming)</LI>
 <LI>Jason Champion (MSW project file for library build)</LI>
@@ -440,7 +442,7 @@ Many thanks to the following people for providing bug fixes and improvements:
 <LI>Immanuel Litzroth (OS-X sysex fix)</LI>
 <LI>Jon McCormack (Snow Leopard updates)</LI>
 <LI>Axel Schmidt (client naming)</LI>
-<LI>Alexander Svetalkin (Jack MIDI)</LI>
+<LI>Alexander Svetalkin (JACK MIDI)</LI>
 <LI>Casey Tucker (OS-X driver information, sysex sending)</LI>
 <LI>Bastiaan Verreijt (Windows sysex multi-buffer code)</LI>
 <LI>Dan Wilcox</LI>
@@ -449,7 +451,7 @@ Many thanks to the following people for providing bug fixes and improvements:
 \section license License
 
     RtMidi: realtime MIDI i/o C++ classes<BR>
-    Copyright (c) 2003-2012 Gary P. Scavone
+    Copyright (c) 2003-2014 Gary P. Scavone
 
     Permission is hereby granted, free of charge, to any person
     obtaining a copy of this software and associated documentation files

doc/release.txt

@@ -1,4 +1,4 @@
-RtMidi - a set of C++ classes that provides a common API for realtime MIDI input/output across Linux (ALSA & Jack), Macintosh OS X (CoreMidi & Jack), and Windows (Multimedia, Kernel Streaming).
+RtMidi - a set of C++ classes that provides a common API for realtime MIDI input/output across Linux (ALSA & JACK), Macintosh OS X (CoreMidi & JACK), and Windows (Multimedia, Kernel Streaming).
 
 By Gary P. Scavone, 2003-2014
 

librtmidi.pc.in

@@ -5,7 +5,7 @@ includedir=${prefix}/include
 
 Name: librtmidi
 Description: RtMidi - a set of C++ classes that provide a common API for realtime MIDI input/output
-Version: 2.0.1
+Version: 2.1.0
 Requires: @req@ 
 Libs: -L${libdir} -lrtmidi
 Libs.private: -lpthread

readme

@@ -1,4 +1,4 @@
-RtMidi - a set of C++ classes that provide a common API for realtime MIDI input/output across Linux (ALSA & Jack), Macintosh OS X (CoreMidi) and Windows (Multimedia & Kernel Streaming).
+RtMidi - a set of C++ classes that provide a common API for realtime MIDI input/output across Linux (ALSA & JACK), Macintosh OS X (CoreMidi & JACK) and Windows (Multimedia & Kernel Streaming).
 
 By Gary P. Scavone, 2003-2014.
 
@@ -13,11 +13,11 @@ If you checked out the code from git, please run "autoconf" before "./configure"
 
 OVERVIEW:
 
-RtMidi is a set of C++ classes (RtMidiIn, RtMidiOut, and API specific classes) that provide a common API (Application Programming Interface) for realtime MIDI input/output across Linux (ALSA, Jack), Macintosh OS X (CoreMidi, Jack), SGI, and Windows (Multimedia Library, Kernel Streming) operating systems.  RtMidi significantly simplifies the process of interacting with computer MIDI hardware and software.  It was designed with the following goals:
+RtMidi is a set of C++ classes (RtMidiIn, RtMidiOut, and API specific classes) that provide a common API (Application Programming Interface) for realtime MIDI input/output across Linux (ALSA, JACK), Macintosh OS X (CoreMidi, JACK), and Windows (Multimedia Library, Kernel Streming) operating systems.  RtMidi significantly simplifies the process of interacting with computer MIDI hardware and software.  It was designed with the following goals:
 
   - object oriented C++ design
   - simple, common API across all supported platforms
-  - only two header files and one source file for easy inclusion in programming projects
+  - only one header and one source file for easy inclusion in programming projects
   - MIDI device enumeration
 
 MIDI input and output functionality are separated into two classes, RtMidiIn and RtMidiOut.  Each class instance supports only a single MIDI connection.  RtMidi does not provide timing functionality (i.e., output messages are sent immediately).  Input messages are timestamped with delta times in seconds (via a double floating point type).  MIDI data is passed to the user as raw bytes using an std::vector<unsigned char>.