v2/rtaudio.h

   1 /************************************************************************/
   2 /*! \class RtAudio
   3     \brief Realtime audio i/o C++ classes.
   4
   5     RtAudio provides a common API (Application Programming Interface)
   6     for realtime audio input/output across Linux (native ALSA, Jack,
   7     and OSS), SGI, Macintosh OS X (CoreAudio), and Windows
   8     (DirectSound and ASIO) operating systems.
   9
  10     RtAudio WWW site: http://music.mcgill.ca/~gary/rtaudio/
  11
  12     RtAudio: realtime audio i/o C++ classes
  13     Copyright (c) 2001-2005 Gary P. Scavone
  14
  15     Permission is hereby granted, free of charge, to any person
  16     obtaining a copy of this software and associated documentation files
  17     (the "Software"), to deal in the Software without restriction,
  18     including without limitation the rights to use, copy, modify, merge,
  19     publish, distribute, sublicense, and/or sell copies of the Software,
  20     and to permit persons to whom the Software is furnished to do so,
  21     subject to the following conditions:
  22
  23     The above copyright notice and this permission notice shall be
  24     included in all copies or substantial portions of the Software.
  25
  26     Any person wishing to distribute modifications to the Software is
  27     requested to send the modifications to the original developer so that
  28     they can be incorporated into the canonical version.
  29
  30     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  31     EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  32     MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  33     IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
  34     ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
  35     CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  36     WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  37 */
  38 /************************************************************************/
  39
  40 // RtAudio: Version 3.0.2 (14 October 2005)
  41
  42 #ifndef __RTAUDIO_H
  43 #define __RTAUDIO_H
  44
  45 #include "rterror.h"
  46 #include <string>
  47 #include <vector>
  48
  49 // Operating system dependent thread functionality.
  50 #if defined(__WINDOWS_DS__) || defined(__WINDOWS_ASIO__)
  51   #include <windows.h>
  52
  53   #if defined(__WINDOWS_PTHREAD__)
  54     #include <pthread.h>
  55     typedef pthread_t ThreadHandle;
  56     typedef pthread_mutex_t StreamMutex;
  57   #else
  58     #include <process.h>
  59     typedef unsigned long ThreadHandle;
  60     typedef CRITICAL_SECTION StreamMutex;
  61   #endif
  62
  63 #else // Various unix flavors with pthread support.
  64   #include <pthread.h>
  65
  66   typedef pthread_t ThreadHandle;
  67   typedef pthread_mutex_t StreamMutex;
  68
  69 #endif
  70
  71 // This global structure type is used to pass callback information
  72 // between the private RtAudio stream structure and global callback
  73 // handling functions.
  74 struct CallbackInfo {
  75   void *object;    // Used as a "this" pointer.
  76   ThreadHandle thread;
  77   bool usingCallback;
  78   void *callback;
  79   void *userData;
  80   void *apiInfo;   // void pointer for API specific callback information
  81
  82   // Default constructor.
  83   CallbackInfo()
  84     :object(0), usingCallback(false), callback(0),
  85      userData(0), apiInfo(0) {}
  86 };
  87
  88 // Support for signed integers and floats.  Audio data fed to/from
  89 // the tickStream() routine is assumed to ALWAYS be in host
  90 // byte order.  The internal routines will automatically take care of
  91 // any necessary byte-swapping between the host format and the
  92 // soundcard.  Thus, endian-ness is not a concern in the following
  93 // format definitions.
  94 typedef unsigned long RtAudioFormat;
  95 static const RtAudioFormat RTAUDIO_SINT8 = 0x1;    /*!< 8-bit signed integer. */
  96 static const RtAudioFormat RTAUDIO_SINT16 = 0x2;   /*!< 16-bit signed integer. */
  97 static const RtAudioFormat RTAUDIO_SINT24 = 0x4;   /*!< Upper 3 bytes of 32-bit signed integer. */
  98 static const RtAudioFormat RTAUDIO_SINT32 = 0x8;   /*!< 32-bit signed integer. */
  99 static const RtAudioFormat RTAUDIO_FLOAT32 = 0x10; /*!< Normalized between plus/minus 1.0. */
 100 static const RtAudioFormat RTAUDIO_FLOAT64 = 0x20; /*!< Normalized between plus/minus 1.0. */
 101
 102 typedef int (*RtAudioCallback)(char *buffer, int bufferSize, void *userData);
 103
 104 //! The public device information structure for returning queried values.
 105 struct RtAudioDeviceInfo {
 106   std::string name;      /*!< Character string device identifier. */
 107   bool probed;          /*!< true if the device capabilities were successfully probed. */
 108   int outputChannels;   /*!< Maximum output channels supported by device. */
 109   int inputChannels;    /*!< Maximum input channels supported by device. */
 110   int duplexChannels;   /*!< Maximum simultaneous input/output channels supported by device. */
 111   bool isDefault;       /*!< true if this is the default output or input device. */
 112   std::vector<int> sampleRates; /*!< Supported sample rates (queried from list of standard rates). */
 113   RtAudioFormat nativeFormats;  /*!< Bit mask of supported data formats. */
 114
 115   // Default constructor.
 116   RtAudioDeviceInfo()
 117     :probed(false), outputChannels(0), inputChannels(0),
 118        duplexChannels(0), isDefault(false), nativeFormats(0) {}
 119 };
 120
 121 // **************************************************************** //
 122 //
 123 // RtApi class declaration.
 124 //
 125 // Note that RtApi is an abstract base class and cannot be
 126 // explicitly instantiated.  The class RtAudio will create an
 127 // instance of an RtApi subclass (RtApiOss, RtApiAlsa,
 128 // RtApiJack, RtApiCore, RtApiAl, RtApiDs, or RtApiAsio).
 129 //
 130 // **************************************************************** //
 131
 132 class RtApi
 133 {
 134 public:
 135
 136   enum StreamState {
 137     STREAM_STOPPED,
 138     STREAM_RUNNING
 139   };
 140
 141   RtApi();
 142   virtual ~RtApi();
 143   void openStream( int outputDevice, int outputChannels,
 144                    int inputDevice, int inputChannels,
 145                    RtAudioFormat format, int sampleRate,
 146                    int *bufferSize, int numberOfBuffers );
 147   void openStream( int outputDevice, int outputChannels,
 148                    int inputDevice, int inputChannels,
 149                    RtAudioFormat format, int sampleRate,
 150                    int *bufferSize, int *numberOfBuffers );
 151   virtual void setStreamCallback( RtAudioCallback callback, void *userData ) = 0;
 152   virtual void cancelStreamCallback() = 0;
 153   int getDeviceCount(void);
 154   RtAudioDeviceInfo getDeviceInfo( int device );
 155   char * const getStreamBuffer();
 156   RtApi::StreamState getStreamState() const;
 157   virtual void tickStream() = 0;
 158   virtual void closeStream();
 159   virtual void startStream() = 0;
 160   virtual void stopStream() = 0;
 161   virtual void abortStream() = 0;
 162
 163 protected:
 164
 165   static const unsigned int MAX_SAMPLE_RATES;
 166   static const unsigned int SAMPLE_RATES[];
 167
 168   enum { FAILURE, SUCCESS };
 169
 170   enum StreamMode {
 171     OUTPUT,
 172     INPUT,
 173     DUPLEX,
 174     UNINITIALIZED = -75
 175   };
 176
 177   // A protected structure used for buffer conversion.
 178   struct ConvertInfo {
 179     int channels;
 180     int inJump, outJump;
 181     RtAudioFormat inFormat, outFormat;
 182     std::vector<int> inOffset;
 183     std::vector<int> outOffset;
 184   };
 185
 186   // A protected structure for audio streams.
 187   struct RtApiStream {
 188     int device[2];          // Playback and record, respectively.
 189     void *apiHandle;        // void pointer for API specific stream handle information
 190     StreamMode mode;         // OUTPUT, INPUT, or DUPLEX.
 191     StreamState state;       // STOPPED or RUNNING
 192     char *userBuffer;
 193     char *deviceBuffer;
 194     bool doConvertBuffer[2]; // Playback and record, respectively.
 195     bool deInterleave[2];    // Playback and record, respectively.
 196     bool doByteSwap[2];      // Playback and record, respectively.
 197     int sampleRate;
 198     int bufferSize;
 199     int nBuffers;
 200     int nUserChannels[2];    // Playback and record, respectively.
 201     int nDeviceChannels[2];  // Playback and record channels, respectively.
 202     RtAudioFormat userFormat;
 203     RtAudioFormat deviceFormat[2]; // Playback and record, respectively.
 204     StreamMutex mutex;
 205     CallbackInfo callbackInfo;
 206     ConvertInfo convertInfo[2];
 207
 208     RtApiStream()
 209       :apiHandle(0), mode((enum RtApi::StreamMode)-75), userBuffer(0), deviceBuffer(0) {}
 210   };
 211
 212   // A protected device structure for audio devices.
 213   struct RtApiDevice {
 214     std::string name;      /*!< Character string device identifier. */
 215     bool probed;           /*!< true if the device capabilities were successfully probed. */
 216     void *apiDeviceId;     // void pointer for API specific device information
 217     int maxOutputChannels; /*!< Maximum output channels supported by device. */
 218     int maxInputChannels;  /*!< Maximum input channels supported by device. */
 219     int maxDuplexChannels; /*!< Maximum simultaneous input/output channels supported by device. */
 220     int minOutputChannels; /*!< Minimum output channels supported by device. */
 221     int minInputChannels;  /*!< Minimum input channels supported by device. */
 222     int minDuplexChannels; /*!< Minimum simultaneous input/output channels supported by device. */
 223     bool hasDuplexSupport; /*!< true if device supports duplex mode. */
 224     bool isDefault;        /*!< true if this is the default output or input device. */
 225     std::vector<int> sampleRates; /*!< Supported sample rates. */
 226     RtAudioFormat nativeFormats;  /*!< Bit mask of supported data formats. */
 227
 228     // Default constructor.
 229     RtApiDevice()
 230       :probed(false), apiDeviceId(0), maxOutputChannels(0), maxInputChannels(0),
 231        maxDuplexChannels(0), minOutputChannels(0), minInputChannels(0),
 232        minDuplexChannels(0), isDefault(false), nativeFormats(0) {}
 233   };
 234
 235   typedef signed short Int16;
 236   typedef signed int Int32;
 237   typedef float Float32;
 238   typedef double Float64;
 239
 240   char message_[1024];
 241   int nDevices_;
 242   std::vector<RtApiDevice> devices_;
 243   RtApiStream stream_;
 244
 245   /*!
 246     Protected, api-specific method to count and identify the system
 247     audio devices.  This function MUST be implemented by all subclasses.
 248   */
 249   virtual void initialize(void) = 0;
 250
 251   /*!
 252     Protected, api-specific method which attempts to fill an
 253     RtAudioDevice structure for a given device.  This function MUST be
 254     implemented by all subclasses.  If an error is encountered during
 255     the probe, a "warning" message is reported and the value of
 256     "probed" remains false (no exception is thrown).  A successful
 257     probe is indicated by probed = true.
 258   */
 259   virtual void probeDeviceInfo( RtApiDevice *info );
 260
 261   /*!
 262     Protected, api-specific method which attempts to open a device
 263     with the given parameters.  This function MUST be implemented by
 264     all subclasses.  If an error is encountered during the probe, a
 265     "warning" message is reported and FAILURE is returned (no
 266     exception is thrown). A successful probe is indicated by a return
 267     value of SUCCESS.
 268   */
 269   virtual bool probeDeviceOpen( int device, StreamMode mode, int channels,
 270                                 int sampleRate, RtAudioFormat format,
 271                                 int *bufferSize, int numberOfBuffers );
 272
 273   /*!
 274     Protected method which returns the index in the devices array to
 275     the default input device.
 276   */
 277   virtual int getDefaultInputDevice(void);
 278
 279   /*!
 280     Protected method which returns the index in the devices array to
 281     the default output device.
 282   */
 283   virtual int getDefaultOutputDevice(void);
 284
 285   //! Protected common method to clear an RtApiDevice structure.
 286   void clearDeviceInfo( RtApiDevice *info );
 287
 288   //! Protected common method to clear an RtApiStream structure.
 289   void clearStreamInfo();
 290
 291   //! Protected common error method to allow global control over error handling.
 292   void error( RtError::Type type, long cont = 0 );
 293
 294   /*!
 295     Protected common method used to check whether a stream is open.
 296     If not, an "invalid identifier" exception is thrown.
 297   */
 298   void verifyStream();
 299
 300   /*!
 301     Protected method used to perform format, channel number, and/or interleaving
 302     conversions between the user and device buffers.
 303   */
 304   void convertBuffer( char *outBuffer, char *inBuffer, ConvertInfo &info );
 305
 306   //! Protected common method used to perform byte-swapping on buffers.
 307   void byteSwapBuffer( char *buffer, int samples, RtAudioFormat format );
 308
 309   //! Protected common method which returns the number of bytes for a given format.
 310   int formatBytes( RtAudioFormat format );
 311 };
 312
 313
 314 // **************************************************************** //
 315 //
 316 // RtAudio class declaration.
 317 //
 318 // RtAudio is a "controller" used to select an available audio i/o
 319 // interface.  It presents a common API for the user to call but all
 320 // functionality is implemented by the class RtAudioApi and its
 321 // subclasses.  RtAudio creates an instance of an RtAudioApi subclass
 322 // based on the user's API choice.  If no choice is made, RtAudio
 323 // attempts to make a "logical" API selection.
 324 //
 325 // **************************************************************** //
 326
 327 class RtAudio
 328 {
 329 public:
 330
 331   //! Audio API specifier arguments.
 332   enum RtAudioApi {
 333     UNSPECIFIED,    /*!< Search for a working compiled API. */
 334     LINUX_ALSA,     /*!< The Advanced Linux Sound Architecture API. */
 335     LINUX_OSS,      /*!< The Linux Open Sound System API. */
 336     LINUX_JACK,     /*!< The Linux Jack Low-Latency Audio Server API. */
 337     MACOSX_CORE,    /*!< Macintosh OS-X Core Audio API. */
 338     IRIX_AL,        /*!< The Irix Audio Library API. */
 339     WINDOWS_ASIO,   /*!< The Steinberg Audio Stream I/O API. */
 340     WINDOWS_DS      /*!< The Microsoft Direct Sound API. */
 341   };
 342
 343   //! The default class constructor.
 344   /*!
 345     Probes the system to make sure at least one audio input/output
 346     device is available and determines the api-specific identifier for
 347     each device found.  An RtError error can be thrown if no devices
 348     are found or if a memory allocation error occurs.
 349
 350     If no API argument is specified and multiple API support has been
 351     compiled, the default order of use is JACK, ALSA, OSS (Linux
 352     systems) and ASIO, DS (Windows systems).
 353   */
 354   RtAudio( RtAudioApi api=UNSPECIFIED );
 355
 356   //! A constructor which can be used to open a stream during instantiation.
 357   /*!
 358     The specified output and/or input device identifiers correspond
 359     to those enumerated via the getDeviceInfo() method.  If device =
 360     0, the default or first available devices meeting the given
 361     parameters is selected.  If an output or input channel value is
 362     zero, the corresponding device value is ignored.  When a stream is
 363     successfully opened, its identifier is returned via the "streamId"
 364     pointer.  An RtError can be thrown if no devices are found
 365     for the given parameters, if a memory allocation error occurs, or
 366     if a driver error occurs. \sa openStream()
 367   */
 368   RtAudio( int outputDevice, int outputChannels,
 369            int inputDevice, int inputChannels,
 370            RtAudioFormat format, int sampleRate,
 371            int *bufferSize, int numberOfBuffers, RtAudioApi api=UNSPECIFIED );
 372
 373   //! An overloaded constructor which opens a stream and also returns \c numberOfBuffers parameter via pointer argument.
 374   /*!
 375     See the previous constructor call for details.  This overloaded
 376     version differs only in that it takes a pointer argument for the
 377     \c numberOfBuffers parameter and returns the value used by the
 378     audio device (which may be different from that requested).  Note
 379     that the \c numberofBuffers parameter is not used with the Linux
 380     Jack, Macintosh CoreAudio, and Windows ASIO APIs.
 381   */
 382   RtAudio( int outputDevice, int outputChannels,
 383            int inputDevice, int inputChannels,
 384            RtAudioFormat format, int sampleRate,
 385            int *bufferSize, int *numberOfBuffers, RtAudioApi api=UNSPECIFIED );
 386
 387   //! The destructor.
 388   /*!
 389     Stops and closes an open stream and devices and deallocates
 390     buffer and structure memory.
 391   */
 392   ~RtAudio();
 393
 394   //! A public method for opening a stream with the specified parameters.
 395   /*!
 396     An RtError is thrown if a stream cannot be opened.
 397
 398     \param outputDevice: If equal to 0, the default or first device
 399            found meeting the given parameters is opened.  Otherwise, the
 400            device number should correspond to one of those enumerated via
 401            the getDeviceInfo() method.
 402     \param outputChannels: The desired number of output channels.  If
 403            equal to zero, the outputDevice identifier is ignored.
 404     \param inputDevice: If equal to 0, the default or first device
 405            found meeting the given parameters is opened.  Otherwise, the
 406            device number should correspond to one of those enumerated via
 407            the getDeviceInfo() method.
 408     \param inputChannels: The desired number of input channels.  If
 409            equal to zero, the inputDevice identifier is ignored.
 410     \param format: An RtAudioFormat specifying the desired sample data format.
 411     \param sampleRate: The desired sample rate (sample frames per second).
 412     \param *bufferSize: A pointer value indicating the desired internal buffer
 413            size in sample frames.  The actual value used by the device is
 414            returned via the same pointer.  A value of zero can be specified,
 415            in which case the lowest allowable value is determined.
 416     \param numberOfBuffers: A value which can be used to help control device
 417            latency.  More buffers typically result in more robust performance,
 418            though at a cost of greater latency.  A value of zero can be
 419            specified, in which case the lowest allowable value is used.
 420   */
 421   void openStream( int outputDevice, int outputChannels,
 422                    int inputDevice, int inputChannels,
 423                    RtAudioFormat format, int sampleRate,
 424                    int *bufferSize, int numberOfBuffers );
 425
 426   //! A public method for opening a stream and also returning \c numberOfBuffers parameter via pointer argument.
 427   /*!
 428     See the previous function call for details.  This overloaded
 429     version differs only in that it takes a pointer argument for the
 430     \c numberOfBuffers parameter and returns the value used by the
 431     audio device (which may be different from that requested).  Note
 432     that the \c numberofBuffers parameter is not used with the Linux
 433     Jack, Macintosh CoreAudio, and Windows ASIO APIs.
 434   */
 435   void openStream( int outputDevice, int outputChannels,
 436                    int inputDevice, int inputChannels,
 437                    RtAudioFormat format, int sampleRate,
 438                    int *bufferSize, int *numberOfBuffers );
 439
 440   //! A public method which sets a user-defined callback function for a given stream.
 441   /*!
 442     This method assigns a callback function to a previously opened
 443     stream for non-blocking stream functionality.  A separate process
 444     is initiated, though the user function is called only when the
 445     stream is "running" (between calls to the startStream() and
 446     stopStream() methods, respectively).  The callback process remains
 447     active for the duration of the stream and is automatically
 448     shutdown when the stream is closed (via the closeStream() method
 449     or by object destruction).  The callback process can also be
 450     shutdown and the user function de-referenced through an explicit
 451     call to the cancelStreamCallback() method.  Note that the stream
 452     can use only blocking or callback functionality at a particular
 453     time, though it is possible to alternate modes on the same stream
 454     through the use of the setStreamCallback() and
 455     cancelStreamCallback() methods (the blocking tickStream() method
 456     can be used before a callback is set and/or after a callback is
 457     cancelled).  An RtError will be thrown if called when no stream is
 458     open or a thread errors occurs.
 459   */
 460   void setStreamCallback(RtAudioCallback callback, void *userData) { rtapi_->setStreamCallback( callback, userData ); };
 461
 462   //! A public method which cancels a callback process and function for the stream.
 463   /*!
 464     This method shuts down a callback process and de-references the
 465     user function for the stream.  Callback functionality can
 466     subsequently be restarted on the stream via the
 467     setStreamCallback() method.  An RtError will be thrown if called
 468     when no stream is open.
 469    */
 470   void cancelStreamCallback() { rtapi_->cancelStreamCallback(); };
 471
 472   //! A public method which returns the number of audio devices found.
 473   int getDeviceCount(void) { return rtapi_->getDeviceCount(); };
 474
 475   //! Return an RtAudioDeviceInfo structure for a specified device number.
 476   /*!
 477     Any device integer between 1 and getDeviceCount() is valid.  If
 478     a device is busy or otherwise unavailable, the structure member
 479     "probed" will have a value of "false" and all other members are
 480     undefined.  If the specified device is the current default input
 481     or output device, the "isDefault" member will have a value of
 482     "true".  An RtError will be thrown for an invalid device argument.
 483   */
 484   RtAudioDeviceInfo getDeviceInfo(int device) { return rtapi_->getDeviceInfo( device ); };
 485
 486   //! A public method which returns a pointer to the buffer for an open stream.
 487   /*!
 488     The user should fill and/or read the buffer data in interleaved format
 489     and then call the tickStream() method.  An RtError will be
 490     thrown if called when no stream is open.
 491   */
 492   char * const getStreamBuffer() { return rtapi_->getStreamBuffer(); };
 493
 494   //! Public method used to trigger processing of input/output data for a stream.
 495   /*!
 496     This method blocks until all buffer data is read/written.  An
 497     RtError will be thrown if a driver error occurs or if called when
 498     no stream is open.
 499   */
 500   void tickStream() { rtapi_->tickStream(); };
 501
 502   //! Public method which closes a stream and frees any associated buffers.
 503   /*!
 504     If a stream is not open, this method issues a warning and
 505     returns (an RtError is not thrown).
 506   */
 507   void closeStream()  { rtapi_->closeStream(); };
 508
 509   //! Public method which starts a stream.
 510   /*!
 511     An RtError will be thrown if a driver error occurs or if called
 512     when no stream is open.
 513   */
 514   void startStream() { rtapi_->startStream(); };
 515
 516   //! Stop a stream, allowing any samples remaining in the queue to be played out and/or read in.
 517   /*!
 518     An RtError will be thrown if a driver error occurs or if called
 519     when no stream is open.
 520   */
 521   void stopStream() { rtapi_->stopStream(); };
 522
 523   //! Stop a stream, discarding any samples remaining in the input/output queue.
 524   /*!
 525     An RtError will be thrown if a driver error occurs or if called
 526     when no stream is open.
 527   */
 528   void abortStream() { rtapi_->abortStream(); };
 529
 530
 531  protected:
 532
 533   void initialize( RtAudioApi api );
 534
 535   RtApi *rtapi_;
 536 };
 537
 538
 539 // RtApi Subclass prototypes.
 540
 541 #if defined(__LINUX_ALSA__)
 542
 543 class RtApiAlsa: public RtApi
 544 {
 545 public:
 546
 547   RtApiAlsa();
 548   ~RtApiAlsa();
 549   void tickStream();
 550   void closeStream();
 551   void startStream();
 552   void stopStream();
 553   void abortStream();
 554   int streamWillBlock();
 555   void setStreamCallback( RtAudioCallback callback, void *userData );
 556   void cancelStreamCallback();
 557
 558   private:
 559
 560   void initialize(void);
 561   void probeDeviceInfo( RtApiDevice *info );
 562   bool probeDeviceOpen( int device, StreamMode mode, int channels,
 563                         int sampleRate, RtAudioFormat format,
 564                         int *bufferSize, int numberOfBuffers );
 565 };
 566
 567 #endif
 568
 569 #if defined(__LINUX_JACK__)
 570
 571 class RtApiJack: public RtApi
 572 {
 573 public:
 574
 575   RtApiJack();
 576   ~RtApiJack();
 577   void tickStream();
 578   void closeStream();
 579   void startStream();
 580   void stopStream();
 581   void abortStream();
 582   void setStreamCallback( RtAudioCallback callback, void *userData );
 583   void cancelStreamCallback();
 584   // This function is intended for internal use only.  It must be
 585   // public because it is called by the internal callback handler,
 586   // which is not a member of RtAudio.  External use of this function
 587   // will most likely produce highly undesireable results!
 588   void callbackEvent( unsigned long nframes );
 589
 590   private:
 591
 592   void initialize(void);
 593   void probeDeviceInfo( RtApiDevice *info );
 594   bool probeDeviceOpen( int device, StreamMode mode, int channels,
 595                         int sampleRate, RtAudioFormat format,
 596                         int *bufferSize, int numberOfBuffers );
 597 };
 598
 599 #endif
 600
 601 #if defined(__LINUX_OSS__)
 602
 603 class RtApiOss: public RtApi
 604 {
 605 public:
 606
 607   RtApiOss();
 608   ~RtApiOss();
 609   void tickStream();
 610   void closeStream();
 611   void startStream();
 612   void stopStream();
 613   void abortStream();
 614   int streamWillBlock();
 615   void setStreamCallback( RtAudioCallback callback, void *userData );
 616   void cancelStreamCallback();
 617
 618   private:
 619
 620   void initialize(void);
 621   void probeDeviceInfo( RtApiDevice *info );
 622   bool probeDeviceOpen( int device, StreamMode mode, int channels,
 623                         int sampleRate, RtAudioFormat format,
 624                         int *bufferSize, int numberOfBuffers );
 625 };
 626
 627 #endif
 628
 629 #if defined(__MACOSX_CORE__)
 630
 631 #include <CoreAudio/AudioHardware.h>
 632
 633 class RtApiCore: public RtApi
 634 {
 635 public:
 636
 637   RtApiCore();
 638   ~RtApiCore();
 639   int getDefaultOutputDevice(void);
 640   int getDefaultInputDevice(void);
 641   void tickStream();
 642   void closeStream();
 643   void startStream();
 644   void stopStream();
 645   void abortStream();
 646   void setStreamCallback( RtAudioCallback callback, void *userData );
 647   void cancelStreamCallback();
 648
 649   // This function is intended for internal use only.  It must be
 650   // public because it is called by the internal callback handler,
 651   // which is not a member of RtAudio.  External use of this function
 652   // will most likely produce highly undesireable results!
 653   void callbackEvent( AudioDeviceID deviceId, void *inData, void *outData );
 654
 655   private:
 656
 657   void initialize(void);
 658   void probeDeviceInfo( RtApiDevice *info );
 659   bool probeDeviceOpen( int device, StreamMode mode, int channels,
 660                         int sampleRate, RtAudioFormat format,
 661                         int *bufferSize, int numberOfBuffers );
 662 };
 663
 664 #endif
 665
 666 #if defined(__WINDOWS_DS__)
 667
 668 class RtApiDs: public RtApi
 669 {
 670 public:
 671
 672   RtApiDs();
 673   ~RtApiDs();
 674   int getDefaultOutputDevice(void);
 675   int getDefaultInputDevice(void);
 676   void tickStream();
 677   void closeStream();
 678   void startStream();
 679   void stopStream();
 680   void abortStream();
 681   int streamWillBlock();
 682   void setStreamCallback( RtAudioCallback callback, void *userData );
 683   void cancelStreamCallback();
 684
 685   public:
 686   // \brief Internal structure that provide debug information on the state of a running DSound device.
 687   struct RtDsStatistics {
 688     // \brief Sample Rate.
 689     long sampleRate;
 690     // \brief The size of one sample * number of channels on the input device.
 691     int inputFrameSize;
 692     // \brief The size of one sample * number of channels on the output device.
 693     int outputFrameSize;
 694     /* \brief The number of times the read pointer had to be adjusted to avoid reading from an unsafe buffer position.
 695      *
 696      * This field is only used when running in DUPLEX mode. INPUT mode devices just wait until the data is
 697      * available.
 698      */
 699     int numberOfReadOverruns;
 700     // \brief The number of times the write pointer had to be adjusted to avoid writing in an unsafe buffer position.
 701     int numberOfWriteUnderruns;
 702     // \brief Number of bytes by attribute to buffer configuration by which writing must lead the current write pointer.
 703     int writeDeviceBufferLeadBytes;
 704     // \brief Number of bytes by attributable to the device driver by which writing must lead the current write pointer on this output device.
 705     unsigned long writeDeviceSafeLeadBytes;
 706     // \brief Number of bytes by which reading must trail the current read pointer on this input device.
 707     unsigned long readDeviceSafeLeadBytes;
 708     /* \brief Estimated latency in seconds.
 709     *
 710     * For INPUT mode devices, based the latency of the device's safe read pointer, plus one buffer's
 711     * worth of additional latency.
 712     *
 713     * For OUTPUT mode devices, the latency of the device's safe write pointer, plus N buffers of
 714     * additional buffer latency.
 715     *
 716     * For DUPLEX devices, the sum of latencies for both input and output devices. DUPLEX devices
 717     * also back off the read pointers an additional amount in order to maintain synchronization
 718     * between out-of-phase read and write pointers. This time is also included.
 719     *
 720     * Note that most software packages report latency between the safe write pointer
 721     * and the software lead pointer, excluding the hardware device's safe write pointer
 722     * latency. Figures of 1 or 2ms of latency on Windows audio devices are invariably of this type.
 723     * The reality is that hardware devices often have latencies of 30ms or more (often much
 724     * higher for duplex operation).
 725     */
 726
 727     double latency;
 728   };
 729   // \brief Report on the current state of a running DSound device.
 730   static RtDsStatistics getDsStatistics();
 731
 732   private:
 733
 734   void initialize(void);
 735   void probeDeviceInfo( RtApiDevice *info );
 736   bool probeDeviceOpen( int device, StreamMode mode, int channels,
 737                         int sampleRate, RtAudioFormat format,
 738                         int *bufferSize, int numberOfBuffers );
 739
 740   bool coInitialized;
 741   bool buffersRolling;
 742   long duplexPrerollBytes;
 743   static RtDsStatistics statistics;
 744
 745 };
 746
 747 #endif
 748
 749 #if defined(__WINDOWS_ASIO__)
 750
 751 class RtApiAsio: public RtApi
 752 {
 753 public:
 754
 755   RtApiAsio();
 756   ~RtApiAsio();
 757   void tickStream();
 758   void closeStream();
 759   void startStream();
 760   void stopStream();
 761   void abortStream();
 762   void setStreamCallback( RtAudioCallback callback, void *userData );
 763   void cancelStreamCallback();
 764
 765   // This function is intended for internal use only.  It must be
 766   // public because it is called by the internal callback handler,
 767   // which is not a member of RtAudio.  External use of this function
 768   // will most likely produce highly undesireable results!
 769   void callbackEvent( long bufferIndex );
 770
 771   private:
 772
 773   void initialize(void);
 774   void probeDeviceInfo( RtApiDevice *info );
 775   bool probeDeviceOpen( int device, StreamMode mode, int channels,
 776                         int sampleRate, RtAudioFormat format,
 777                         int *bufferSize, int numberOfBuffers );
 778
 779   bool coInitialized;
 780
 781 };
 782
 783 #endif
 784
 785 #if defined(__IRIX_AL__)
 786
 787 class RtApiAl: public RtApi
 788 {
 789 public:
 790
 791   RtApiAl();
 792   ~RtApiAl();
 793   int getDefaultOutputDevice(void);
 794   int getDefaultInputDevice(void);
 795   void tickStream();
 796   void closeStream();
 797   void startStream();
 798   void stopStream();
 799   void abortStream();
 800   int streamWillBlock();
 801   void setStreamCallback( RtAudioCallback callback, void *userData );
 802   void cancelStreamCallback();
 803
 804   private:
 805
 806   void initialize(void);
 807   void probeDeviceInfo( RtApiDevice *info );
 808   bool probeDeviceOpen( int device, StreamMode mode, int channels,
 809                         int sampleRate, RtAudioFormat format,
 810                         int *bufferSize, int numberOfBuffers );
 811 };
 812
 813 #endif
 814
 815 // Define the following flag to have extra information spewed to stderr.
 816 //#define __RTAUDIO_DEBUG__
 817
 818 #endif