RtAudio.h File Reference

#include <string>
#include <vector>
#include "RtError.h"
@@ -21,141 +22,110 @@ class RtAudio Realtime audio i/o C++ classes. More...
-struct RtAudio::DeviceInfo +struct RtAudio::RtAudio::DeviceInfo The public device information structure for returning queried values. More...
-struct RtAudio::StreamParameters +struct RtAudio::RtAudio::StreamParameters The structure for specifying input or ouput stream parameters. More...
-struct RtAudio::StreamOptions +struct RtAudio::RtAudio::StreamOptions The structure for specifying stream options. More...

Typedefs

-typedef unsigned long RtAudioFormat +typedef unsigned long RtAudioFormat - RtAudio data format type.
-typedef unsigned int RtAudioStreamFlags + RtAudio data format type.
+typedef unsigned int RtAudioStreamFlags - RtAudio stream option flags.
-typedef unsigned int RtAudioStreamStatus + RtAudio stream option flags.
+typedef unsigned int RtAudioStreamStatus - RtAudio stream status (over- or underflow) flags.
-typedef int(* RtAudioCallback )(void *outputBuffer, void *inputBuffer, unsigned int nFrames, double streamTime, RtAudioStreamStatus status, void *userData) + RtAudio stream status (over- or underflow) flags.
+typedef int(* RtAudioCallback )(void *outputBuffer, void *inputBuffer, unsigned int nFrames, double streamTime, RtAudioStreamStatus status, void *userData) - RtAudio callback function prototype.
+ RtAudio callback function prototype.

Detailed Description

Typedef Documentation

-

- - - - -
- + +
+
+
- +

typedef unsigned long RtAudioFormat typedef unsigned long RtAudioFormat

-
- - - - - -
- - + +

-RtAudio data format type. +RtAudio data format type.
-Support for signed integers and floats. Audio data fed to/from an RtAudio stream 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.
+Support for signed integers and floats. Audio data fed to/from an RtAudio stream 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.

-
RTAUDIO_SINT8: 8-bit signed integer.
RTAUDIO_SINT16: 16-bit signed integer.
RTAUDIO_SINT24: Upper 3 bytes of 32-bit signed integer.
RTAUDIO_SINT32: 32-bit signed integer.
RTAUDIO_FLOAT32: Normalized between plus/minus 1.0.
RTAUDIO_FLOAT64: Normalized between plus/minus 1.0.
-
-

- - - - -
- +
RTAUDIO_SINT8: 8-bit signed integer.
RTAUDIO_SINT16: 16-bit signed integer.
RTAUDIO_SINT24: Upper 3 bytes of 32-bit signed integer.
RTAUDIO_SINT32: 32-bit signed integer.
RTAUDIO_FLOAT32: Normalized between plus/minus 1.0.
RTAUDIO_FLOAT64: Normalized between plus/minus 1.0.
+ + +
+ +
+
+
- +

typedef unsigned long RtAudioStreamFlags typedef unsigned long RtAudioStreamFlags

-
- - - - - -
- - + +

-RtAudio stream option flags. +RtAudio stream option flags.
The following flags can be OR'ed together to allow a client to make changes to the default stream behavior:

RTAUDIO_NONINTERLEAVED: Use non-interleaved buffers (default = interleaved).
RTAUDIO_MINIMIZE_LATENCY: Attempt to set stream parameters for lowest possible latency.
RTAUDIO_HOG_DEVICE: Attempt grab device for exclusive use.

-By default, RtAudio streams pass and receive audio data from the client in an interleaved format. By passing the RTAUDIO_NONINTERLEAVED flag to the openStream() function, audio data will instead be presented in non-interleaved buffers. In this case, each buffer argument in the RtAudioCallback function will point to a single array of data, with nFrames samples for each channel concatenated back-to-back. For example, the first sample of data for the second channel would be located at index nFrames (assuming the buffer pointer was recast to the correct data type for the stream).
-Certain audio APIs offer a number of parameters that influence the I/O latency of a stream. By default, RtAudio will attempt to set these parameters internally for robust (glitch-free) performance (though some APIs, like Windows Direct Sound, make this difficult). By passing the RTAUDIO_MINIMIZE_LATENCY flag to the openStream() function, internal stream settings will be influenced in an attempt to minimize stream latency, though possibly at the expense of stream performance.
-If the RTAUDIO_HOG_DEVICE flag is set, RtAudio will attempt to open the input and/or output stream device(s) for exclusive use. Note that this is not possible with all supported audio APIs.
-

- - - - -
- +By default, RtAudio streams pass and receive audio data from the client in an interleaved format. By passing the RTAUDIO_NONINTERLEAVED flag to the openStream() function, audio data will instead be presented in non-interleaved buffers. In this case, each buffer argument in the RtAudioCallback function will point to a single array of data, with nFrames samples for each channel concatenated back-to-back. For example, the first sample of data for the second channel would be located at index nFrames (assuming the buffer pointer was recast to the correct data type for the stream).
+Certain audio APIs offer a number of parameters that influence the I/O latency of a stream. By default, RtAudio will attempt to set these parameters internally for robust (glitch-free) performance (though some APIs, like Windows Direct Sound, make this difficult). By passing the RTAUDIO_MINIMIZE_LATENCY flag to the openStream() function, internal stream settings will be influenced in an attempt to minimize stream latency, though possibly at the expense of stream performance.
+If the RTAUDIO_HOG_DEVICE flag is set, RtAudio will attempt to open the input and/or output stream device(s) for exclusive use. Note that this is not possible with all supported audio APIs.
+If the RTAUDIO_SCHEDULE_REALTIME flag is set, RtAudio will attempt to select realtime scheduling (round-robin) for the callback thread. + +
+ +
+
+
- +

typedef unsigned long RtAudioStreamStatus typedef unsigned long RtAudioStreamStatus

-
- - - - - -
- - + +

-RtAudio stream status (over- or underflow) flags. +RtAudio stream status (over- or underflow) flags.
Notification of a stream over- or underflow is indicated by a non-zero stream status argument in the RtAudioCallback function. The stream status can be one of the following two options, depending on whether the stream is open for output and/or input:

-
RTAUDIO_INPUT_OVERFLOW: Input data was discarded because of an overflow condition at the driver.
RTAUDIO_OUTPUT_UNDERFLOW: The output buffer ran low, likely producing a break in the output sound.
-
-

- - - - -
- +
RTAUDIO_INPUT_OVERFLOW: Input data was discarded because of an overflow condition at the driver.
RTAUDIO_OUTPUT_UNDERFLOW: The output buffer ran low, likely producing a break in the output sound.
+ + +
+ +
+
+
- +

typedef int(* RtAudioCallback)(void *outputBuffer, void *inputBuffer, unsigned int nFrames, double streamTime, RtAudioStreamStatus status, void *userData) typedef int(* RtAudioCallback)(void *outputBuffer, void *inputBuffer, unsigned int nFrames, double streamTime, RtAudioStreamStatus status, void *userData)

-
- - - - - -
- - + +

-RtAudio callback function prototype. +RtAudio callback function prototype.
-All RtAudio clients must create a function of type RtAudioCallback to read and/or write data from/to the audio stream. When the underlying audio system is ready for new input or output data, this function will be invoked.
+All RtAudio clients must create a function of type RtAudioCallback to read and/or write data from/to the audio stream. When the underlying audio system is ready for new input or output data, this function will be invoked.

Parameters:
@@ -166,13 +136,14 @@ All RtAudio clients must create a fun

outputBuffer For output (or duplex) streams, the client should write nFrames of audio sample frames into this buffer. This argument should be recast to the datatype specified when the stream was opened. For input-only streams, this argument will be NULL.
userData A pointer to optional data provided by the client when opening the stream (default = NULL).

-To continue normal stream operation, the RtAudioCallback function should return a value of zero. To stop the stream and drain the output buffer, the function should return a value of one. To abort the stream immediately, the client should return a value of two.
+To continue normal stream operation, the RtAudioCallback function should return a value of zero. To stop the stream and drain the output buffer, the function should return a value of one. To abort the stream immediately, the client should return a value of two. +

	©2001-2008 Gary P. Scavone, McGill University. All Rights Reserved. Maintained by Gary P. Scavone.
©2001-2009 Gary P. Scavone, McGill University. All Rights Reserved. Maintained by Gary P. Scavone.