RtAudio WWW site: http://www.music.mcgill.ca/~gary/rtaudio/
RtAudio: realtime audio i/o C++ classes
- Copyright (c) 2001-2012 Gary P. Scavone
+ Copyright (c) 2001-2013 Gary P. Scavone
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation files
\file RtAudio.h
*/
-// RtAudio: Version 4.0.11
-
#ifndef __RTAUDIO_H
#define __RTAUDIO_H
#include <string>
#include <vector>
-#include "RtError.h"
+#include <exception>
+#include <iostream>
+
+// RtAudio version: 4.1.0pre
/*! \typedef typedef unsigned long RtAudioFormat;
\brief RtAudio data format type.
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.
- Note that 24-bit data is expected to be encapsulated in a 32-bit
- format.
- \e RTAUDIO_SINT8: 8-bit signed integer.
- \e RTAUDIO_SINT16: 16-bit signed integer.
- - \e RTAUDIO_SINT24: Lower 3 bytes of 32-bit signed integer.
+ - \e RTAUDIO_SINT24: 24-bit signed integer.
- \e RTAUDIO_SINT32: 32-bit signed integer.
- \e RTAUDIO_FLOAT32: Normalized between plus/minus 1.0.
- \e RTAUDIO_FLOAT64: Normalized between plus/minus 1.0.
typedef unsigned long RtAudioFormat;
static const RtAudioFormat RTAUDIO_SINT8 = 0x1; // 8-bit signed integer.
static const RtAudioFormat RTAUDIO_SINT16 = 0x2; // 16-bit signed integer.
-static const RtAudioFormat RTAUDIO_SINT24 = 0x4; // Lower 3 bytes of 32-bit signed integer.
+static const RtAudioFormat RTAUDIO_SINT24 = 0x4; // 24-bit signed integer.
static const RtAudioFormat RTAUDIO_SINT32 = 0x8; // 32-bit signed integer.
static const RtAudioFormat RTAUDIO_FLOAT32 = 0x10; // Normalized between plus/minus 1.0.
static const RtAudioFormat RTAUDIO_FLOAT64 = 0x20; // Normalized between plus/minus 1.0.
RtAudioStreamStatus status,
void *userData );
+/************************************************************************/
+/*! \class RtAudioError
+ \brief Exception handling class for RtAudio.
+
+ The RtAudioError class is quite simple but it does allow errors to be
+ "caught" by RtAudioError::Type. See the RtAudio and RtMidi
+ documentation to know which methods can throw an RtAudioError.
+
+*/
+/************************************************************************/
+
+class RtAudioError : public std::exception
+{
+ public:
+ //! Defined RtAudioError types.
+ enum Type {
+ WARNING, /*!< A non-critical error. */
+ DEBUG_WARNING, /*!< A non-critical error which might be useful for debugging. */
+ UNSPECIFIED, /*!< The default, unspecified error type. */
+ NO_DEVICES_FOUND, /*!< No devices found on system. */
+ INVALID_DEVICE, /*!< An invalid device ID was specified. */
+ MEMORY_ERROR, /*!< An error occured during memory allocation. */
+ INVALID_PARAMETER, /*!< An invalid parameter was specified to a function. */
+ INVALID_USE, /*!< The function was called incorrectly. */
+ DRIVER_ERROR, /*!< A system driver error occured. */
+ SYSTEM_ERROR, /*!< A system error occured. */
+ THREAD_ERROR /*!< A thread error occured. */
+ };
+
+ //! The constructor.
+ RtAudioError( const std::string& message, Type type = RtAudioError::UNSPECIFIED ) throw() : message_(message), type_(type) {}
+
+ //! The destructor.
+ virtual ~RtAudioError( void ) throw() {}
+
+ //! Prints thrown error message to stderr.
+ virtual void printMessage( void ) const throw() { std::cerr << '\n' << message_ << "\n\n"; }
+
+ //! Returns the thrown error message type.
+ virtual const Type& getType(void) const throw() { return type_; }
+
+ //! Returns the thrown error message string.
+ virtual const std::string& getMessage(void) const throw() { return message_; }
+
+ //! Returns the thrown error message as a c-style string.
+ virtual const char* what( void ) const throw() { return message_.c_str(); }
+
+ protected:
+ std::string message_;
+ Type type_;
+};
+
+//! RtAudio error callback function prototype.
+/*!
+ \param type Type of error.
+ \param errorText Error description.
+ */
+typedef void (*RtAudioErrorCallback)( RtAudioError::Type type, const std::string &errorText );
// **************************************************************** //
//
: flags(0), numberOfBuffers(0), priority(0) {}
};
+ //! A static function to determine the current RtAudio version.
+ static std::string getVersion( void ) { return "4.1.0"; }
+
//! A static function to determine the available compiled audio APIs.
/*!
The values returned in the std::vector can be compared against
/*!
Any device integer between 0 and getDeviceCount() - 1 is valid.
- If an invalid argument is provided, an RtError (type = INVALID_USE)
+ If an invalid argument is provided, an RtAudioError (type = INVALID_USE)
will be thrown. If a device is busy or otherwise unavailable, the
structure member "probed" will have a value of "false" and all
other members are undefined. If the specified device is the
//! A public function for opening a stream with the specified parameters.
/*!
- An RtError (type = SYSTEM_ERROR) is thrown if a stream cannot be
+ An RtAudioError (type = SYSTEM_ERROR) is thrown if a stream cannot be
opened with the specified parameters or an error occurs during
- processing. An RtError (type = INVALID_USE) is thrown if any
+ processing. An RtAudioError (type = INVALID_USE) is thrown if any
invalid device ID or channel number parameters are specified.
\param outputParameters Specifies output stream parameters to use
chosen. If the RTAUDIO_MINIMIZE_LATENCY flag bit is set, the
lowest allowable value is used. The actual value used is
returned via the structure argument. The parameter is API dependent.
+ \param errorCallback A client-defined function that will be invoked
+ when an error has occured.
*/
void openStream( RtAudio::StreamParameters *outputParameters,
RtAudio::StreamParameters *inputParameters,
RtAudioFormat format, unsigned int sampleRate,
unsigned int *bufferFrames, RtAudioCallback callback,
- void *userData = NULL, RtAudio::StreamOptions *options = NULL );
+ void *userData = NULL, RtAudio::StreamOptions *options = NULL, RtAudioErrorCallback errorCallback = NULL );
//! A function that closes a stream and frees any associated stream memory.
/*!
//! A function that starts a stream.
/*!
- An RtError (type = SYSTEM_ERROR) is thrown if an error occurs
- during processing. An RtError (type = INVALID_USE) is thrown if a
+ An RtAudioError (type = SYSTEM_ERROR) is thrown if an error occurs
+ during processing. An RtAudioError (type = INVALID_USE) is thrown if a
stream is not open. A warning is issued if the stream is already
running.
*/
//! Stop a stream, allowing any samples remaining in the output queue to be played.
/*!
- An RtError (type = SYSTEM_ERROR) is thrown if an error occurs
- during processing. An RtError (type = INVALID_USE) is thrown if a
+ An RtAudioError (type = SYSTEM_ERROR) is thrown if an error occurs
+ during processing. An RtAudioError (type = INVALID_USE) is thrown if a
stream is not open. A warning is issued if the stream is already
stopped.
*/
//! Stop a stream, discarding any samples remaining in the input/output queue.
/*!
- An RtError (type = SYSTEM_ERROR) is thrown if an error occurs
- during processing. An RtError (type = INVALID_USE) is thrown if a
+ An RtAudioError (type = SYSTEM_ERROR) is thrown if an error occurs
+ during processing. An RtAudioError (type = INVALID_USE) is thrown if a
stream is not open. A warning is issued if the stream is already
stopped.
*/
//! Returns the number of elapsed seconds since the stream was started.
/*!
- If a stream is not open, an RtError (type = INVALID_USE) will be thrown.
+ If a stream is not open, an RtAudioError (type = INVALID_USE) will be thrown.
*/
double getStreamTime( void );
caused by internal buffering by the audio system and/or hardware.
For duplex streams, the returned value will represent the sum of
the input and output latencies. If a stream is not open, an
- RtError (type = INVALID_USE) will be thrown. If the API does not
+ RtAudioError (type = INVALID_USE) will be thrown. If the API does not
report latency, the return value will be zero.
*/
long getStreamLatency( void );
/*!
On some systems, the sample rate used may be slightly different
than that specified in the stream parameters. If a stream is not
- open, an RtError (type = INVALID_USE) will be thrown.
+ open, an RtAudioError (type = INVALID_USE) will be thrown.
*/
unsigned int getStreamSampleRate( void );
#include <windows.h>
#include <process.h>
- typedef unsigned long ThreadHandle;
+ typedef ULONG_PTR ThreadHandle;
typedef CRITICAL_SECTION StreamMutex;
#elif defined(__LINUX_ALSA__) || defined(__LINUX_PULSE__) || defined(__UNIX_JACK__) || defined(__LINUX_OSS__) || defined(__MACOSX_CORE__)
ThreadHandle thread;
void *callback;
void *userData;
+ void *errorCallback;
void *apiInfo; // void pointer for API specific callback information
bool isRunning;
+ bool doRealtime;
+ int priority;
// Default constructor.
CallbackInfo()
- :object(0), callback(0), userData(0), apiInfo(0), isRunning(false) {}
+ :object(0), callback(0), userData(0), errorCallback(0), apiInfo(0), isRunning(false), doRealtime(false) {}
};
// **************************************************************** //
RtAudio::StreamParameters *inputParameters,
RtAudioFormat format, unsigned int sampleRate,
unsigned int *bufferFrames, RtAudioCallback callback,
- void *userData, RtAudio::StreamOptions *options );
+ void *userData, RtAudio::StreamOptions *options,
+ RtAudioErrorCallback errorCallback );
virtual void closeStream( void );
virtual void startStream( void ) = 0;
virtual void stopStream( void ) = 0;
long getStreamLatency( void );
unsigned int getStreamSampleRate( void );
virtual double getStreamTime( void );
- bool isStreamOpen( void ) const { return stream_.state != STREAM_CLOSED; };
- bool isStreamRunning( void ) const { return stream_.state == STREAM_RUNNING; };
- void showWarnings( bool value ) { showWarnings_ = value; };
+ bool isStreamOpen( void ) const { return stream_.state != STREAM_CLOSED; }
+ bool isStreamRunning( void ) const { return stream_.state == STREAM_RUNNING; }
+ void showWarnings( bool value ) { showWarnings_ = value; }
protected:
std::string errorText_;
bool showWarnings_;
RtApiStream stream_;
+ bool firstErrorOccurred;
/*!
Protected, api-specific method that attempts to open a device
void clearStreamInfo();
/*!
- Protected common method that throws an RtError (type =
+ Protected common method that throws an RtAudioError (type =
INVALID_USE) if a stream is not open.
*/
void verifyStream( void );
//! Protected common error method to allow global control over error handling.
- void error( RtError::Type type );
+ void error( RtAudioError::Type type );
/*!
Protected method used to perform format, channel number, and/or interleaving
inline bool RtAudio :: isStreamOpen( void ) const throw() { return rtapi_->isStreamOpen(); }
inline bool RtAudio :: isStreamRunning( void ) const throw() { return rtapi_->isStreamRunning(); }
inline long RtAudio :: getStreamLatency( void ) { return rtapi_->getStreamLatency(); }
-inline unsigned int RtAudio :: getStreamSampleRate( void ) { return rtapi_->getStreamSampleRate(); };
+inline unsigned int RtAudio :: getStreamSampleRate( void ) { return rtapi_->getStreamSampleRate(); }
inline double RtAudio :: getStreamTime( void ) { return rtapi_->getStreamTime(); }
inline void RtAudio :: showWarnings( bool value ) throw() { rtapi_->showWarnings( value ); }
RtApiCore();
~RtApiCore();
- RtAudio::Api getCurrentApi( void ) { return RtAudio::MACOSX_CORE; };
+ RtAudio::Api getCurrentApi( void ) { return RtAudio::MACOSX_CORE; }
unsigned int getDeviceCount( void );
RtAudio::DeviceInfo getDeviceInfo( unsigned int device );
unsigned int getDefaultOutputDevice( void );
RtApiJack();
~RtApiJack();
- RtAudio::Api getCurrentApi( void ) { return RtAudio::UNIX_JACK; };
+ RtAudio::Api getCurrentApi( void ) { return RtAudio::UNIX_JACK; }
unsigned int getDeviceCount( void );
RtAudio::DeviceInfo getDeviceInfo( unsigned int device );
void closeStream( void );
RtApiAsio();
~RtApiAsio();
- RtAudio::Api getCurrentApi( void ) { return RtAudio::WINDOWS_ASIO; };
+ RtAudio::Api getCurrentApi( void ) { return RtAudio::WINDOWS_ASIO; }
unsigned int getDeviceCount( void );
RtAudio::DeviceInfo getDeviceInfo( unsigned int device );
void closeStream( void );
RtApiDs();
~RtApiDs();
- RtAudio::Api getCurrentApi( void ) { return RtAudio::WINDOWS_DS; };
+ RtAudio::Api getCurrentApi( void ) { return RtAudio::WINDOWS_DS; }
unsigned int getDeviceCount( void );
unsigned int getDefaultOutputDevice( void );
unsigned int getDefaultInputDevice( void );
bool coInitialized_;
bool buffersRolling;
long duplexPrerollBytes;
+ std::vector<struct DsDevice> dsDevices;
bool probeDeviceOpen( unsigned int device, StreamMode mode, unsigned int channels,
unsigned int firstChannel, unsigned int sampleRate,
RtAudioFormat format, unsigned int *bufferSize,
RtApiAlsa();
~RtApiAlsa();
- RtAudio::Api getCurrentApi() { return RtAudio::LINUX_ALSA; };
+ RtAudio::Api getCurrentApi() { return RtAudio::LINUX_ALSA; }
unsigned int getDeviceCount( void );
RtAudio::DeviceInfo getDeviceInfo( unsigned int device );
void closeStream( void );
{
public:
~RtApiPulse();
- RtAudio::Api getCurrentApi() { return RtAudio::LINUX_PULSE; };
+ RtAudio::Api getCurrentApi() { return RtAudio::LINUX_PULSE; }
unsigned int getDeviceCount( void );
RtAudio::DeviceInfo getDeviceInfo( unsigned int device );
void closeStream( void );
RtApiOss();
~RtApiOss();
- RtAudio::Api getCurrentApi() { return RtAudio::LINUX_OSS; };
+ RtAudio::Api getCurrentApi() { return RtAudio::LINUX_OSS; }
unsigned int getDeviceCount( void );
RtAudio::DeviceInfo getDeviceInfo( unsigned int device );
void closeStream( void );
{
public:
- RtApiDummy() { errorText_ = "RtApiDummy: This class provides no functionality."; error( RtError::WARNING ); };
- RtAudio::Api getCurrentApi( void ) { return RtAudio::RTAUDIO_DUMMY; };
- unsigned int getDeviceCount( void ) { return 0; };
- RtAudio::DeviceInfo getDeviceInfo( unsigned int device ) { RtAudio::DeviceInfo info; return info; };
- void closeStream( void ) {};
- void startStream( void ) {};
- void stopStream( void ) {};
- void abortStream( void ) {};
+ RtApiDummy() { errorText_ = "RtApiDummy: This class provides no functionality."; error( RtAudioError::WARNING ); }
+ RtAudio::Api getCurrentApi( void ) { return RtAudio::RTAUDIO_DUMMY; }
+ unsigned int getDeviceCount( void ) { return 0; }
+ RtAudio::DeviceInfo getDeviceInfo( unsigned int /*device*/ ) { RtAudio::DeviceInfo info; return info; }
+ void closeStream( void ) {}
+ void startStream( void ) {}
+ void stopStream( void ) {}
+ void abortStream( void ) {}
private:
- bool probeDeviceOpen( unsigned int device, StreamMode mode, unsigned int channels,
- unsigned int firstChannel, unsigned int sampleRate,
- RtAudioFormat format, unsigned int *bufferSize,
- RtAudio::StreamOptions *options ) { return false; };
+ bool probeDeviceOpen( unsigned int /*device*/, StreamMode /*mode*/, unsigned int /*channels*/,
+ unsigned int /*firstChannel*/, unsigned int /*sampleRate*/,
+ RtAudioFormat /*format*/, unsigned int * /*bufferSize*/,
+ RtAudio::StreamOptions * /*options*/ ) { return false; }
};
#endif