doc/html/settings.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.6.2 -->
  12 <div class="contents">
  13
  14
  15 <h1><a class="anchor" id="settings">Device Settings </a></h1><p>The next step in using <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> is to open a stream with particular device and parameter settings.</p>
  16 <div class="fragment"><pre class="fragment"><span class="preprocessor">#include &quot;<a class="code" href="RtAudio_8h.html">RtAudio.h</a>&quot;</span>
  17
  18 <span class="keywordtype">int</span> main()
  19 {
  20   <a class="code" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> dac;
  21   <span class="keywordflow">if</span> ( dac.<a class="code" href="classRtAudio.html#a747ce2d73803641bbb66d6e78092aa1a" title="A public function that queries for the number of audio devices available.">getDeviceCount</a>() == 0 ) exit( 0 );
  22
  23   <a class="code" href="structRtAudio_1_1StreamParameters.html" title="The structure for specifying input or ouput stream parameters.">RtAudio::StreamParameters</a> parameters;
  24   parameters.<a class="code" href="structRtAudio_1_1StreamParameters.html#ab3c72bcf3ef12149ae9a4fb597cc5489">deviceId</a> = dac.<a class="code" href="classRtAudio.html#a3a3f3dbe13ea696b521e49cdaaa357bc" title="A function that returns the index of the default output device.">getDefaultOutputDevice</a>();
  25   parameters.<a class="code" href="structRtAudio_1_1StreamParameters.html#a88a10091b6e284e21235cc6f25332ebd">nChannels</a> = 2;
  26   <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> sampleRate = 44100;
  27   <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> bufferFrames = 256; <span class="comment">// 256 sample frames</span>
  28
  29   <a class="code" href="structRtAudio_1_1StreamOptions.html" title="The structure for specifying stream options.">RtAudio::StreamOptions</a> options;
  30   options.<a class="code" href="structRtAudio_1_1StreamOptions.html#a0ecc98b031aa3af49d09b781643e298b">flags</a> = RTAUDIO_NONINTERLEAVED;
  31
  32   <span class="keywordflow">try</span> {
  33     dac.<a class="code" href="classRtAudio.html#afacc99740fa4c5606fb35467cdea6da8" title="A public function for opening a stream with the specified parameters.">openStream</a>( &amp;parameters, NULL, RTAUDIO_FLOAT32,
  34                     sampleRate, &amp;bufferFrames, &amp;myCallback, NULL, &amp;options );
  35   }
  36   <span class="keywordflow">catch</span> ( <a class="code" href="classRtError.html" title="Exception handling class for RtAudio &amp;amp; RtMidi.">RtError</a>&amp; e ) {
  37     std::cout &lt;&lt; <span class="charliteral">&#39;\n&#39;</span> &lt;&lt; e.<a class="code" href="classRtError.html#afd067ba6b46edd37f989cad02cd70b50" title="Returns the thrown error message string.">getMessage</a>() &lt;&lt; <span class="charliteral">&#39;\n&#39;</span> &lt;&lt; std::endl;
  38     exit( 0 );
  39   }
  40
  41   <span class="keywordflow">return</span> 0;
  42 }
  43 </pre></div><p>The <a class="el" href="classRtAudio.html#afacc99740fa4c5606fb35467cdea6da8" title="A public function for opening a stream with the specified parameters.">RtAudio::openStream()</a> function attempts to open a stream with a specified set of parameter values. In the above example, we attempt to open a two channel playback stream using the default output device, 32-bit floating point data, a sample rate of 44100 Hz, and a frame rate of 256 sample frames per output buffer. If the user specifies an invalid parameter value (such as a device id greater than or equal to the number of enumerated devices), an <a class="el" href="classRtError.html" title="Exception handling class for RtAudio &amp; RtMidi.">RtError</a> is thrown of type = INVALID_USE. If a system error occurs or the device does not support the specified parameter values, an <a class="el" href="classRtError.html" title="Exception handling class for RtAudio &amp; RtMidi.">RtError</a> of type = SYSTEM_ERROR is thrown. In either case, a descriptive error message is bundled with the exception and can be queried with the <a class="el" href="classRtError.html#afd067ba6b46edd37f989cad02cd70b50" title="Returns the thrown error message string.">RtError::getMessage()</a> or <a class="el" href="classRtError.html#aeb843b7a7785d66061c61ebfc29e7e9d" title="Returns the thrown error message as a c-style string.">RtError::what()</a> functions.</p>
  44 <p><a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> provides four signed integer and two floating point data formats which can be specified using the RtAudioFormat parameter values mentioned earlier. If the opened device does not natively support the given format, <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> will automatically perform the necessary data format conversion.</p>
  45 <p>The <code>bufferFrames</code> parameter specifies the desired number of sample frames that will be written to and/or read from a device per write/read operation. This parameter can be used to control stream latency though there is no guarantee that the passed value will be that used by a device. In general, a lower <code>bufferFrames</code> value will produce less latency but perhaps less robust performance. A value of zero can be specified, in which case the smallest allowable value will be used. The <code>bufferFrames</code> parameter is passed as a pointer and the actual value used by the stream is set during the device setup procedure. <code>bufferFrames</code> values should be a power of two. Optimal and allowable buffer values tend to vary between systems and devices. Stream latency can also be controlled via the optional <a class="el" href="structRtAudio_1_1StreamOptions.html" title="The structure for specifying stream options.">RtAudio::StreamOptions</a> member <code>numberOfBuffers</code> (not used in the example above), though this tends to be more system dependent. In particular, the <code>numberOfBuffers</code> parameter is ignored when using the OS-X Core Audio, Jack, and the Windows ASIO APIs.</p>
  46 <p>As noted earlier, the device capabilities reported by a driver or underlying audio API are not always accurate and/or may be dependent on a combination of device settings. Because of this, <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> does not attempt to query a device's capabilities or use previously reported values when opening a device. Instead, <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> simply attempts to set the given parameters on a specified device and then checks whether the setup is successful or not.</p>
  47 <p>The RtAudioCallback parameter above is a pointer to a user-defined function that will be called whenever the audio system is ready for new output data or has new input data to be read. Further details on the use of a callback function are provided in the next section.</p>
  48 <p>Several stream options are available to fine-tune the behavior of an audio stream. In the example above, we specify that data will be written by the user in a <em>non-interleaved</em> format via the <a class="el" href="structRtAudio_1_1StreamOptions.html" title="The structure for specifying stream options.">RtAudio::StreamOptions</a> member <code>flags</code>. That is, all <code>bufferFrames</code> of the first channel should be written consecutively, followed by all <code>bufferFrames</code> of the second channel. By default (when no option is specified), <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> expects data to be written in an <em>interleaved</em> format. </p>
  49 </div>
  50 <HR>
  51
  52 <table><tr><td><img src="../images/mcgill.gif" width=165></td>
  53   <td>&copy;2001-2010 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>
  54 </table>
  55
  56 </BODY>
  57 </HTML>