mirrors/alsa-lib
1
0
Fork 0
mirror of https://github.com/alsa-project/alsa-lib.git synced 2025-10-29 05:40:25 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

Added index page and PCM page (partial documentation)

Browse source
This commit is contained in:
Jaroslav Kysela 2001-10-14 11:04:00 +00:00
parent f8c9bcd465
commit 0a2bf64685
3 changed files with 173 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

2
doc/doxygen.cfg
View file

@ -5,7 +5,7 @@ GENERATE_MAN = NO
GENERATE_RTF = NO
CASE_SENSE_NAMES = NO
INPUT = ../include ../src
INPUT = index.doxygen pcm.doxygen ../include ../src
EXCLUDE = ../src/control/control_local.h \
../src/pcm/atomic.h \
../src/pcm/interval.h \

36
doc/index.doxygen Normal file
View file

@ -0,0 +1,36 @@
/*! \page Index Preamble and License
\author Jaroslav Kysela <perex@suse.cz>
\author Abramo Bagnara <abramo@alsa-project.org>
\author Takashi Iwai <takashi@suse.de>
\author Frank van de Pol <fvdpol@home.nl>
<H2>Preface</H2>
<P>The Advanced Linux Sound Architecture (\e ALSA) comes with a kernel
API & library API. This document describes the library API and how
it interfaces with the kernel API.</P>
<H2>Documentation License</H2>
<P>This documentation is free; you can redistribute it without
any restrictions. The modification or derived work must retain
copyright and list all authors.</P>
<P>This documentation is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.</P>
<H2>API usage</H2>
<P>Application programmers should use the library API rather than
kernel API. The library offers 100% of the functionally of the kernel API,
but add major improvements in usability, making the application code simpler
and better looking. In addition, some of the some fixes/compatibility code
may be placed in the library code instead of the kernel driver.</P>
<H2>API links</H2>
<UL>
<LI>Page \ref pcm explains the design of PCM (digital audio) API
</UL>
*/

136
doc/pcm.doxygen Normal file
View file

@ -0,0 +1,136 @@
/*! \page pcm PCM (digital audio) interface
<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>Digital audio is the most commonly used method of representing
sound inside a computer. In this method sound is stored as a sequence of
samples taken from the audio signal using constant time intervals.
A sample represents volume of the signal at the moment when it
was measured. In uncompressed digital audio each sample require one
or more bytes of storage. The number of bytes required depends on number
of channels (mono, stereo) and sample format (8 or 16 bits, mu-Law, etc.).
The length of this interval determines the sampling rate. Commonly used
sampling rates are between 8kHz (telephone quality) and
48kHz (DAT tapes).</P>
<P>The physical devices used in digital audio are called the
ADC (Analog to Digital Converter) and DAC (Digital to Analog Converter).
A device containing both ADC and DAC is commonly known as a codec.
The codec device used in a Sound Blaster cards is called a DSP which
is somewhat misleading since DSP also stands for Digital Signal Processor
(the SB DSP chip is very limited when compared to "true" DSP chips).</P>
<P>Sampling parameters affect the quality of sound which can be
reproduced from the recorded signal. The most fundamental parameter
is sampling rate which limits the highest frequency that can be stored.
It is well known (Nyquist's Sampling Theorem) that the highest frequency
that can be stored in a sampled signal is at most 1/2 of the sampling
frequency. For example, an 8 kHz sampling rate permits the recording of
a signal in which the highest frequency is less than 4 kHz. Higher frequency
signals must be filtered out before feeding them to ADC.</P>
<P>Sample encoding limits the dynamic range of a recorded signal
(difference between the faintest and the loudest signal that can be
recorded). In theory the maximum dynamic range of signal is number_of_bits *
6dB. This means that 8 bits sampling resolution gives dynamic range of
48dB and 16 bit resolution gives 96dB.</P>
<P>Quality has price. The number of bytes required to store an audio
sequence depends on sampling rate, number of channels and sampling
resolution. For example just 8000 bytes of memory is required to store
one second of sound using 8kHz/8 bits/mono but 48kHz/16bit/stereo takes
192 kilobytes. A 64 kbps ISDN channel is required to transfer a
8kHz/8bit/mono audio stream in real time, and about 1.5Mbps is required
for DAT quality (48kHz/16bit/stereo). On the other hand it is possible
to store just 5.46 seconds of sound in a megabyte of memory when using
48kHz/16bit/stereo sampling. With 8kHz/8bits/mono it is possible to store
131 seconds of sound using the same amount of memory. It is possible
to reduce memory and communication costs by compressing the recorded
signal but this is beyond the scope of this document. </P>
\section pcm_open_behaviour Blocked and non-blocked open
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
\a mode argument in \link ::snd_pcm_open() \endlink function.
The blocked mode is the default (without \link ::SND_PCM_NONBLOCK \endlink 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 \link ::SND_PCM_NONBLOCK \endlink)
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 \link snd_pcm_nonblock() \endlink function.
\section pcm_async Asynchronous mode
There is also possibility to receive asynchronous notification after
specified time periods. You may see the \link ::SND_PCM_ASYNC \endlink
mode for \link ::snd_pcm_open() \endlink function and
\link ::snd_async_add_pcm_handler() \endlink function for further details.
\section pcm_handshake Handshake between application and library
The ALSA PCM API design uses the states to determine the communication
phase between application and library. The actual state can be determined
using \link ::snd_pcm_state() \endlink call. There are these states:
\par SND_PCM_STATE_OPEN
The PCM device is in the open state. After the \link ::snd_pcm_open() \endlink open call,
the device is in this state. Also, when \link ::snd_pcm_hw_params() \endlink call fails,
then this state is entered to force application calling
\link ::snd_pcm_hw_params() \endlink function to set right communication
parameters.
\par SND_PCM_STATE_SETUP
The PCM device has accepted communication parameters and it is waiting
for \link ::snd_pcm_prepare() \endlink call to prepare the hardware for
selected operation (playback or capture).
\par SND_PCM_STATE_PREPARE
The PCM device is prepared for operation. Application can use
\link ::snd_pcm_start() \endlink call, write or read data to start
the operation.
\par SND_PCM_STATE_RUNNING
The PCM device is running. It processes the samples. The stream can
be stopped using the \link ::snd_pcm_drop() \endlink or
\link ::snd_pcm_drain \endlink calls.
\par SND_PCM_STATE_XRUN
The PCM device reached overrun (capture) or underrun (playback).
You can use the -EPIPE return code from I/O functions
(\link ::snd_pcm_writei() \endlink, \link ::snd_pcm_writen() \endlink,
\link ::snd_pcm_readi() \endlink, \link ::snd_pcm_readi() \endlink)
to determine this state without checking
the actual state via \link ::snd_pcm_state() \endlink call. You can recover from
this state with \link ::snd_pcm_prepare() \endlink,
\link ::snd_pcm_drop() \endlink or \link ::snd_pcm_drain() \endlink calls.
\par SND_PCM_STATE_DRAINING
The device is in this state when application using the capture mode
called \link ::snd_pcm_drain() \endlink function. Until all data are
read from the internal ring buffer using I/O routines
(\link ::snd_pcm_readi() \endlink, \link ::snd_pcm_readn() \endlink),
then the device stays in this state.
\par SND_PCM_STATE_PAUSED
The device is in this state when application called
the \link ::snd_pcm_pause() \endlink function until the pause is released.
Not all hardware supports this feature. Application should check the
capability with the \link ::snd_pcm_hw_params_can_pause() \endlink.
\par SND_PCM_STATE_SUSPENDED
The device is in the suspend state provoked with the power management
system. The stream can be resumed using \link ::snd_pcm_resume() \endlink
call, but not all hardware supports this feature. Application should check
the capability with the \link ::snd_pcm_hw_params_can_resume() \endlink.
In other case, the calls \link ::snd_pcm_prepare() \endlink,
\link ::snd_pcm_drop() \endlink, \link ::snd_pcm_drain() \endlink can be used
to leave this state.
*/