---

RtAudio.h

/************************************************************************/
/************************************************************************/

// RtAudio: Version 3.0.3 (18 November 2005)

#ifndef __RTAUDIO_H
#define __RTAUDIO_H

#include "RtError.h"
#include <string>
#include <vector>

// Operating system dependent thread functionality.
#if defined(__WINDOWS_DS__) || defined(__WINDOWS_ASIO__)
  #include <windows.h>
  #include <process.h>

  typedef unsigned long ThreadHandle;
  typedef CRITICAL_SECTION StreamMutex;

#else // Various unix flavors with pthread support.
  #include <pthread.h>

  typedef pthread_t ThreadHandle;
  typedef pthread_mutex_t StreamMutex;

#endif

// This global structure type is used to pass callback information
// between the private RtAudio stream structure and global callback
// handling functions.
struct CallbackInfo {
  void *object;    // Used as a "this" pointer.
  ThreadHandle thread;
  bool usingCallback;
  void *callback;
  void *userData;
  void *apiInfo;   // void pointer for API specific callback information

  // Default constructor.
  CallbackInfo()
    :object(0), usingCallback(false), callback(0),
     userData(0), apiInfo(0) {}
};

// Support for signed integers and floats.  Audio data fed to/from
// the tickStream() routine is assumed to ALWAYS be in host
// byte order.  The internal routines will automatically take care of
// any necessary byte-swapping between the host format and the
// soundcard.  Thus, endian-ness is not a concern in the following
// format definitions.
typedef unsigned long RtAudioFormat;
static const RtAudioFormat RTAUDIO_SINT8 = 0x1;    
static const RtAudioFormat RTAUDIO_SINT16 = 0x2;   
static const RtAudioFormat RTAUDIO_SINT24 = 0x4;   
static const RtAudioFormat RTAUDIO_SINT32 = 0x8;   
static const RtAudioFormat RTAUDIO_FLOAT32 = 0x10; 
static const RtAudioFormat RTAUDIO_FLOAT64 = 0x20; 
typedef int (*RtAudioCallback)(char *buffer, int bufferSize, void *userData);

struct RtAudioDeviceInfo {
  std::string name;      
  bool probed;          
  int outputChannels;   
  int inputChannels;    
  int duplexChannels;   
  bool isDefault;       
  std::vector<int> sampleRates; 
  RtAudioFormat nativeFormats;  
  // Default constructor.
  RtAudioDeviceInfo()
    :probed(false), outputChannels(0), inputChannels(0),
       duplexChannels(0), isDefault(false), nativeFormats(0) {}
};

// **************************************************************** //
//
// RtApi class declaration.
//
// Note that RtApi is an abstract base class and cannot be
// explicitly instantiated.  The class RtAudio will create an
// instance of an RtApi subclass (RtApiOss, RtApiAlsa,
// RtApiJack, RtApiCore, RtApiAl, RtApiDs, or RtApiAsio).
//
// **************************************************************** //

class RtApi
{
public:

  enum StreamState {
    STREAM_STOPPED,
    STREAM_RUNNING
  };

  RtApi();
  virtual ~RtApi();
  void openStream( int outputDevice, int outputChannels,
                   int inputDevice, int inputChannels,
                   RtAudioFormat format, int sampleRate,
                   int *bufferSize, int numberOfBuffers );
  void openStream( int outputDevice, int outputChannels,
                   int inputDevice, int inputChannels,
                   RtAudioFormat format, int sampleRate,
                   int *bufferSize, int *numberOfBuffers );
  virtual void setStreamCallback( RtAudioCallback callback, void *userData ) = 0;
  virtual void cancelStreamCallback() = 0;
  int getDeviceCount(void);
  RtAudioDeviceInfo getDeviceInfo( int device );
  char * const getStreamBuffer();
  RtApi::StreamState getStreamState() const;
  virtual void tickStream() = 0;
  virtual void closeStream();
  virtual void startStream() = 0;
  virtual void stopStream() = 0;
  virtual void abortStream() = 0;

protected:

  static const unsigned int MAX_SAMPLE_RATES;
  static const unsigned int SAMPLE_RATES[];

  enum { FAILURE, SUCCESS };

  enum StreamMode {
    OUTPUT,
    INPUT,
    DUPLEX,
    UNINITIALIZED = -75
  };

  // A protected structure used for buffer conversion.
  struct ConvertInfo {
    int channels;
    int inJump, outJump;
    RtAudioFormat inFormat, outFormat;
    std::vector<int> inOffset;
    std::vector<int> outOffset;
  };

  // A protected structure for audio streams.
  struct RtApiStream {
    int device[2];          // Playback and record, respectively.
    void *apiHandle;        // void pointer for API specific stream handle information
    StreamMode mode;         // OUTPUT, INPUT, or DUPLEX.
    StreamState state;       // STOPPED or RUNNING
    char *userBuffer;
    char *deviceBuffer;
    bool doConvertBuffer[2]; // Playback and record, respectively.
    bool deInterleave[2];    // Playback and record, respectively.
    bool doByteSwap[2];      // Playback and record, respectively.
    int sampleRate;
    int bufferSize;
    int nBuffers;
    int nUserChannels[2];    // Playback and record, respectively.
    int nDeviceChannels[2];  // Playback and record channels, respectively.
    RtAudioFormat userFormat;
    RtAudioFormat deviceFormat[2]; // Playback and record, respectively.
    StreamMutex mutex;
    CallbackInfo callbackInfo;
    ConvertInfo convertInfo[2];

    RtApiStream()
      :apiHandle(0), userBuffer(0), deviceBuffer(0) {}
  };

  // A protected device structure for audio devices.
  struct RtApiDevice {
    std::string name;      
    bool probed;           
    void *apiDeviceId;     // void pointer for API specific device information
    int maxOutputChannels; 
    int maxInputChannels;  
    int maxDuplexChannels; 
    int minOutputChannels; 
    int minInputChannels;  
    int minDuplexChannels; 
    bool hasDuplexSupport; 
    bool isDefault;        
    std::vector<int> sampleRates; 
    RtAudioFormat nativeFormats;  
    // Default constructor.
    RtApiDevice()
      :probed(false), apiDeviceId(0), maxOutputChannels(0), maxInputChannels(0),
       maxDuplexChannels(0), minOutputChannels(0), minInputChannels(0),
       minDuplexChannels(0), isDefault(false), nativeFormats(0) {}
  };

  typedef signed short Int16;
  typedef signed int Int32;
  typedef float Float32;
  typedef double Float64;

  char message_[1024];
  int nDevices_;
  std::vector<RtApiDevice> devices_;
  RtApiStream stream_;

  virtual void initialize(void) = 0;

  virtual void probeDeviceInfo( RtApiDevice *info );

  virtual bool probeDeviceOpen( int device, StreamMode mode, int channels, 
                                int sampleRate, RtAudioFormat format,
                                int *bufferSize, int numberOfBuffers );

  virtual int getDefaultInputDevice(void);

  virtual int getDefaultOutputDevice(void);

  void clearDeviceInfo( RtApiDevice *info );

  void clearStreamInfo();

  void error( RtError::Type type );

  void verifyStream();

  void convertBuffer( char *outBuffer, char *inBuffer, ConvertInfo &info );

  void byteSwapBuffer( char *buffer, int samples, RtAudioFormat format );

  int formatBytes( RtAudioFormat format );
};


// **************************************************************** //
//
// RtAudio class declaration.
//
// RtAudio is a "controller" used to select an available audio i/o
// interface.  It presents a common API for the user to call but all
// functionality is implemented by the class RtAudioApi and its
// subclasses.  RtAudio creates an instance of an RtAudioApi subclass
// based on the user's API choice.  If no choice is made, RtAudio
// attempts to make a "logical" API selection.
//
// **************************************************************** //

class RtAudio
{
public:

  enum RtAudioApi {
    UNSPECIFIED,    
    LINUX_ALSA,     
    LINUX_OSS,      
    LINUX_JACK,     
    MACOSX_CORE,    
    IRIX_AL,        
    WINDOWS_ASIO,   
    WINDOWS_DS      
  };


  RtAudio( RtAudioApi api=UNSPECIFIED );


  RtAudio( int outputDevice, int outputChannels,
           int inputDevice, int inputChannels,
           RtAudioFormat format, int sampleRate,
           int *bufferSize, int numberOfBuffers, RtAudioApi api=UNSPECIFIED );


  RtAudio( int outputDevice, int outputChannels,
           int inputDevice, int inputChannels,
           RtAudioFormat format, int sampleRate,
           int *bufferSize, int *numberOfBuffers, RtAudioApi api=UNSPECIFIED );


  ~RtAudio();


  void openStream( int outputDevice, int outputChannels,
                   int inputDevice, int inputChannels,
                   RtAudioFormat format, int sampleRate,
                   int *bufferSize, int numberOfBuffers );


  void openStream( int outputDevice, int outputChannels,
                   int inputDevice, int inputChannels,
                   RtAudioFormat format, int sampleRate,
                   int *bufferSize, int *numberOfBuffers );


  void setStreamCallback(RtAudioCallback callback, void *userData) { rtapi_->setStreamCallback( callback, userData ); };


  void cancelStreamCallback() { rtapi_->cancelStreamCallback(); };

  int getDeviceCount(void) { return rtapi_->getDeviceCount(); };


  RtAudioDeviceInfo getDeviceInfo(int device) { return rtapi_->getDeviceInfo( device ); };


  char * const getStreamBuffer() { return rtapi_->getStreamBuffer(); };


  void tickStream() { rtapi_->tickStream(); };


  void closeStream()  { rtapi_->closeStream(); };


  void startStream() { rtapi_->startStream(); };


  void stopStream() { rtapi_->stopStream(); };


  void abortStream() { rtapi_->abortStream(); };


 protected:

  void initialize( RtAudioApi api );

  RtApi *rtapi_;
};


// RtApi Subclass prototypes.

#if defined(__LINUX_ALSA__)

class RtApiAlsa: public RtApi
{
public:

  RtApiAlsa();
  ~RtApiAlsa();
  void tickStream();
  void closeStream();
  void startStream();
  void stopStream();
  void abortStream();
  int streamWillBlock();
  void setStreamCallback( RtAudioCallback callback, void *userData );
  void cancelStreamCallback();

  private:

  void initialize(void);
  bool primeOutputBuffer();
  void probeDeviceInfo( RtApiDevice *info );
  bool probeDeviceOpen( int device, StreamMode mode, int channels, 
                        int sampleRate, RtAudioFormat format,
                        int *bufferSize, int numberOfBuffers );
};

#endif

#if defined(__LINUX_JACK__)

class RtApiJack: public RtApi
{
public:

  RtApiJack();
  ~RtApiJack();
  void tickStream();
  void closeStream();
  void startStream();
  void stopStream();
  void abortStream();
  void setStreamCallback( RtAudioCallback callback, void *userData );
  void cancelStreamCallback();
  // This function is intended for internal use only.  It must be
  // public because it is called by the internal callback handler,
  // which is not a member of RtAudio.  External use of this function
  // will most likely produce highly undesireable results!
  void callbackEvent( unsigned long nframes );

  private:

  void initialize(void);
  void probeDeviceInfo( RtApiDevice *info );
  bool probeDeviceOpen( int device, StreamMode mode, int channels, 
                        int sampleRate, RtAudioFormat format,
                        int *bufferSize, int numberOfBuffers );
};

#endif

#if defined(__LINUX_OSS__)

class RtApiOss: public RtApi
{
public:

  RtApiOss();
  ~RtApiOss();
  void tickStream();
  void closeStream();
  void startStream();
  void stopStream();
  void abortStream();
  int streamWillBlock();
  void setStreamCallback( RtAudioCallback callback, void *userData );
  void cancelStreamCallback();

  private:

  void initialize(void);
  void probeDeviceInfo( RtApiDevice *info );
  bool probeDeviceOpen( int device, StreamMode mode, int channels, 
                        int sampleRate, RtAudioFormat format,
                        int *bufferSize, int numberOfBuffers );
};

#endif

#if defined(__MACOSX_CORE__)

#include <CoreAudio/AudioHardware.h>

class RtApiCore: public RtApi
{
public:

  RtApiCore();
  ~RtApiCore();
  int getDefaultOutputDevice(void);
  int getDefaultInputDevice(void);
  void tickStream();
  void closeStream();
  void startStream();
  void stopStream();
  void abortStream();
  void setStreamCallback( RtAudioCallback callback, void *userData );
  void cancelStreamCallback();

  // This function is intended for internal use only.  It must be
  // public because it is called by the internal callback handler,
  // which is not a member of RtAudio.  External use of this function
  // will most likely produce highly undesireable results!
  void callbackEvent( AudioDeviceID deviceId, void *inData, void *outData );

  private:

  void initialize(void);
  void probeDeviceInfo( RtApiDevice *info );
  bool probeDeviceOpen( int device, StreamMode mode, int channels, 
                        int sampleRate, RtAudioFormat format,
                        int *bufferSize, int numberOfBuffers );
};

#endif

#if defined(__WINDOWS_DS__)

class RtApiDs: public RtApi
{
public:

  RtApiDs();
  ~RtApiDs();
  int getDefaultOutputDevice(void);
  int getDefaultInputDevice(void);
  void tickStream();
  void closeStream();
  void startStream();
  void stopStream();
  void abortStream();
  int streamWillBlock();
  void setStreamCallback( RtAudioCallback callback, void *userData );
  void cancelStreamCallback();

  public:
  // \brief Internal structure that provide debug information on the state of a running DSound device.
  struct RtDsStatistics {
    // \brief Sample Rate.
    long sampleRate;
    // \brief The size of one sample * number of channels on the input device.
    int inputFrameSize; 
    // \brief The size of one sample * number of channels on the output device.
    int outputFrameSize; 
    /* \brief The number of times the read pointer had to be adjusted to avoid reading from an unsafe buffer position.
     *
     * This field is only used when running in DUPLEX mode. INPUT mode devices just wait until the data is 
     * available.
     */
    int numberOfReadOverruns;
    // \brief The number of times the write pointer had to be adjusted to avoid writing in an unsafe buffer position.
    int numberOfWriteUnderruns;
    // \brief Number of bytes by attribute to buffer configuration by which writing must lead the current write pointer.
    int writeDeviceBufferLeadBytes;
    // \brief Number of bytes by attributable to the device driver by which writing must lead the current write pointer on this output device.
    unsigned long writeDeviceSafeLeadBytes;
    // \brief Number of bytes by which reading must trail the current read pointer on this input device.
    unsigned long readDeviceSafeLeadBytes; 
    /* \brief Estimated latency in seconds. 
    *
    * For INPUT mode devices, based the latency of the device's safe read pointer, plus one buffer's
    * worth of additional latency.
    *
    * For OUTPUT mode devices, the latency of the device's safe write pointer, plus N buffers of 
    * additional buffer latency.
    *
    * For DUPLEX devices, the sum of latencies for both input and output devices. DUPLEX devices
    * also back off the read pointers an additional amount in order to maintain synchronization 
    * between out-of-phase read and write pointers. This time is also included.
    *
    * Note that most software packages report latency between the safe write pointer 
    * and the software lead pointer, excluding the hardware device's safe write pointer 
    * latency. Figures of 1 or 2ms of latency on Windows audio devices are invariably of this type.
    * The reality is that hardware devices often have latencies of 30ms or more (often much 
    * higher for duplex operation).
    */

    double latency;
  };
  // \brief Report on the current state of a running DSound device.
  static RtDsStatistics getDsStatistics();

  private:

  void initialize(void);
  void probeDeviceInfo( RtApiDevice *info );
  bool probeDeviceOpen( int device, StreamMode mode, int channels, 
                        int sampleRate, RtAudioFormat format,
                        int *bufferSize, int numberOfBuffers );

  bool coInitialized;
  bool buffersRolling;
  long duplexPrerollBytes;
  static RtDsStatistics statistics;

};

#endif

#if defined(__WINDOWS_ASIO__)

class RtApiAsio: public RtApi
{
public:

  RtApiAsio();
  ~RtApiAsio();
  void tickStream();
  void closeStream();
  void startStream();
  void stopStream();
  void abortStream();
  void setStreamCallback( RtAudioCallback callback, void *userData );
  void cancelStreamCallback();

  // This function is intended for internal use only.  It must be
  // public because it is called by the internal callback handler,
  // which is not a member of RtAudio.  External use of this function
  // will most likely produce highly undesireable results!
  void callbackEvent( long bufferIndex );

  private:

  void initialize(void);
  void probeDeviceInfo( RtApiDevice *info );
  bool probeDeviceOpen( int device, StreamMode mode, int channels, 
                        int sampleRate, RtAudioFormat format,
                        int *bufferSize, int numberOfBuffers );

  bool coInitialized;

};

#endif

#if defined(__IRIX_AL__)

class RtApiAl: public RtApi
{
public:

  RtApiAl();
  ~RtApiAl();
  int getDefaultOutputDevice(void);
  int getDefaultInputDevice(void);
  void tickStream();
  void closeStream();
  void startStream();
  void stopStream();
  void abortStream();
  int streamWillBlock();
  void setStreamCallback( RtAudioCallback callback, void *userData );
  void cancelStreamCallback();

  private:

  void initialize(void);
  void probeDeviceInfo( RtApiDevice *info );
  bool probeDeviceOpen( int device, StreamMode mode, int channels, 
                        int sampleRate, RtAudioFormat format,
                        int *bufferSize, int numberOfBuffers );
};

#endif

// Define the following flag to have extra information spewed to stderr.
//#define __RTAUDIO_DEBUG__

#endif

---

©2001-2005 Gary P. Scavone, McGill University. All Rights Reserved. Maintained by Gary P. Scavone, gary@music.mcgill.ca