doc/html/probe.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.5.8 -->
  12 <div class="contents">
  13 <h1><a class="anchor" name="probe">Probing Device Capabilities </a></h1>A programmer may wish to query the available audio device capabilities before deciding which to use. The following example outlines how this can be done.<p>
  14 <div class="fragment"><pre class="fragment"><span class="comment">// audioprobe.cpp</span>
  15
  16 <span class="preprocessor">#include &lt;iostream&gt;</span>
  17 <span class="preprocessor">#include "<a class="code" href="RtAudio_8h.html">RtAudio.h</a>"</span>
  18
  19 <span class="keywordtype">int</span> main()
  20 {
  21   <a class="code" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> audio;
  22
  23   <span class="comment">// Determine the number of devices available</span>
  24   <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> devices = audio.<a class="code" href="classRtAudio.html#747ce2d73803641bbb66d6e78092aa1a" title="A public function that queries for the number of audio devices available.">getDeviceCount</a>();
  25
  26   <span class="comment">// Scan through devices for various capabilities</span>
  27   <a class="code" href="structRtAudio_1_1DeviceInfo.html" title="The public device information structure for returning queried values.">RtAudio::DeviceInfo</a> info;
  28   <span class="keywordflow">for</span> ( <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> i=1; i&lt;=devices; i++ ) {
  29
  30     info = audio.<a class="code" href="classRtAudio.html#02d7ff44ad1d7eae22283a052f3dfda8" title="Return an RtAudio::DeviceInfo structure for a specified device number.">getDeviceInfo</a>( i );
  31
  32     <span class="keywordflow">if</span> ( info.<a class="code" href="structRtAudio_1_1DeviceInfo.html#5bf008c629ef493c713ec870d0217407">probed</a> == <span class="keyword">true</span> ) {
  33       <span class="comment">// Print, for example, the maximum number of output channels for each device</span>
  34       std::cout &lt;&lt; <span class="stringliteral">"device = "</span> &lt;&lt; i;
  35       std::cout &lt;&lt; <span class="stringliteral">": maximum output channels = "</span> &lt;&lt; info.<a class="code" href="structRtAudio_1_1DeviceInfo.html#185f8aac1095de4fbb6e0076875d24c4">outputChannels</a> &lt;&lt; <span class="stringliteral">"\n"</span>;
  36     }
  37   }
  38
  39   <span class="keywordflow">return</span> 0;
  40 }
  41 </pre></div><p>
  42 The <a class="el" href="structRtAudio_1_1DeviceInfo.html" title="The public device information structure for returning queried values.">RtAudio::DeviceInfo</a> structure is defined in <a class="el" href="RtAudio_8h.html">RtAudio.h</a> and provides a variety of information useful in assessing the capabilities of a device:<p>
  43 <div class="fragment"><pre class="fragment">  <span class="keyword">typedef</span> <span class="keyword">struct </span><a class="code" href="structRtAudio_1_1DeviceInfo.html" title="The public device information structure for returning queried values.">RtAudio::DeviceInfo</a> {
  44     <span class="keywordtype">bool</span> <a class="code" href="structRtAudio_1_1DeviceInfo.html#5bf008c629ef493c713ec870d0217407">probed</a>;                           <span class="comment">// true if the device capabilities were successfully probed.</span>
  45     std::string <a class="code" href="structRtAudio_1_1DeviceInfo.html#a0e2ea10c52c206c9e105ac76b01f194">name</a>;                      <span class="comment">// Character string device identifier.</span>
  46     <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> <a class="code" href="structRtAudio_1_1DeviceInfo.html#185f8aac1095de4fbb6e0076875d24c4">outputChannels</a>;           <span class="comment">// Maximum output channels supported by device.</span>
  47     <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> <a class="code" href="structRtAudio_1_1DeviceInfo.html#731b31adf84c550ab98329be1baa58b4">inputChannels</a>;            <span class="comment">// Maximum input channels supported by device.</span>
  48     <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> <a class="code" href="structRtAudio_1_1DeviceInfo.html#ca6ecfb8b5b8c114c54809d8af50ee5b">duplexChannels</a>;           <span class="comment">// Maximum simultaneous input/output channels supported by device.</span>
  49     <span class="keywordtype">bool</span> <a class="code" href="structRtAudio_1_1DeviceInfo.html#af74fc23f451fdd22ed073a47f0db674">isDefaultOutput</a>;                  <span class="comment">// true if this is the default output device.</span>
  50     <span class="keywordtype">bool</span> <a class="code" href="structRtAudio_1_1DeviceInfo.html#a8b03618fa1d4c051f6add14bb031728">isDefaultInput</a>;                   <span class="comment">// true if this is the default input device.</span>
  51     std::vector&lt;unsigned int&gt; <a class="code" href="structRtAudio_1_1DeviceInfo.html#5b158efcbfbd30e7226df92d0109d475">sampleRates</a>; <span class="comment">// Supported sample rates.</span>
  52     <a class="code" href="RtAudio_8h.html#afca92882d25915560018873221e44b8" title="RtAudio data format type.">RtAudioFormat</a> <a class="code" href="structRtAudio_1_1DeviceInfo.html#97559ee4a1f2c8cfb765949e6193e1f4">nativeFormats</a>;           <span class="comment">// Bit mask of supported data formats.</span>
  53   };
  54 </pre></div><p>
  55 The following data formats are defined and fully supported by <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a>:<p>
  56 <div class="fragment"><pre class="fragment">  <span class="keyword">typedef</span> <span class="keywordtype">unsigned</span> <span class="keywordtype">long</span> <a class="code" href="RtAudio_8h.html#afca92882d25915560018873221e44b8" title="RtAudio data format type.">RtAudioFormat</a>;
  57   <span class="keyword">static</span> <span class="keyword">const</span> RtAudioFormat  RTAUDIO_SINT8;   <span class="comment">// Signed 8-bit integer</span>
  58   <span class="keyword">static</span> <span class="keyword">const</span> RtAudioFormat  RTAUDIO_SINT16;  <span class="comment">// Signed 16-bit integer</span>
  59   <span class="keyword">static</span> <span class="keyword">const</span> RtAudioFormat  RTAUDIO_SINT24;  <span class="comment">// Signed 24-bit integer (lower 3 bytes of 32-bit signed integer.)</span>
  60   <span class="keyword">static</span> <span class="keyword">const</span> RtAudioFormat  RTAUDIO_SINT32;  <span class="comment">// Signed 32-bit integer</span>
  61   <span class="keyword">static</span> <span class="keyword">const</span> RtAudioFormat  RTAUDIO_FLOAT32; <span class="comment">// 32-bit float normalized between +/- 1.0</span>
  62   <span class="keyword">static</span> <span class="keyword">const</span> RtAudioFormat  RTAUDIO_FLOAT64; <span class="comment">// 64-bit double normalized between +/- 1.0</span>
  63 </pre></div><p>
  64 The <code>nativeFormats</code> member of the <a class="el" href="structRtAudio_1_1DeviceInfo.html" title="The public device information structure for returning queried values.">RtAudio::DeviceInfo</a> structure is a bit mask of the above formats which are natively supported by the device. However, <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> will automatically provide format conversion if a particular format is not natively supported. When the <code>probed</code> member of the <a class="el" href="structRtAudio_1_1DeviceInfo.html" title="The public device information structure for returning queried values.">RtAudio::DeviceInfo</a> structure is false, the remaining structure members are undefined and the device is probably unusable.<p>
  65 Some audio devices may require a minimum channel value greater than one. <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> will provide automatic channel number compensation when the number of channels set by the user is less than that required by the device. Channel compensation is <em>NOT</em> possible when the number of channels set by the user is greater than that supported by the device.<p>
  66 It should be noted that the capabilities reported by a device driver or underlying audio API are not always accurate and/or may be dependent on a combination of device settings. For this reason, <a class="el" href="classRtAudio.html" title="Realtime audio i/o C++ classes.">RtAudio</a> does not rely on the queried values when attempting to open a stream. </div>
  67 <HR>
  68
  69 <table><tr><td><img src="../images/mcgill.gif" width=165></td>
  70   <td>&copy;2001-2009 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>
  71 </table>
  72
  73 </BODY>
  74 </HTML>