WDL/rtaudiomidi/RtMidi.h

   1 /**********************************************************************/
   2 /*! \class RtMidi
   3     \brief An abstract base class for realtime MIDI input/output.
   4
   5     This class implements some common functionality for the realtime
   6     MIDI input/output subclasses RtMidiIn and RtMidiOut.
   7
   8     RtMidi WWW site: http://music.mcgill.ca/~gary/rtmidi/
   9
  10     RtMidi: realtime MIDI i/o C++ classes
  11     Copyright (c) 2003-2011 Gary P. Scavone
  12
  13     Permission is hereby granted, free of charge, to any person
  14     obtaining a copy of this software and associated documentation files
  15     (the "Software"), to deal in the Software without restriction,
  16     including without limitation the rights to use, copy, modify, merge,
  17     publish, distribute, sublicense, and/or sell copies of the Software,
  18     and to permit persons to whom the Software is furnished to do so,
  19     subject to the following conditions:
  20
  21     The above copyright notice and this permission notice shall be
  22     included in all copies or substantial portions of the Software.
  23
  24     Any person wishing to distribute modifications to the Software is
  25     requested to send the modifications to the original developer so that
  26     they can be incorporated into the canonical version.
  27
  28     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  29     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  30     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  31     IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
  32     ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
  33     CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  34     WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  35 */
  36 /**********************************************************************/
  37
  38 // RtMidi: Version 1.0.14
  39
  40 #ifndef RTMIDI_H
  41 #define RTMIDI_H
  42
  43 #include "RtError.h"
  44 #include <string>
  45
  46 class RtMidi
  47 {
  48  public:
  49
  50   //! Pure virtual openPort() function.
  51   virtual void openPort( unsigned int portNumber = 0, const std::string portName = std::string( "RtMidi" ) ) = 0;
  52
  53   //! Pure virtual openVirtualPort() function.
  54   virtual void openVirtualPort( const std::string portName = std::string( "RtMidi" ) ) = 0;
  55
  56   //! Pure virtual getPortCount() function.
  57   virtual unsigned int getPortCount() = 0;
  58
  59   //! Pure virtual getPortName() function.
  60   virtual std::string getPortName( unsigned int portNumber = 0 ) = 0;
  61
  62   //! Pure virtual closePort() function.
  63   virtual void closePort( void ) = 0;
  64
  65  protected:
  66
  67   RtMidi();
  68   virtual ~RtMidi() {};
  69
  70   // A basic error reporting function for internal use in the RtMidi
  71   // subclasses.  The behavior of this function can be modified to
  72   // suit specific needs.
  73   void error( RtError::Type type );
  74
  75   void *apiData_;
  76   bool connected_;
  77   std::string errorString_;
  78 };
  79
  80 /**********************************************************************/
  81 /*! \class RtMidiIn
  82     \brief A realtime MIDI input class.
  83
  84     This class provides a common, platform-independent API for
  85     realtime MIDI input.  It allows access to a single MIDI input
  86     port.  Incoming MIDI messages are either saved to a queue for
  87     retrieval using the getMessage() function or immediately passed to
  88     a user-specified callback function.  Create multiple instances of
  89     this class to connect to more than one MIDI device at the same
  90     time.  With the OS-X and Linux ALSA MIDI APIs, it is also possible
  91     to open a virtual input port to which other MIDI software clients
  92     can connect.
  93
  94     by Gary P. Scavone, 2003-2008.
  95 */
  96 /**********************************************************************/
  97
  98 #include <vector>
  99 #include <queue>
 100
 101 class RtMidiIn : public RtMidi
 102 {
 103  public:
 104
 105   //! User callback function type definition.
 106   typedef void (*RtMidiCallback)( double timeStamp, std::vector<unsigned char> *message, void *userData);
 107
 108   //! Default constructor that allows an optional client name.
 109   /*!
 110       An exception will be thrown if a MIDI system initialization error occurs.
 111   */
 112   RtMidiIn( const std::string clientName = std::string( "RtMidi Input Client") );
 113
 114   //! If a MIDI connection is still open, it will be closed by the destructor.
 115   ~RtMidiIn();
 116
 117   //! Open a MIDI input connection.
 118   /*!
 119       An optional port number greater than 0 can be specified.
 120       Otherwise, the default or first port found is opened.
 121   */
 122   void openPort( unsigned int portNumber = 0, const std::string Portname = std::string( "RtMidi Input" ) );
 123
 124   //! Create a virtual input port, with optional name, to allow software connections (OS X and ALSA only).
 125   /*!
 126       This function creates a virtual MIDI input port to which other
 127       software applications can connect.  This type of functionality
 128       is currently only supported by the Macintosh OS-X and Linux ALSA
 129       APIs (the function does nothing for the other APIs).
 130   */
 131   void openVirtualPort( const std::string portName = std::string( "RtMidi Input" ) );
 132
 133   //! Set a callback function to be invoked for incoming MIDI messages.
 134   /*!
 135       The callback function will be called whenever an incoming MIDI
 136       message is received.  While not absolutely necessary, it is best
 137       to set the callback function before opening a MIDI port to avoid
 138       leaving some messages in the queue.
 139   */
 140   void setCallback( RtMidiCallback callback, void *userData = 0 );
 141
 142   //! Cancel use of the current callback function (if one exists).
 143   /*!
 144       Subsequent incoming MIDI messages will be written to the queue
 145       and can be retrieved with the \e getMessage function.
 146   */
 147   void cancelCallback();
 148
 149   //! Close an open MIDI connection (if one exists).
 150   void closePort( void );
 151
 152   //! Return the number of available MIDI input ports.
 153   unsigned int getPortCount();
 154
 155   //! Return a string identifier for the specified MIDI input port number.
 156   /*!
 157       An empty string is returned if an invalid port specifier is provided.
 158   */
 159   std::string getPortName( unsigned int portNumber = 0 );
 160
 161   //! Set the maximum number of MIDI messages to be saved in the queue.
 162   /*!
 163       If the queue size limit is reached, incoming messages will be
 164       ignored.  The default limit is 1024.
 165   */
 166   void setQueueSizeLimit( unsigned int queueSize );
 167
 168   //! Specify whether certain MIDI message types should be queued or ignored during input.
 169   /*!
 170       By default, MIDI timing and active sensing messages are ignored
 171       during message input because of their relative high data rates.
 172       MIDI sysex messages are ignored by default as well.  Variable
 173       values of "true" imply that the respective message type will be
 174       ignored.
 175   */
 176   void ignoreTypes( bool midiSysex = true, bool midiTime = true, bool midiSense = true );
 177
 178   //! Fill the user-provided vector with the data bytes for the next available MIDI message in the input queue and return the event delta-time in seconds.
 179   /*!
 180       This function returns immediately whether a new message is
 181       available or not.  A valid message is indicated by a non-zero
 182       vector size.  An exception is thrown if an error occurs during
 183       message retrieval or an input connection was not previously
 184       established.
 185   */
 186   double getMessage( std::vector<unsigned char> *message );
 187
 188   // A MIDI structure used internally by the class to store incoming
 189   // messages.  Each message represents one and only one MIDI message.
 190   struct MidiMessage {
 191     std::vector<unsigned char> bytes;
 192     double timeStamp;
 193
 194     // Default constructor.
 195     MidiMessage()
 196       :bytes(3), timeStamp(0.0) {}
 197   };
 198
 199   // The RtMidiInData structure is used to pass private class data to
 200   // the MIDI input handling function or thread.
 201   struct RtMidiInData {
 202     std::queue<MidiMessage> queue;
 203     MidiMessage message;
 204     unsigned int queueLimit;
 205     unsigned char ignoreFlags;
 206     bool doInput;
 207     bool firstMessage;
 208     void *apiData;
 209     bool usingCallback;
 210     void *userCallback;
 211     void *userData;
 212     bool continueSysex;
 213
 214     // Default constructor.
 215     RtMidiInData()
 216       : queueLimit(1024), ignoreFlags(7), doInput(false), firstMessage(true),
 217         apiData(0), usingCallback(false), userCallback(0), userData(0),
 218         continueSysex(false) {}
 219   };
 220
 221  private:
 222
 223   void initialize( const std::string& clientName );
 224   RtMidiInData inputData_;
 225
 226 };
 227
 228 /**********************************************************************/
 229 /*! \class RtMidiOut
 230     \brief A realtime MIDI output class.
 231
 232     This class provides a common, platform-independent API for MIDI
 233     output.  It allows one to probe available MIDI output ports, to
 234     connect to one such port, and to send MIDI bytes immediately over
 235     the connection.  Create multiple instances of this class to
 236     connect to more than one MIDI device at the same time.
 237
 238     by Gary P. Scavone, 2003-2008.
 239 */
 240 /**********************************************************************/
 241
 242 class RtMidiOut : public RtMidi
 243 {
 244  public:
 245
 246   //! Default constructor that allows an optional client name.
 247   /*!
 248       An exception will be thrown if a MIDI system initialization error occurs.
 249   */
 250   RtMidiOut( const std::string clientName = std::string( "RtMidi Output Client" ) );
 251
 252   //! The destructor closes any open MIDI connections.
 253   ~RtMidiOut();
 254
 255   //! Open a MIDI output connection.
 256   /*!
 257       An optional port number greater than 0 can be specified.
 258       Otherwise, the default or first port found is opened.  An
 259       exception is thrown if an error occurs while attempting to make
 260       the port connection.
 261   */
 262   void openPort( unsigned int portNumber = 0, const std::string portName = std::string( "RtMidi Output" ) );
 263
 264   //! Close an open MIDI connection (if one exists).
 265   void closePort();
 266
 267   //! Create a virtual output port, with optional name, to allow software connections (OS X and ALSA only).
 268   /*!
 269       This function creates a virtual MIDI output port to which other
 270       software applications can connect.  This type of functionality
 271       is currently only supported by the Macintosh OS-X and Linux ALSA
 272       APIs (the function does nothing with the other APIs).  An
 273       exception is thrown if an error occurs while attempting to create
 274       the virtual port.
 275   */
 276   void openVirtualPort( const std::string portName = std::string( "RtMidi Output" ) );
 277
 278   //! Return the number of available MIDI output ports.
 279   unsigned int getPortCount();
 280
 281   //! Return a string identifier for the specified MIDI port type and number.
 282   /*!
 283       An empty string is returned if an invalid port specifier is provided.
 284   */
 285   std::string getPortName( unsigned int portNumber = 0 );
 286
 287   //! Immediately send a single message out an open MIDI output port.
 288   /*!
 289       An exception is thrown if an error occurs during output or an
 290       output connection was not previously established.
 291   */
 292   void sendMessage( std::vector<unsigned char> *message );
 293
 294  private:
 295
 296   void initialize( const std::string& clientName );
 297 };
 298
 299 #endif