doc/html/apinotes.html

   1 <HTML>
   2 <HEAD>
   3 <TITLE>The RtAudio Home Page</TITLE>
   4 <LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css">
   5 <LINK REL="SHORTCUT ICON" HREF="http://www.music.mcgill.ca/~gary/favicon.ico">
   6 </HEAD>
   7 <BODY BGCOLOR="#FFFFFF">
   8 <CENTER>
   9 <a class="qindex" href="index.html">Home</a> &nbsp; <a class="qindex" href="annotated.html">Class/Enum List</a> &nbsp; <a class="qindex" href="files.html">File List</a> &nbsp; <a class="qindex" href="functions.html">Compound Members</a> &nbsp; </CENTER>
  10 <HR>
  11 <!-- Generated by Doxygen 1.8.2 -->
  12 </div><!-- top -->
  13 <div class="header">
  14   <div class="headertitle">
  15 <div class="title">API Notes </div>  </div>
  16 </div><!--header-->
  17 <div class="contents">
  18 <div class="textblock"><p><a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> is designed to provide a common API across the various supported operating systems and audio libraries. Despite that, some issues should be mentioned with regard to each.</p>
  19 <h1><a class="anchor" id="linux"></a>
  20 Linux:</h1>
  21 <p><a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> for Linux was developed under Redhat distributions 7.0 - Fedora. Four different audio APIs are supported on Linux platforms: <a href="http://www.opensound.com/oss.html">OSS</a> (versions &gt;= 4.0), <a href="http://www.alsa-project.org/">ALSA</a>, <a href="http://jackit.sourceforge.net/">Jack</a>, and <a href="http://www.freedesktop.org/wiki/Software/PulseAudio">PulseAudio</a>. Note that <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> now only supports the newer version 4.0 OSS API. The ALSA API is now part of the Linux kernel and offers significantly better functionality than the OSS API. <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> provides support for the 1.0 and higher versions of ALSA. Jack is a low-latency audio server written primarily for the GNU/Linux operating system. It can connect a number of different applications to an audio device, as well as allow them to share audio between themselves. Input/output latency on the order of 15 milliseconds can typically be achieved using any of the Linux APIs by fine-tuning the <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> 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.</p>
  22 <p>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 <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> tests, it is recommended that the native ALSA implementation of <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> be used on systems which have ALSA drivers installed.</p>
  23 <p>The ALSA implementation of <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> makes no use of the ALSA "plug" interface. All necessary data format conversions, channel compensation, de-interleaving, and byte-swapping is handled by internal <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> routines.</p>
  24 <h1><a class="anchor" id="macosx"></a>
  25 Macintosh OS-X (CoreAudio and Jack):</h1>
  26 <p>The Apple CoreAudio API is designed to use a separate callback procedure for each of its audio devices. A single <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> duplex stream using two different devices is supported, though it cannot be guaranteed to always behave correctly because we cannot synchronize these two callbacks. The <em>numberOfBuffers</em> parameter to the <a class="el" href="classRtAudio.html#a6907539d2527775df778ebce32ef1e3b" title="A public function for opening a stream with the specified parameters.">RtAudio::openStream()</a> function has no affect in this implementation.</p>
  27 <p>It is not possible to have multiple instances of <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> accessing the same CoreAudio device.</p>
  28 <p>The <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> Jack support can be compiled on Macintosh OS-X systems, as well as in Linux.</p>
  29 <h1><a class="anchor" id="windowsds"></a>
  30 Windows (DirectSound):</h1>
  31 <p>The <code>configure</code> script provides support for the MinGW compiler. DirectSound support is specified with the "&amp;ndash;with-ds" flag.</p>
  32 <p>In order to compile <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> under Windows for the DirectSound API, 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. Audio output latency with DirectSound can be reasonably good, especially since <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> version 3.0.2. Input audio latency still tends to be bad but better since version 3.0.2. <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> was originally developed with Visual C++ version 6.0 but has been tested with .NET.</p>
  33 <p>The DirectSound version of <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> can be compiled with or without the UNICODE preprocessor definition.</p>
  34 <h1><a class="anchor" id="windowsasio"></a>
  35 Windows (ASIO):</h1>
  36 <p>ASIO support using MinGW and the <code>configure</code> script is specified with the "&amp;ndash;with-asio" flag.</p>
  37 <p>The Steinberg ASIO audio API allows only a single device driver to be loaded and accessed at a time. ASIO device drivers must be supplied by audio hardware manufacturers, though ASIO emulation is possible on top of systems with DirectSound drivers. The <em>numberOfBuffers</em> parameter to the <a class="el" href="classRtAudio.html#a6907539d2527775df778ebce32ef1e3b" title="A public function for opening a stream with the specified parameters.">RtAudio::openStream()</a> function has no affect in this implementation.</p>
  38 <p>A number of ASIO source and header files are required for use with <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a>. Specifically, an <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> project must include the following files: <code>asio.h,cpp; asiodrivers.h,cpp; asiolist.h,cpp; asiodrvr.h; asiosys.h; ginclude.h; iasiodrv.h; iasiothiscallresolver.h,cpp</code>. The Visual C++ projects found in <code>/tests/Windows/</code> compile both ASIO and DirectSound support.</p>
  39 <p>The Steinberg provided <code>asiolist</code> class does not compile when the preprocessor definition UNICODE is defined. Note that this could be an issue when using <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> with Qt, though Qt programs appear to compile without the UNICODE definition (try <code>DEFINES -= UNICODE</code> in your .pro file). <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> with ASIO support has been tested using the MinGW compiler under Windows XP, as well as in the Visual Studio environment. </p>
  40 </div></div><!-- contents -->
  41 <HR>
  42 <table><tr><td><img src="../images/mcgill.gif" width=165></td>
  43   <td>&copy;2001-2013 Gary P. Scavone, McGill University. All Rights Reserved.<br>Maintained by <a href="http://www.music.mcgill.ca/~gary/">Gary P. Scavone</a>.</td></tr>
  44 </table>
  45 </BODY>
  46 </HTML>