X-Git-Url: https://git.carlh.net/gitweb/?a=blobdiff_plain;f=doc%2Fdoxygen%2Ftutorial.txt;h=b42a945a7f728b3f4232545542f8603c82bbac33;hb=d80e83b7145a6c2ecaa6d7fc6ade83ef124515a1;hp=951b28b79fdb9c8df709bb4e63a7644bd3363b2f;hpb=8eb71e693530726068addf6b8088aea0fd340f2a;p=rtaudio-cdist.git diff --git a/doc/doxygen/tutorial.txt b/doc/doxygen/tutorial.txt index 951b28b..b42a945 100644 --- a/doc/doxygen/tutorial.txt +++ b/doc/doxygen/tutorial.txt @@ -1,630 +1,54 @@ -/*! \mainpage The RtAudio Tutorial - -
- -- \ref intro -- \ref start -- \ref error -- \ref probing -- \ref settings -- \ref playbackb -- \ref playbackc -- \ref recording -- \ref duplex -- \ref methods -- \ref compiling -- \ref osnotes -- \ref acknowledge - -\section intro Introduction - -RtAudio is a C++ class which provides a common API (Application Programming Interface) for realtime audio input/output across Linux (native ALSA and OSS), SGI, and Windows operating systems. RtAudio significantly simplifies the process of interacting with computer audio hardware. It was designed with the following goals: - -- -
OS: | -Audio API: | -Preprocessor Definition: | -Library: | -Example Compiler Statement: | -
Linux | -ALSA | -__LINUX_ALSA__ | -libasound, libpthread | -g++ -Wall -D__LINUX_ALSA__ -o probe probe.cpp RtAudio.cpp -lasound -lpthread | -
Linux | -OSS | -__LINUX_OSS__ | -libpthread | -g++ -Wall -D__LINUX_OSS__ -o probe probe.cpp RtAudio.cpp -lpthread | -
Irix | -AL | -__IRIX_AL__ | -libaudio, libpthread | -CC -Wall -D__IRIX_AL__ -o probe probe.cpp RtAudio.cpp -laudio -lpthread | -
Windows | -Direct Sound | -__WINDOWS_DS__ | -dsound.lib (ver. 5.0 or higher), multithreaded | -compiler specific | -
- -The example compiler statements above could be used to compile the probe.cpp example file, assuming that probe.cpp, RtAudio.h, and RtAudio.cpp all exist in the same directory. - -\section osnotes OS Notes - -RtAudio is designed to provide a common API across the various supported operating systems and audio libraries. Despite that, however, some issues need to be mentioned with regard to each. - -\subsection linux Linux: - -RtAudio for Linux was developed under Redhat distributions 7.0 - 7.2. Two different audio APIs are supported on Linux platforms: OSS and ALSA. The OSS API has existed for at least 6 years and the Linux kernel is distributed with free versions of OSS audio drivers. Therefore, a generic Linux system is most likely to have OSS support. The ALSA API, although relatively new, is now part of the Linux development kernel and offers significantly better functionality than the OSS API. RtAudio provides support for the 0.9 and higher versions of ALSA. Input/output latency on the order of 15 milliseconds can typically be achieved under both OSS or ALSA by fine-tuning the RtAudio buffer parameters (without kernel modifications). Latencies on the order of 5 milliseconds or less can be achieved using a low-latency kernel patch and increasing FIFO scheduling priority. The pthread library, which is used for callback functionality, is a standard component of all Linux distributions. - -The ALSA library includes OSS emulation support. That means that you can run programs compiled for the OSS API even when using the ALSA drivers and library. It should be noted however that OSS emulation under ALSA is not perfect. Specifically, channel number queries seem to consistently produce invalid results. While OSS emulation is successful for the majority of RtAudio tests, it is recommended that the native ALSA implementation of RtAudio be used on systems which have ALSA drivers installed. - -The ALSA implementation of RtAudio makes no use of the ALSA "plug" interface. All necessary data format conversions, channel compensation, deinterleaving, and byte-swapping is handled by internal RtAudio routines. - -\subsection irix Irix (SGI): - -The Irix version of RtAudio was written and tested on an SGI Indy running Irix version 6.5.4 and the newer "al" audio library. RtAudio does not compile under Irix version 6.3, mainly because the C++ compiler is too old. Despite the relatively slow speed of the Indy, RtAudio was found to behave quite well and input/output latency was very good. No problems were found with respect to using the pthread library. - -\subsection windows Windows: - -RtAudio under Windows is written using the DirectSound API. In order to compile RtAudio under Windows, you must have the header and source files for DirectSound version 5.0 or higher. As far as I know, there is no DirectSoundCapture support for Windows NT (in which case, you cannot use RtAudio). Audio output latency with DirectSound can be reasonably good (on the order of 20 milliseconds). On the other hand, input audio latency tends to be terrible (100 milliseconds or more). Further, DirectSound drivers tend to crash easily when experimenting with buffer parameters. On my system, I found it necessary to use values around nBuffers = 8 and bufferSize = 512 to avoid crashing my system. RtAudio was developed with Visual C++ version 6.0. I was forced in several instances to modify code in order to get it to compile under the non-standard version of C++ that Microsoft so unprofessionally implemented. We can only hope that the developers of Visual C++ 7.0 will have time to read the C++ standard. - - -\section acknowledge Acknowledgements - -The RtAudio API incorporates many of the concepts developed in the PortAudio project by Phil Burk and Ross Bencina. Early development also incorporated ideas from Bill Schottstaedt's sndlib. The CCRMA SoundWire group provided valuable feedback during the API proposal stages. - -RtAudio was slowly developed over the course of many months while in residence at the Institut Universitari de L'Audiovisual (IUA) in Barcelona, Spain, the Laboratory of Acoustics and Audio Signal Processing at the Helsinki University of Technology, Finland, and the Center for Computer Research in Music and Acoustics (CCRMA) at Stanford University. This work was supported in part by the United States Air Force Office of Scientific Research (grant \#F49620-99-1-0293). - -*/ +/*! \mainpage The RtAudio Home Page + +RtAudio is a set of C++ classes that provide a common API (Application Programming Interface) for realtime audio input/output across Linux, Macintosh OS-X and Windows (DirectSound and ASIO) operating systems. RtAudio significantly simplifies the process of interacting with computer audio hardware. It was designed with the following objectives: + +