Sophie

Sophie

distrib > Mandriva > 2010.1 > x86_64 > media > main-release > by-pkgid > eebe3e0b47589a6371b9bc07addc51ff > files > 134

libalsa2-docs-1.0.23-2mdv2010.1.x86_64.rpm

<!-- This comment will put IE 6, 7 and 8 in quirks mode -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>ALSA project - the C library reference: PCM (digital audio) interface</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javaScript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body onload='searchBox.OnSelectItem(0);'>
<!-- Generated by Doxygen 1.6.3 -->
<script type="text/javascript"><!--
var searchBox = new SearchBox("searchBox", "search",false,'Search');
--></script>
<div class="navigation" id="top">
  <div class="tabs">
    <ul>
      <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
      <li class="current"><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Data&nbsp;Structures</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li><a href="examples.html"><span>Examples</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <img id="MSearchSelect" src="search/search.png"
             onmouseover="return searchBox.OnSearchSelectShow()"
             onmouseout="return searchBox.OnSearchSelectHide()"
             alt=""/>
        <input type="text" id="MSearchField" value="Search" accesskey="S"
             onfocus="searchBox.OnSearchFieldFocus(true)" 
             onblur="searchBox.OnSearchFieldFocus(false)" 
             onkeyup="searchBox.OnSearchFieldChange(event)"/>
        <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
        </div>
      </li>
    </ul>
  </div>
</div>
<div class="contents">


<h1><a class="anchor" id="pcm">PCM (digital audio) interface </a></h1><p>Although abbreviation PCM stands for Pulse Code Modulation, we are understanding it as general digital audio processing with volume samples generated in continuous time periods.</p>
<p>The analog signal is recorded via analog to digital converters (ADC). The digital value (de-facto a volume at a specific time) obtained from ADC can be further processed. The following picture shows a perfect sinus waveform:</p>
<p><br/>
 </p>
<div align="center">
<img src="wave1.gif" alt="wave1.gif"/>
</div>
<p>Next image shows digitized representation:</p>
<p><br/>
 </p>
<div align="center">
<img src="wave2.gif" alt="wave2.gif"/>
</div>
<p>As you may see, the quality of digital audio signal depends on the time (recording rate) and voltage resolution (usually in an linear integer representation with basic unit one bit).</p>
<p>The stored digital signal can be converted back to voltage (analog) representation via digital to analog converters (DAC).</p>
<p>One digital value is called sample. More samples are collected to frames (frame is terminology for ALSA) depending on count of converters used at one specific time. One frame might contain one sample (when only one converter is used - mono) or more samples (for example: stereo has signals from two converters recorded at same time). Digital audio stream contains collection of frames recorded at boundaries of continuous time periods.</p>
<h2><a class="anchor" id="pcm_general_overview">
General overview</a></h2>
<p>ALSA uses the ring buffer to store outgoing (playback) and incoming (capture, record) samples. There are two pointers being maintained to allow a precise communication between application and device pointing to current processed sample by hardware and last processed sample by application. The modern audio chips allow to program the transfer time periods. It means that the stream of samples is divided to small chunks. Device acknowledges to application when the transfer of a chunk is complete.</p>
<h2><a class="anchor" id="pcm_transfer">
Transfer methods in UNIX environments</a></h2>
<p>In the UNIX environment, data chunk acknowledges are received via standard I/O calls or event waiting routines (poll or select function). To accomplish this list, the asynchronous notification of acknowledges should be listed here. The ALSA implementation for these methods is described in the <a class="el" href="pcm.html#alsa_transfers">ALSA transfers</a> section.</p>
<h3><a class="anchor" id="pcm_transfer_io">
Standard I/O transfers</a></h3>
<p>The standard I/O transfers are using the read (see 'man 2 read') and write (see 'man 2 write') C functions. There are two basic behaviours of these functions - blocked and non-blocked (see the O_NONBLOCK flag for the standard C open function - see 'man 2 open'). In non-blocked behaviour, these I/O functions never stops, they return -EAGAIN error code, when no data can be transferred (the ring buffer is full in our case). In blocked behaviour, these I/O functions stop and wait until there is a room in the ring buffer (playback) or until there are a new samples (capture). The ALSA implementation can be found in the <a class="el" href="pcm.html#alsa_pcm_rw">Read / Write transfer</a> section.</p>
<h3><a class="anchor" id="pcm_transfer_event">
Event waiting routines</a></h3>
<p>The poll or select functions (see 'man 2 poll' or 'man 2 select' for further details) allows to receive requests/events from the device while an application is waiting on events from other sources (like keyboard, screen, network etc.), too. <a class="el" href="group___p_c_m.html#ga742e8705f6992fd0e36efc868e574f01">snd_pcm_poll_descriptors</a> can be used to get file descriptors to poll or select on (note that wait direction might be diferent than expected - do not use only returned file descriptors, but handle events member as well - see <a class="el" href="group___p_c_m.html#ga742e8705f6992fd0e36efc868e574f01">snd_pcm_poll_descriptors</a> function description for more details and <a class="el" href="group___p_c_m.html#ga7e561f305702c6f52dab49b6c84f7df7">snd_pcm_poll_descriptors_revents</a> for events demangling). The implemented transfer routines can be found in the <a class="el" href="pcm.html#alsa_transfers">ALSA transfers</a> section.</p>
<h3><a class="anchor" id="pcm_transfer_async">
Asynchronous notification</a></h3>
<p>ALSA driver and library knows to handle the asynchronous notifications over the SIGIO signal. This signal allows to interrupt application and transfer data in the signal handler. For further details see the sigaction function ('man 2 sigaction'). The section <a class="el" href="pcm.html#pcm_async">Asynchronous mode</a> describes the ALSA API for this extension. The implemented transfer routines can be found in the <a class="el" href="pcm.html#alsa_transfers">ALSA transfers</a> section.</p>
<h2><a class="anchor" id="pcm_open_behaviour">
Blocked and non-blocked open</a></h2>
<p>The ALSA PCM API uses a different behaviour when the device is opened with blocked or non-blocked mode. The mode can be specified with <em>mode</em> argument in <a class="el" href="group___p_c_m.html#ga8340c7dc0ac37f37afe5e7c21d6c528b" title="Opens a PCM.">snd_pcm_open()</a> function. The blocked mode is the default (without <a class="el" href="group___p_c_m.html#ga6bd90de1d1527b5804090dcce51079ad">SND_PCM_NONBLOCK</a> mode). In this mode, the behaviour is that if the resources have already used with another application, then it blocks the caller, until resources are free. The non-blocked behaviour (with <a class="el" href="group___p_c_m.html#ga6bd90de1d1527b5804090dcce51079ad">SND_PCM_NONBLOCK</a>) doesn't block the caller in any way and returns -EBUSY error when the resources are not available. Note that the mode also determines the behaviour of standard I/O calls, returning -EAGAIN when non-blocked mode is used and the ring buffer is full (playback) or empty (capture). The operation mode for I/O calls can be changed later with the <a class="el" href="group___p_c_m.html#ga8d9ed4a62c17402de0389fd31fc7dc1f" title="set nonblock mode">snd_pcm_nonblock()</a> function.</p>
<h2><a class="anchor" id="pcm_async">
Asynchronous mode</a></h2>
<p>There is also possibility to receive asynchronous notification after specified time periods. You may see the <a class="el" href="group___p_c_m.html#ga9b22351abf6c85ced128e2088f6f6a5c">SND_PCM_ASYNC</a> mode for <a class="el" href="group___p_c_m.html#ga8340c7dc0ac37f37afe5e7c21d6c528b" title="Opens a PCM.">snd_pcm_open()</a> function and <a class="el" href="group___p_c_m.html#ga5a0c0da6d0d35a3ac9f6a97567ac3b63" title="Add an async handler for a PCM.">snd_async_add_pcm_handler()</a> function for further details.</p>
<h2><a class="anchor" id="pcm_handshake">
Handshake between application and library</a></h2>
<p>The ALSA PCM API design uses the states to determine the communication phase between application and library. The actual state can be determined using <a class="el" href="group___p_c_m.html#ga87896f6f17020fc19835790369e7ce75" title="Return PCM state.">snd_pcm_state()</a> call. There are these states:</p>
<dl class="user"><dt><b>SND_PCM_STATE_OPEN</b></dt><dd>The PCM device is in the open state. After the <a class="el" href="group___p_c_m.html#ga8340c7dc0ac37f37afe5e7c21d6c528b" title="Opens a PCM.">snd_pcm_open()</a> open call, the device is in this state. Also, when <a class="el" href="group___p_c_m.html#ga1ca0dc120a484965e26cabf966502330" title="Install one PCM hardware configuration chosen from a configuration space and snd_pcm_prepare...">snd_pcm_hw_params()</a> call fails, then this state is entered to force application calling <a class="el" href="group___p_c_m.html#ga1ca0dc120a484965e26cabf966502330" title="Install one PCM hardware configuration chosen from a configuration space and snd_pcm_prepare...">snd_pcm_hw_params()</a> function to set right communication parameters.</dd></dl>
<dl class="user"><dt><b>SND_PCM_STATE_SETUP</b></dt><dd>The PCM device has accepted communication parameters and it is waiting for <a class="el" href="group___p_c_m.html#ga788d05de75f2d536f8443cb0306754d0" title="Prepare PCM for use.">snd_pcm_prepare()</a> call to prepare the hardware for selected operation (playback or capture).</dd></dl>
<dl class="user"><dt><b>SND_PCM_STATE_PREPARE</b></dt><dd>The PCM device is prepared for operation. Application can use <a class="el" href="group___p_c_m.html#ga6bdb88b68a9d9e66015d770f600c6aea" title="Start a PCM.">snd_pcm_start()</a> call, write or read data to start the operation.</dd></dl>
<dl class="user"><dt><b>SND_PCM_STATE_RUNNING</b></dt><dd>The PCM device has been started and is running. It processes the samples. The stream can be stopped using the <a class="el" href="group___p_c_m.html#ga7000ca6010a1a2739daddff8e2fbb440" title="Stop a PCM dropping pending frames.">snd_pcm_drop()</a> or <a class="el" href="group___p_c_m.html#ga49afc5b8527f30c33fafa476533c9f86" title="Stop a PCM preserving pending frames.">snd_pcm_drain()</a> calls.</dd></dl>
<dl class="user"><dt><b>SND_PCM_STATE_XRUN</b></dt><dd>The PCM device reached overrun (capture) or underrun (playback). You can use the -EPIPE return code from I/O functions (<a class="el" href="group___p_c_m.html#gabc748a500743713eafa960c7d104ca6f" title="Write interleaved frames to a PCM.">snd_pcm_writei()</a>, <a class="el" href="group___p_c_m.html#gae599772ce3d0aa6a70de143abcf145e7" title="Write non interleaved frames to a PCM.">snd_pcm_writen()</a>, <a class="el" href="group___p_c_m.html#ga4c2c7bd26cf221268d59dc3bbeb9c048" title="Read interleaved frames from a PCM.">snd_pcm_readi()</a>, <a class="el" href="group___p_c_m.html#gafea175455f1a405f633a43484ded3d8a" title="Read non interleaved frames to a PCM.">snd_pcm_readn()</a>) to determine this state without checking the actual state via <a class="el" href="group___p_c_m.html#ga87896f6f17020fc19835790369e7ce75" title="Return PCM state.">snd_pcm_state()</a> call. It is recommended to use the helper function <a class="el" href="group___p_c_m.html#ga2157aaeb6fc14da3f040d76591f9d3b1" title="Recover the stream state from an error or suspend.">snd_pcm_recover()</a> to recover from this state, but you can also use <a class="el" href="group___p_c_m.html#ga788d05de75f2d536f8443cb0306754d0" title="Prepare PCM for use.">snd_pcm_prepare()</a>, <a class="el" href="group___p_c_m.html#ga7000ca6010a1a2739daddff8e2fbb440" title="Stop a PCM dropping pending frames.">snd_pcm_drop()</a> or <a class="el" href="group___p_c_m.html#ga49afc5b8527f30c33fafa476533c9f86" title="Stop a PCM preserving pending frames.">snd_pcm_drain()</a> calls.</dd></dl>
<dl class="user"><dt><b>SND_PCM_STATE_DRAINING</b></dt><dd>The device is in this state when application using the capture mode called <a class="el" href="group___p_c_m.html#ga49afc5b8527f30c33fafa476533c9f86" title="Stop a PCM preserving pending frames.">snd_pcm_drain()</a> function. Until all data are read from the internal ring buffer using I/O routines (<a class="el" href="group___p_c_m.html#ga4c2c7bd26cf221268d59dc3bbeb9c048" title="Read interleaved frames from a PCM.">snd_pcm_readi()</a>, <a class="el" href="group___p_c_m.html#gafea175455f1a405f633a43484ded3d8a" title="Read non interleaved frames to a PCM.">snd_pcm_readn()</a>), then the device stays in this state.</dd></dl>
<dl class="user"><dt><b>SND_PCM_STATE_PAUSED</b></dt><dd>The device is in this state when application called the <a class="el" href="group___p_c_m.html#gad711b582c7066bd4fffa1d08a04316b5" title="Pause/resume PCM.">snd_pcm_pause()</a> function until the pause is released. Not all hardware supports this feature. Application should check the capability with the <a class="el" href="group___p_c_m___h_w___params.html#gaad4ba98b2f66baa5360b9a85f064a3e9" title="Check, if hardware supports pause.">snd_pcm_hw_params_can_pause()</a>.</dd></dl>
<dl class="user"><dt><b>SND_PCM_STATE_SUSPENDED</b></dt><dd>The device is in the suspend state provoked with the power management system. The stream can be resumed using <a class="el" href="group___p_c_m.html#ga13083ce2209aab9ea73831610bc61ab1" title="Resume from suspend, no samples are lost.">snd_pcm_resume()</a> call, but not all hardware supports this feature. Application should check the capability with the <a class="el" href="group___p_c_m___h_w___params.html#ga6b79539a34e6f51972f4c32b3296585a" title="Check, if hardware supports resume.">snd_pcm_hw_params_can_resume()</a>. In other case, the calls <a class="el" href="group___p_c_m.html#ga788d05de75f2d536f8443cb0306754d0" title="Prepare PCM for use.">snd_pcm_prepare()</a>, <a class="el" href="group___p_c_m.html#ga7000ca6010a1a2739daddff8e2fbb440" title="Stop a PCM dropping pending frames.">snd_pcm_drop()</a>, <a class="el" href="group___p_c_m.html#ga49afc5b8527f30c33fafa476533c9f86" title="Stop a PCM preserving pending frames.">snd_pcm_drain()</a> can be used to leave this state.</dd></dl>
<dl class="user"><dt><b>SND_PCM_STATE_DISCONNECTED</b></dt><dd>The device is physicaly disconnected. It does not accept any I/O calls in this state.</dd></dl>
<h2><a class="anchor" id="pcm_formats">
PCM formats</a></h2>
<p>The full list of formats present the <a class="el" href="group___p_c_m.html#gaa14b7f26877a812acbb39811364177f8">snd_pcm_format_t</a> type. The 24-bit linear samples uses 32-bit physical space, but the sample is stored in low three bits. Some hardware does not support processing of full range, thus you may get the significant bits for linear samples via <a class="el" href="group___p_c_m___h_w___params.html#ga8bb1180b62a4225f0e094b95ac5d3674" title="Get sample resolution info from a configuration space.">snd_pcm_hw_params_get_sbits()</a> function. The example: ICE1712 chips support 32-bit sample processing, but low byte is ignored (playback) or zero (capture). The function <a class="el" href="group___p_c_m___h_w___params.html#ga8bb1180b62a4225f0e094b95ac5d3674" title="Get sample resolution info from a configuration space.">snd_pcm_hw_params_get_sbits()</a> returns 24 in the case.</p>
<h2><a class="anchor" id="alsa_transfers">
ALSA transfers</a></h2>
<p>There are two methods to transfer samples in application. The first method is the standard read / write one. The second method, uses the direct audio buffer to communicate with the device while ALSA library manages this space itself. You can find examples of all communication schemes for playback in <a class="el" href="pcm.html#example_test_pcm">Sine-wave generator example</a>. To complete the list, we should note that <a class="el" href="group___p_c_m.html#gad4d53d58b996a7cd9a5cbf1710b90375" title="Wait for a PCM to become ready.">snd_pcm_wait()</a> function contains embedded poll waiting implementation.</p>
<h3><a class="anchor" id="alsa_pcm_rw">
Read / Write transfer</a></h3>
<p>There are two versions of read / write routines. The first expects the interleaved samples at input (<a class="el" href="group___p_c_m.html#gga661221ba5e8f1d6eaf4ab8e2da57cc1aa72a970ed6e676ab0fd9f3c3d36737e0a">SND_PCM_ACCESS_RW_INTERLEAVED</a> access method), and the second one expects non-interleaved (samples in separated buffers - <a class="el" href="group___p_c_m.html#gga661221ba5e8f1d6eaf4ab8e2da57cc1aae7ab128d10c32667f396933190435071">SND_PCM_ACCESS_RW_NONINTERLEAVED</a> access method) at input. There are these functions for interleaved transfers: <a class="el" href="group___p_c_m.html#gabc748a500743713eafa960c7d104ca6f" title="Write interleaved frames to a PCM.">snd_pcm_writei()</a> <a class="el" href="group___p_c_m.html#ga4c2c7bd26cf221268d59dc3bbeb9c048" title="Read interleaved frames from a PCM.">snd_pcm_readi()</a>. For non-interleaved transfers, there are these functions: <a class="el" href="group___p_c_m.html#gae599772ce3d0aa6a70de143abcf145e7" title="Write non interleaved frames to a PCM.">snd_pcm_writen()</a> and <a class="el" href="group___p_c_m.html#gafea175455f1a405f633a43484ded3d8a" title="Read non interleaved frames to a PCM.">snd_pcm_readn()</a>.</p>
<h3><a class="anchor" id="alsa_mmap_rw">
Direct Read / Write transfer (via mmap'ed areas)</a></h3>
<p>Three kinds of organization of ring buffer memory areas exist in ALSA API. Access <a class="el" href="group___p_c_m.html#gga661221ba5e8f1d6eaf4ab8e2da57cc1aa90a5dea527c5ae9a53f1448beb2dee6f">SND_PCM_ACCESS_MMAP_INTERLEAVED</a> has interleaved samples. Access <a class="el" href="group___p_c_m.html#gga661221ba5e8f1d6eaf4ab8e2da57cc1aa7de225785e05dd1d538203c5ece9036e">SND_PCM_ACCESS_MMAP_NONINTERLEAVED</a> expects continous sample areas for one channel. Access <a class="el" href="group___p_c_m.html#gga661221ba5e8f1d6eaf4ab8e2da57cc1aa26a4f161364cb539df4de5eeb9949121">SND_PCM_ACCESS_MMAP_COMPLEX</a> does not fit to interleaved and non-interleaved ring buffer organization.</p>
<p>There are two functions for this kind of transfer. Application can get an access to memory areas via <a class="el" href="group___p_c_m___direct.html#ga6d4acf42de554d4d1177fb035d484ea4" title="Application request to access a portion of direct (mmap) area.">snd_pcm_mmap_begin()</a> function. This function returns the areas (single area is equal to a channel) containing the direct pointers to memory and sample position description in <a class="el" href="structsnd__pcm__channel__area__t.html">snd_pcm_channel_area_t</a> structure. After application transfers the data in the memory areas, then it must be acknowledged the end of transfer via <a class="el" href="group___p_c_m___direct.html#gac306bd13c305825aa39dd9180a3ad520" title="Application has completed the access to area requested with snd_pcm_mmap_begin.">snd_pcm_mmap_commit()</a> function to allow the ALSA library update the pointers to ring buffer. This kind of communication is also called "zero-copy", because the device does not require to copy the samples from application to another place in system memory.</p>
<p>If you like to use the compatibility functions in mmap mode, there are read / write routines equaling to standard read / write transfers. Using these functions discards the benefits of direct access to memory region. See the <a class="el" href="group___p_c_m___direct.html#ga24b6c538c8d7ddd0776ee65f8fb909eb" title="Read interleaved frames from a PCM using direct buffer (mmap).">snd_pcm_mmap_readi()</a>, <a class="el" href="group___p_c_m.html#gabc748a500743713eafa960c7d104ca6f" title="Write interleaved frames to a PCM.">snd_pcm_writei()</a>, <a class="el" href="group___p_c_m.html#gafea175455f1a405f633a43484ded3d8a" title="Read non interleaved frames to a PCM.">snd_pcm_readn()</a> and <a class="el" href="group___p_c_m.html#gae599772ce3d0aa6a70de143abcf145e7" title="Write non interleaved frames to a PCM.">snd_pcm_writen()</a> functions.</p>
<h2><a class="anchor" id="pcm_errors">
Error codes</a></h2>
<dl class="user"><dt><b>-EPIPE</b></dt><dd></dd></dl>
<p>This error means xrun (underrun for playback or overrun for capture). The underrun can happen when an application does not feed new samples in time to alsa-lib (due CPU usage). The overrun can happen when an application does not take new captured samples in time from alsa-lib.</p>
<dl class="user"><dt><b>-ESTRPIPE</b></dt><dd></dd></dl>
<p>This error means that system has suspended drivers. The application should wait in loop when <a class="el" href="group___p_c_m.html#ga13083ce2209aab9ea73831610bc61ab1" title="Resume from suspend, no samples are lost.">snd_pcm_resume()</a> != -EAGAIN and then call <a class="el" href="group___p_c_m.html#ga788d05de75f2d536f8443cb0306754d0" title="Prepare PCM for use.">snd_pcm_prepare()</a> when <a class="el" href="group___p_c_m.html#ga13083ce2209aab9ea73831610bc61ab1" title="Resume from suspend, no samples are lost.">snd_pcm_resume()</a> return an error code. If <a class="el" href="group___p_c_m.html#ga13083ce2209aab9ea73831610bc61ab1" title="Resume from suspend, no samples are lost.">snd_pcm_resume()</a> does not fail (a zero value is returned), driver supports resume and the <a class="el" href="group___p_c_m.html#ga788d05de75f2d536f8443cb0306754d0" title="Prepare PCM for use.">snd_pcm_prepare()</a> call can be ommited.</p>
<dl class="user"><dt><b>-EBADFD</b></dt><dd></dd></dl>
<p>This error means that the device is in a bad state. It means that the handskahe between application and alsa-lib is corrupted.</p>
<dl class="user"><dt><b>-ENOTTY, -ENODEV</b></dt><dd></dd></dl>
<p>This error can happen when device is physically removed (for example some hotplug devices like USB or PCMCIA, CardBus or ExpressCard can be removed on the fly).</p>
<h2><a class="anchor" id="pcm_params">
Managing parameters</a></h2>
<p>The ALSA PCM device uses two groups of PCM related parameters. The hardware parameters contains the stream description like format, rate, count of channels, ring buffer size etc. The software parameters contains the software (driver) related parameters. The communication behaviour can be controlled via these parameters, like automatic start, automatic stop, interrupting (chunk acknowledge) etc. The software parameters can be modified at any time (when valid hardware parameters are set). It includes the running state as well.</p>
<h3><a class="anchor" id="pcm_hw_params">
Hardware related parameters</a></h3>
<p>The ALSA PCM devices use the parameter refining system for hardware parameters - <a class="el" href="group___p_c_m.html#ga65c737127994f0a980edad744e36dc40">snd_pcm_hw_params_t</a>. It means, that application choose the full-range of configurations at first and then application sets single parameters until all parameters are elementary (definite).</p>
<dl class="user"><dt><b>Access modes</b></dt><dd></dd></dl>
<p>ALSA knows about five access modes. The first three can be used for direct communication. The access mode <a class="el" href="group___p_c_m.html#gga661221ba5e8f1d6eaf4ab8e2da57cc1aa90a5dea527c5ae9a53f1448beb2dee6f">SND_PCM_ACCESS_MMAP_INTERLEAVED</a> determines the direct memory area and interleaved sample organization. Interleaved organization means, that samples from channels are mixed together. The access mode <a class="el" href="group___p_c_m.html#gga661221ba5e8f1d6eaf4ab8e2da57cc1aa7de225785e05dd1d538203c5ece9036e">SND_PCM_ACCESS_MMAP_NONINTERLEAVED</a> determines the direct memory area and non-interleaved sample organization. Each channel has a separate buffer in the case. The complex direct memory organization represents the <a class="el" href="group___p_c_m.html#gga661221ba5e8f1d6eaf4ab8e2da57cc1aa26a4f161364cb539df4de5eeb9949121">SND_PCM_ACCESS_MMAP_COMPLEX</a> access mode. The sample organization does not fit the interleaved or non-interleaved access modes in the case. The last two access modes describes the read / write access methods. The <a class="el" href="group___p_c_m.html#gga661221ba5e8f1d6eaf4ab8e2da57cc1aa72a970ed6e676ab0fd9f3c3d36737e0a">SND_PCM_ACCESS_RW_INTERLEAVED</a> access represents the read / write interleaved access and the <a class="el" href="group___p_c_m.html#gga661221ba5e8f1d6eaf4ab8e2da57cc1aae7ab128d10c32667f396933190435071">SND_PCM_ACCESS_RW_NONINTERLEAVED</a> represents the non-interleaved access.</p>
<dl class="user"><dt><b>Formats</b></dt><dd></dd></dl>
<p>The full list of formats is available in <a class="el" href="group___p_c_m.html#gaa14b7f26877a812acbb39811364177f8">snd_pcm_format_t</a> enumeration.</p>
<h3><a class="anchor" id="pcm_sw_params">
Software related parameters</a></h3>
<p>These parameters - <a class="el" href="group___p_c_m.html#ga7e082d9ea701709270b0674a0be23b09">snd_pcm_sw_params_t</a> can be modified at any time including the running state.</p>
<dl class="user"><dt><b>Minimum available count of samples</b></dt><dd></dd></dl>
<p>This parameter controls the wakeup point. If the count of available samples is equal or greater than this value, then application will be activated.</p>
<dl class="user"><dt><b>Timestamp mode</b></dt><dd></dd></dl>
<p>The timestamp mode specifies, if timestamps are activated. Currently, only <a class="el" href="group___p_c_m.html#gga695a9755880cf886c13d07938f92ea77af49a1c378583854b22ed6f6490f3b1ee">SND_PCM_TSTAMP_NONE</a> and <a class="el" href="group___p_c_m.html#gga695a9755880cf886c13d07938f92ea77ab09196ab367636c4d365b5b6bcd391d8">SND_PCM_TSTAMP_MMAP</a> modes are known. The mmap mode means that timestamp is taken on every period time boundary. Corresponding position in the ring buffer assigned to timestamp can be obtained using <a class="el" href="group___p_c_m.html#ga3946abd34178b3de60fd5329b71c189b" title="Obtain last position update hi-res timestamp.">snd_pcm_htimestamp()</a> function.</p>
<dl class="user"><dt><b>Transfer align</b></dt><dd></dd></dl>
<p>The read / write transfers can be aligned to this sample count. The modulo is ignored by device. Usually, this value is set to one (no align).</p>
<dl class="user"><dt><b>Start threshold</b></dt><dd></dd></dl>
<p>The start threshold parameter is used to determine the start point in stream. For playback, if samples in ring buffer is equal or greater than the start threshold parameters and the stream is not running, the stream will be started automatically from the device. For capture, if the application wants to read count of samples equal or greater then the stream will be started. If you want to use explicit start (<a class="el" href="group___p_c_m.html#ga6bdb88b68a9d9e66015d770f600c6aea" title="Start a PCM.">snd_pcm_start</a>), you can set this value greater than ring buffer size (in samples), but use the constant MAXINT is not a bad idea.</p>
<dl class="user"><dt><b>Stop threshold</b></dt><dd></dd></dl>
<p>Similarly, the stop threshold parameter is used to automatically stop the running stream, when the available samples crosses this boundary. It means, for playback, the empty samples in ring buffer and for capture, the filled (used) samples in ring buffer.</p>
<dl class="user"><dt><b>Silence threshold</b></dt><dd></dd></dl>
<p>The silence threshold specifies count of samples filled with silence ahead of the current application pointer for playback. It is usable for applications when an overrun is possible (like tasks depending on network I/O etc.). If application wants to manage the ahead samples itself, the <a class="el" href="group___p_c_m.html#ga6c66040dbe01797379436fdf36268fec" title="Move application frame position backward.">snd_pcm_rewind()</a> function allows to forget the last samples in the stream.</p>
<h2><a class="anchor" id="pcm_status">
Obtaining stream status</a></h2>
<p>The stream status is stored in <a class="el" href="group___p_c_m.html#ga902b87281c46910b469d5f7aaafc1890">snd_pcm_status_t</a> structure. These parameters can be obtained: the current stream state - <a class="el" href="group___p_c_m___status.html#gabaae998f0d374c50195b3206d1e43659" title="Get state from a PCM status container (see snd_pcm_state).">snd_pcm_status_get_state()</a>, timestamp of trigger - <a class="el" href="group___p_c_m___status.html#ga5eaeff98814e96c2ffd5f04c95b22c8d" title="Get trigger timestamp from a PCM status container.">snd_pcm_status_get_trigger_tstamp()</a>, timestamp of last pointer update <a class="el" href="group___p_c_m___status.html#gaea54e0a110afa01dd42071a1ca43902e" title="Get &quot;now&quot; timestamp from a PCM status container.">snd_pcm_status_get_tstamp()</a>, delay in samples - <a class="el" href="group___p_c_m___status.html#ga1fdce3985e64f66385a5805da1110f18" title="Get delay from a PCM status container (see snd_pcm_delay).">snd_pcm_status_get_delay()</a>, available count in samples - <a class="el" href="group___p_c_m___status.html#ga91c110525060b925ad4f0c21c205b757" title="Get number of frames available from a PCM status container (see snd_pcm_avail_update)...">snd_pcm_status_get_avail()</a>, maximum available samples - <a class="el" href="group___p_c_m___status.html#gac58d13e4d03c9420c57428ddffd94964" title="Get maximum number of frames available from a PCM status container after last snd_pcm_status...">snd_pcm_status_get_avail_max()</a>, ADC over-range count in samples - <a class="el" href="group___p_c_m___status.html#ga3f4bfd0a0327529abaa621b248b6b1aa" title="Get count of ADC overrange detections since last call.">snd_pcm_status_get_overrange()</a>. The last two parameters - avail_max and overrange are reset to zero after the status call.</p>
<h3><a class="anchor" id="pcm_status_fast">
Obtaining stream state fast and update r/w pointer</a></h3>
<p>The function <a class="el" href="group___p_c_m.html#ga8bb836bd0c414b59789d51a5f5379c08" title="Return number of frames ready to be read (capture) / written (playback).">snd_pcm_avail_update()</a> updates the current available count of samples for writing (playback) or filled samples for reading (capture). This call is mandatory for updating actual r/w pointer. Using standalone, it is a light method to obtain current stream position, because it does not require the user &lt;-&gt; kernel context switch, but the value is less accurate, because ring buffer pointers are updated in kernel drivers only when an interrupt occurs. If you want to get accurate stream state, use functions <a class="el" href="group___p_c_m.html#ga577b4d51e08d94930a05bbe73291ed2a" title="Return number of frames ready to be read (capture) / written (playback).">snd_pcm_avail()</a>, <a class="el" href="group___p_c_m.html#ga012e8b999070e72ab23514f25e7d6482" title="Obtain delay for a running PCM handle.">snd_pcm_delay()</a> or <a class="el" href="group___p_c_m.html#ga170bc44da2607b5583cff5ab5a985d98" title="Combine snd_pcm_avail and snd_pcm_delay functions.">snd_pcm_avail_delay()</a>.  </p>
<p>The function <a class="el" href="group___p_c_m.html#ga577b4d51e08d94930a05bbe73291ed2a" title="Return number of frames ready to be read (capture) / written (playback).">snd_pcm_avail()</a> reads the current hardware pointer in the ring buffer from hardware and calls <a class="el" href="group___p_c_m.html#ga8bb836bd0c414b59789d51a5f5379c08" title="Return number of frames ready to be read (capture) / written (playback).">snd_pcm_avail_update()</a> then.  </p>
<p>The function <a class="el" href="group___p_c_m.html#ga012e8b999070e72ab23514f25e7d6482" title="Obtain delay for a running PCM handle.">snd_pcm_delay()</a> returns the delay in samples. For playback, it means count of samples in the ring buffer before the next sample will be sent to DAC. For capture, it means count of samples in the ring buffer before the next sample will be captured from ADC. It works only when the stream is in the running or draining (playback only) state. Note that this function does not update the current r/w pointer for applications, so the function <a class="el" href="group___p_c_m.html#ga8bb836bd0c414b59789d51a5f5379c08" title="Return number of frames ready to be read (capture) / written (playback).">snd_pcm_avail_update()</a> must be called afterwards before any read/write begin+commit operations.  </p>
<p>The function <a class="el" href="group___p_c_m.html#ga170bc44da2607b5583cff5ab5a985d98" title="Combine snd_pcm_avail and snd_pcm_delay functions.">snd_pcm_avail_delay()</a> combines <a class="el" href="group___p_c_m.html#ga577b4d51e08d94930a05bbe73291ed2a" title="Return number of frames ready to be read (capture) / written (playback).">snd_pcm_avail()</a> and <a class="el" href="group___p_c_m.html#ga012e8b999070e72ab23514f25e7d6482" title="Obtain delay for a running PCM handle.">snd_pcm_delay()</a> and returns both values in sync. </p>
<h2><a class="anchor" id="pcm_action">
Managing the stream state</a></h2>
<p>The following functions directly and indirectly affect the stream state:</p>
<dl class="user"><dt><b>snd_pcm_hw_params</b></dt><dd>The <a class="el" href="group___p_c_m.html#ga1ca0dc120a484965e26cabf966502330" title="Install one PCM hardware configuration chosen from a configuration space and snd_pcm_prepare...">snd_pcm_hw_params()</a> function brings the stream state to <a class="el" href="group___p_c_m.html#gga61ac499cb3701ce536d4d83725908860a58d9a0501aa1b2bd2607e1084c335672">SND_PCM_STATE_SETUP</a> if successfully finishes, otherwise the state <a class="el" href="group___p_c_m.html#gga61ac499cb3701ce536d4d83725908860a56cf8033b50561b57437232e243f3007">SND_PCM_STATE_OPEN</a> is entered. When it is brought to SETUP state, this function automatically calls <a class="el" href="group___p_c_m.html#ga788d05de75f2d536f8443cb0306754d0" title="Prepare PCM for use.">snd_pcm_prepare()</a> function to bring to the PREPARE state as below.</dd></dl>
<dl class="user"><dt><b>snd_pcm_prepare</b></dt><dd>The <a class="el" href="group___p_c_m.html#ga788d05de75f2d536f8443cb0306754d0" title="Prepare PCM for use.">snd_pcm_prepare()</a> function enters from <a class="el" href="group___p_c_m.html#gga61ac499cb3701ce536d4d83725908860a58d9a0501aa1b2bd2607e1084c335672">SND_PCM_STATE_SETUP</a> to the <a class="el" href="group___p_c_m.html#gga61ac499cb3701ce536d4d83725908860a3eb4a3b75c7d2adb22f1829f3f738b27">SND_PCM_STATE_PREPARED</a> after a successful finish.</dd></dl>
<dl class="user"><dt><b>snd_pcm_start</b></dt><dd>The <a class="el" href="group___p_c_m.html#ga6bdb88b68a9d9e66015d770f600c6aea" title="Start a PCM.">snd_pcm_start()</a> function enters the <a class="el" href="group___p_c_m.html#gga61ac499cb3701ce536d4d83725908860a86f6fbc796881f19fde0e1957f878147">SND_PCM_STATE_RUNNING</a> after a successful finish.</dd></dl>
<dl class="user"><dt><b>snd_pcm_drop</b></dt><dd>The <a class="el" href="group___p_c_m.html#ga7000ca6010a1a2739daddff8e2fbb440" title="Stop a PCM dropping pending frames.">snd_pcm_drop()</a> function enters the <a class="el" href="group___p_c_m.html#gga61ac499cb3701ce536d4d83725908860a58d9a0501aa1b2bd2607e1084c335672">SND_PCM_STATE_SETUP</a> state.</dd></dl>
<dl class="user"><dt><b>snd_pcm_drain</b></dt><dd>The <a class="el" href="group___p_c_m.html#ga49afc5b8527f30c33fafa476533c9f86" title="Stop a PCM preserving pending frames.">snd_pcm_drain()</a> function enters the <a class="el" href="group___p_c_m.html#gga61ac499cb3701ce536d4d83725908860a86f88c2a4c8eedb5c91f3b6cb4879cfe">SND_PCM_STATE_DRAINING</a>, if the capture device has some samples in the ring buffer otherwise <a class="el" href="group___p_c_m.html#gga61ac499cb3701ce536d4d83725908860a58d9a0501aa1b2bd2607e1084c335672">SND_PCM_STATE_SETUP</a> state is entered.</dd></dl>
<dl class="user"><dt><b>snd_pcm_pause</b></dt><dd>The <a class="el" href="group___p_c_m.html#gad711b582c7066bd4fffa1d08a04316b5" title="Pause/resume PCM.">snd_pcm_pause()</a> function enters the <a class="el" href="group___p_c_m.html#gga61ac499cb3701ce536d4d83725908860a9fa0c5b43e5c924f87b50e22878a8952">SND_PCM_STATE_PAUSED</a> or <a class="el" href="group___p_c_m.html#gga61ac499cb3701ce536d4d83725908860a86f6fbc796881f19fde0e1957f878147">SND_PCM_STATE_RUNNING</a>.</dd></dl>
<dl class="user"><dt><b>snd_pcm_writei, snd_pcm_writen</b></dt><dd>The <a class="el" href="group___p_c_m.html#gabc748a500743713eafa960c7d104ca6f" title="Write interleaved frames to a PCM.">snd_pcm_writei()</a> and <a class="el" href="group___p_c_m.html#gae599772ce3d0aa6a70de143abcf145e7" title="Write non interleaved frames to a PCM.">snd_pcm_writen()</a> functions can conditionally start the stream - <a class="el" href="group___p_c_m.html#gga61ac499cb3701ce536d4d83725908860a86f6fbc796881f19fde0e1957f878147">SND_PCM_STATE_RUNNING</a>. They depend on the start threshold software parameter.</dd></dl>
<dl class="user"><dt><b>snd_pcm_readi, snd_pcm_readn</b></dt><dd>The <a class="el" href="group___p_c_m.html#ga4c2c7bd26cf221268d59dc3bbeb9c048" title="Read interleaved frames from a PCM.">snd_pcm_readi()</a> and <a class="el" href="group___p_c_m.html#gafea175455f1a405f633a43484ded3d8a" title="Read non interleaved frames to a PCM.">snd_pcm_readn()</a> functions can conditionally start the stream - <a class="el" href="group___p_c_m.html#gga61ac499cb3701ce536d4d83725908860a86f6fbc796881f19fde0e1957f878147">SND_PCM_STATE_RUNNING</a>. They depend on the start threshold software parameter.</dd></dl>
<h2><a class="anchor" id="pcm_sync">
Streams synchronization</a></h2>
<p>There are two functions allowing link multiple streams together. In the case, the linking means that all operations are synchronized. Because the drivers cannot guarantee the synchronization (sample resolution) on hardware lacking this feature, the <a class="el" href="group___p_c_m___info.html#ga4a46693c8a81912de84f814c3eecd06e" title="Get hardware synchronization ID from a PCM info container.">snd_pcm_info_get_sync()</a> function returns synchronization ID - <a class="el" href="unionsnd__pcm__sync__id__t.html">snd_pcm_sync_id_t</a>, which is equal for hardware synchronized streams. When the <a class="el" href="group___p_c_m.html#gac6c33091b049985baa6466e8fe93917e" title="Link two PCMs.">snd_pcm_link()</a> function is called, all operations managing the stream state for these two streams are joined. The opposite function is <a class="el" href="group___p_c_m.html#ga0d3af5e30593dae857b4308aab5035cd" title="Remove a PCM from a linked group.">snd_pcm_unlink()</a>.</p>
<h2><a class="anchor" id="pcm_dev_names">
PCM naming conventions</a></h2>
<p>The ALSA library uses a generic string representation for names of devices. The devices might be virtual, physical or a mix of both. The generic string is passed to <a class="el" href="group___p_c_m.html#ga8340c7dc0ac37f37afe5e7c21d6c528b" title="Opens a PCM.">snd_pcm_open()</a> or <a class="el" href="group___p_c_m.html#ga88164d313d8ff9dc33c94815869cb677" title="Opens a PCM using local configuration.">snd_pcm_open_lconf()</a>. It contains two parts: device name and arguments. Devices and arguments are described in configuration files. The usual place for default definitions is at /usr/share/alsa/alsa.conf. For detailed descriptions about integrated PCM plugins look to <a class="el" href="pcm__plugins.html">PCM (digital audio) plugins</a>.</p>
<h3><a class="anchor" id="pcm_dev_names_default">
Default device</a></h3>
<p>The default device is equal to plug plugin with hw plugin as slave. The defaults are used:</p>
<div class="fragment"><pre class="fragment">defaults.pcm.card 0
defaults.pcm.device 0
defaults.pcm.subdevice -1
</pre></div><p>These defaults can be freely overwritten in local configuration files.</p>
<p>Example:</p>
<div class="fragment"><pre class="fragment"><span class="keywordflow">default</span>
</pre></div><h3><a class="anchor" id="pcm_dev_names_hw">
HW device</a></h3>
<p>The hw device description uses the hw plugin. The three arguments (in order: CARD,DEV,SUBDEV) specify card number or identifier, device number and subdevice number (-1 means any).</p>
<p>Example:</p>
<div class="fragment"><pre class="fragment">hw
hw:0
hw:0,0
hw:supersonic,1
hw:soundwave,1,2
hw:DEV=1,CARD=soundwave,SUBDEV=2
</pre></div><h3><a class="anchor" id="pcm_dev_names_plughw">
Plug-&gt;HW device</a></h3>
<p>The plughw device description uses the plug plugin and hw plugin as slave. The arguments are same as for hw device.</p>
<p>Example:</p>
<div class="fragment"><pre class="fragment">plughw
plughw:0
plughw:0,0
plughw:supersonic,1
plughw:soundwave,1,2
plughw:DEV=1,CARD=soundwave,SUBDEV=2
</pre></div><h3><a class="anchor" id="pcm_dev_names_plug">
Plug device</a></h3>
<p>The plug device uses the plug plugin. The one SLAVE argument specifies the slave plugin.</p>
<p>Example:</p>
<div class="fragment"><pre class="fragment">plug:mypcmdef
plug:hw
plug:<span class="stringliteral">&#39;hw:0,0&#39;</span>
plug:SLAVE=hw
</pre></div><h3><a class="anchor" id="pcm_dev_names_shm">
Shared memory device</a></h3>
<p>The shm device uses the shm plugin. The two arguments (in order: SOCKET,PCM) specify UNIX socket name (for example /tmp/alsa.socket) for server communication and server's PCM name.</p>
<p>Example:</p>
<div class="fragment"><pre class="fragment">shm:<span class="stringliteral">&#39;/tmp/alsa.sock&#39;</span>,<span class="keywordflow">default</span>
shm:SOCKET=<span class="stringliteral">&#39;/tmp/alsa.sock&#39;</span>,PCM=<span class="keywordflow">default</span>
</pre></div><h3><a class="anchor" id="pcm_dev_names_tee">
Tee device</a></h3>
<p>The tee device stores contents of a stream to given file plus transfers it to given slave plugin. The three arguments (in order: SLAVE,FILE,FORMAT) specify slave plugin, filename and file format.</p>
<p>Example:</p>
<div class="fragment"><pre class="fragment">tee:hw,<span class="stringliteral">&#39;/tmp/out.raw&#39;</span>,raw
</pre></div><h3><a class="anchor" id="pcm_dev_names_file">
File device</a></h3>
<p>The file device is file plugin with null plugin as slave. The arguments (in order: FILE,FORMAT) specify filename and file format.</p>
<p>Example:</p>
<div class="fragment"><pre class="fragment">file:<span class="stringliteral">&#39;/tmp/out.raw&#39;</span>,raw
</pre></div><h3><a class="anchor" id="pcm_dev_names_null">
Null device</a></h3>
<p>The null device is null plugin. This device has not any arguments.</p>
<h2><a class="anchor" id="pcm_examples">
Examples</a></h2>
<p>The full featured examples with cross-links can be found in Examples section (see top of page):</p>
<p><a class="anchor" id="example_test_pcm"></a> </p>
<dl class="user"><dt><b>Sine-wave generator</b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd>alsa-lib/test/pcm.c example shows various transfer methods for the playback direction.</dd></dl>
<dl class="user"><dt><b>Minimalistic PCM playback code</b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd>alsa-lib/test/pcm_min.c example shows the minimal code to produce a sound.</dd></dl>
<dl class="user"><dt><b>Latency measuring tool</b></dt><dd></dd></dl>
<dl class="user"><dt><b></b></dt><dd>alsa-lib/test/latency.c example shows the measuring of minimal latency between capture and playback devices. </dd></dl>
</div>
<!--- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&nbsp;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&nbsp;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&nbsp;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&nbsp;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&nbsp;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&nbsp;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&nbsp;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&nbsp;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&nbsp;</span>Defines</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<hr class="footer"/><address style="text-align: right;"><small>Generated on Tue Apr 27 13:29:07 2010 for ALSA project - the C library reference by&nbsp;
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.3 </small></address>
</body>
</html>

Perl :: Catalyst :: PostgreSQL :: RPM Valid HTML 4.01 Transitional