-EXTRA_DIST=plan.txt soundapi.txt soundapi.sgml \
- soundapi.html soundapi-1.html soundapi-2.html \
- soundapi-3.html soundapi-4.html soundapi-5.html
+EXTRA_DIST=plan.txt alsa-lib.lyx alsa-lib.html \
+ pcmbuf.ps pcmbuf.gif pcmbuf1.ps pcmbuf1.gif
INCLUDES=-I$(top_srcdir)/include
--- /dev/null
+ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
+ "http://www.w3.org/TR/REC-html40/loose.dtd"><HTML>
+<META NAME="GENERATOR" CONTENT="TtH 1.98">
+
+
+
+<title> Advanced Linux Sound Architecture - Library API</title>
+
+<H1 align=center>Advanced Linux Sound Architecture - Library API </H1>
+
+<p>
+
+<H3 align=center><b>Jaroslav Kysela <perex@jcu.cz></b> with assistance from Alan Robinson and Fred Floberg</H3>
+
+<p>
+
+<H3 align=center>1998-11-11 </H3>
+
+<p>
+<center> <i>This document describes, in full detail, the Advanced Linux
+Sound Architecture library API. </i>
+<p>
+</center>
+<H1>Contents </H1><A href="#tth_sEc1"
+>1 Introduction</A><br>
+<A href="#tth_sEc2"
+>2 Error Codes</A><br>
+ <A href="#tth_sEc2.1"
+>2.1 Error Codes in Detail</A><br>
+ <A href="#tth_sEc2.2"
+>2.2 Functions</A><br>
+<A href="#tth_sEc3"
+>3 Control Interface</A><br>
+ <A href="#tth_sEc3.1"
+>3.1 Low-Level Layer</A><br>
+ <A href="#tth_sEc3.1.1"
+>3.1.1 Examples</A><br>
+<A href="#tth_sEc4"
+>4 Mixer Interface</A><br>
+ <A href="#tth_sEc4.1"
+>4.1 Low-Level Layer</A><br>
+ <A href="#tth_sEc4.1.1"
+>4.1.1 Examples</A><br>
+<A href="#tth_sEc5"
+>5 Digital Audio (PCM) Interface</A><br>
+ <A href="#tth_sEc5.1"
+>5.1 Low-Level Layer</A><br>
+ <A href="#tth_sEc5.1.1"
+>5.1.1 Example</A><br>
+ <A href="#tth_sEc5.2"
+>5.2 PCM Loopback Interface</A><br>
+<A href="#tth_sEc6"
+>6 RawMidi Interface</A><br>
+ <A href="#tth_sEc6.1"
+>6.1 Low Level Layer</A><br>
+ <A href="#tth_sEc6.1.1"
+>6.1.1 Example</A><br>
+
+<p>
+ <H2><A NAME="tth_sEc1">
+1</A> Introduction</H2>
+
+<p>
+The Advanced Linux Sound Architecture comes with a kernel API & library API.
+This document describes the library API and how it interfaces with the kernel
+API. The kernal API will probably never be documented in standalone form.
+
+<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>
+For a complete list of all variables and functions in the API you should look
+at the following header files:
+
+<p>
+
+<UL>
+<li> /usr/include/sys/asoundlib.h
+
+<li> /usr/include/linux/asound.h
+
+<li> /usr/include/linux/asoundid.h
+</UL>
+<p>
+ <H2><A NAME="tth_sEc2">
+2</A> Error Codes</H2>
+
+<p>
+All functions return int (or some sort of signed value). If this value is negative
+it represents an error code. Codes up to <i>SND_ERROR_BEGIN (500000)</i>
+represent standard system errors. Codes equal to or greather than this value
+represent sound library API errors. All error codes begin with the prefix <i>SND_ERROR_</i>.
+
+<p>
+ <H3><A NAME="tth_sEc2.1">
+2.1</A> Error Codes in Detail</H3>
+
+<p>
+
+<table border>
+<tr><td align="center">SND_ERROR_UNCOMPATIBLE_VERSION</td><td align="center">500000</td></td></table>
+
+
+<p>
+This error is caused if the driver uses an incompatible kernel API for this
+interface and hence the library doesn't know how this API can be used.
+
+<p>
+ <H3><A NAME="tth_sEc2.2">
+2.2</A> Functions</H3>
+
+<p>
+
+<H4>const char *snd_strerror(int errnum) </H4>
+
+<p>
+This function converts an error code to a string. Its functionality is the same
+as the <i>strerror</i> function from the standard C library, but this function
+returns error message strings for sound error codes, as well.
+
+<p>
+ <H2><A NAME="tth_sEc3">
+3</A> Control Interface</H2>
+
+<p>
+The control interface gives applications various information about the currently
+installed sound driver in the system. The interface should be used to detect
+if another sound interface is present for a selected soundcard or, for example,
+to create a list of devices (MIXER, PCM etc) from which the user can select.
+
+<p>
+ <H3><A NAME="tth_sEc3.1">
+3.1</A> Low-Level Layer</H3>
+
+<p>
+
+<H4>int snd_cards(void)</H4>
+
+<p>
+Returns the number of soundcards present in the system, if any. Otherwise it
+returns a negative value, which maps to an error code. This function will return
+0 if no soundcards are detected.
+
+<p>
+
+<H4>unsigned int snd_cards_mask(void)</H4>
+
+<p>
+Returns the bitmap of soundcards present in the system, if any. This function
+will return 0 if no soundcards are detected. The first soundcard is represented
+with bit 0 (0x00000001). See the documentation on installing ALSA and /etc/conf.modules
+configuration for information on assigning numbers to soundcards.
+
+<p>
+
+<H4>int snd_card_name(const char *name)</H4>
+
+<p>
+Returns soundcard number for appropriate soundcard name. String <i>name</i>
+can contain word identification for card (ALSA driver allows the user choose
+card identification using snd_id module parameter) or soundcard index (1-N)
+encoded into ASCII.
+
+<p>
+
+<H4>int snd_ctl_open(void **handle, int card)</H4>
+
+<p>
+Creates a new handle and opens communication with the kernel sound control interface
+for soundcard number <i>card</i> (0-N). The function also checks if the protocol
+is compatible, so as to prevent the use of old programs with a new kernel API.
+Function returns zero if successful, otherwise an error code is returned.
+
+<p>
+
+<H4>int snd_ctl_close(void *handle)</H4>
+
+<p>
+Frees all resources allocated with control handle and closes the kernel sound
+control interface. This function returns zero if successful, otherwise it returns
+an error code.
+
+<p>
+
+<H4>int snd_ctl_file_descriptor(void *handle)</H4>
+
+<p>
+Returns a file descriptor for the kernel sound control interface. This function
+is normally only used in very special cases. This function returns a negative
+error code if an error was encountered.
+
+<p>
+
+<H4>int snd_ctl_hw_info(void *handle, snd_ctl_hw_info_t *info)</H4>
+
+<p>
+Fills the info structure with data about the sound hardware referenced by handle.
+This function returns zero if successful, otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+<i>/* driver has MIDI interface */ </i>
+
+<p>
+#define SND_CTL_GCAPS_MIDI 0x0000001
+
+<p>
+<i>/* soundcard has synthesizer */</i>
+
+<p>
+#define SND_CTL_LCAPS_SYNTH 0x0000001
+
+<p>
+<i>/* soundcard has RAW FM/OPL3 */</i>
+
+<p>
+#define SND_CTL_LCAPS_RAWFM 0x0000002
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_ctl_hw_info {
+
+<p>
+ <i>/* type of card - see SND_CARD_TYPE_XXXX */</i>
+
+<p>
+ unsigned int type;
+
+<p>
+ <i>/* global capabilities - see SND_CTL_GCAPS_XXXX*/</i>
+
+<p>
+ unsigned int gcaps;
+
+<p>
+ <i>/* local capabilities ¯ see SND_CTL_LCAPS_XXXX */</i>
+
+<p>
+ unsigned int lcaps;
+
+<p>
+ <i>/* count of PCM devices (0 to N) */</i>
+
+<p>
+ unsigned int pcmdevs;
+
+<p>
+ <i>/* count of MIXER devices (0 to N)*/</i>
+
+<p>
+ unsigned int mixerdevs;
+
+<p>
+ <i>/* count of raw MIDI devices (0 to N) */</i>
+
+<p>
+ unsigned int mididevs;
+
+<p>
+ <i>/* ID of card (user selectable) */</i>
+
+<p>
+ char id[80];
+
+<p>
+ <i>/* name/info text about soundcard */</i>
+
+<p>
+ char name[80];
+
+<p>
+ <i>/* count of control switches */</i>
+
+<p>
+ unsigned int switches;
+
+<p>
+ <i>/* reserved for future use */</i>
+
+<p>
+ unsigned char reserved[124];
+
+<p>
+};
+</DL>
+<p>
+
+<H4>int snd_ctl_switches(void *handle)</H4>
+
+<p>
+Returns the number of control switches. In this context 'switch' means universal
+control interface between kernel and application which allows various types
+of control. Function returns count if successful, otherwise it returns an error
+code. Return value should be zero if the soundcard doesn't have any control
+switches.
+
+<p>
+
+<H4>int snd_ctl_switch(void *handle, const char *switch_id)</H4>
+
+<p>
+Returns the index for the switch with the name <i>switch_id</i>. This function
+returns switch index if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_ctl_switch_read(void *handle int switchn snd_ctl_switch_t
+*data)</H4>
+
+<p>
+Fills the <i>*data</i> structure with data about the switch with index <i>switchn</i>.
+This function returns zero if successful, otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+<i>/* 0 or 1 (enable member of union) */</i>
+
+<p>
+#define SND_CTL_SW_TYPE_BOOLEAN 0
+
+<p>
+<i>/* 0 to 255 - from low to high (data8[0] member of union) */</i>
+
+<p>
+#define SND_CTL_SW_TYPE_BYTE 1
+
+<p>
+<i>/* 0 to 65535 - from low to high (data16[0] member of union) */</i>
+
+<p>
+#define SND_CTL_SW_TYPE_WORD 2
+
+<p>
+<i>/* 0 to 4294967296 ¯ from low to high (data32[0] member of union) */</i>
+
+<p>
+#define SND_CTL_SW_TYPE_DWORD 3
+
+<p>
+<i>/* user type - no type control */</i>
+
+<p>
+#define SND_CTL_SW_TYPE_USER (~0)
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+<i>/* well known (named) switches */</i>
+
+<p>
+#define SND_CTL_SW_JOYSTICK "Joystick"
+
+<p>
+#define SND_CTL_SW_JOYSTICK_ADDRESS "Joystick Address"
+
+<p>
+#define SND_CTL_SW_JOYSTICK_SPEED "Joystick Speed"
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_ctl_switch {
+
+<p>
+ <i>/* switch index (filled by application) */</i>
+
+<p>
+ unsigned int switchn;
+
+<p>
+ <i>/* indentification of switch (for driver) */</i>
+
+<p>
+ unsigned char name[32];
+
+<p>
+ <i>/* type of switch value - See SND_CTL_SW_TYPE_XXXX */</i>
+
+<p>
+ unsigned int type;
+
+<p>
+ <i>/* low range value */</i>
+
+<p>
+ unsigned int low;
+
+<p>
+ <i>/* high range value */</i>
+
+<p>
+ unsigned int high;
+
+<p>
+ union {
+
+<p>
+ unsigned int enable; <i>/* 0 = off 1 = on */</i>
+
+<p>
+ unsigned char data8[32]; <i>/* 8-bit data */</i>
+
+<p>
+ unsigned short data16[16]; <i>/* 16-bit data */</i>
+
+<p>
+ unsigned int data32[8]; <i>/* 32-bit data */</i>
+
+<p>
+ } value;
+
+<p>
+ <i>/* reserved for future use ¯ must be zero !!! */</i>
+
+<p>
+ unsigned char reserved[32];
+
+<p>
+}
+</DL>
+<p>
+
+<H4>int snd_ctl_switch_write(void *handle int switchn snd_ctl_switch_t
+*data)</H4>
+
+<p>
+Writes the <i>*data</i> structure with data about the switch with index
+<i>switchn</i> to kernel. This function returns zero if successful, otherwise
+it returns an error code.
+
+<p>
+
+<H4>int snd_ctl_mixer_info(void *handle, int dev, snd_mixer_info_t *info)</H4>
+
+<p>
+Fills the *info structure with data about the mixer device. Returns zero if
+successful, otherwise it returns an error code. Details about the <i>snd_mixer_info_t</i>
+structure are in the <b>Mixer Interface</b> section. The argument <i>dev</i>
+specifies the device number for the appropriate soundcard. Its range is 0 to
+N where N is determined by <i>struct snd_ctl_hw_info->mixerdevs - 1</i>.
+It should be used to collect information about mixer devices.
+
+<p>
+
+<H4>int snd_ctl_mixer_switches(void *handle)</H4>
+
+<p>
+Returns count of mixer switches. In this context 'switch' means universal control
+interface between kernel and application which allows various types control.
+This function returns count if successful, otherwise it returns an error code.
+Return value should be zero if soundcard doesn't have any mixer switches.
+
+<p>
+
+<H4>int snd_ctl_mixer_switch(void *handle, const char *switch_id)</H4>
+
+<p>
+Returns the index for the switch with the name <i>switch_id</i>. This function
+returns switch index if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_ctl_mixer_switch_read(void *handle int switchn snd_mixer_switch_t
+*data)</H4>
+
+<p>
+Fills the <i>*data</i> structure with data about the switch with index <i>switchn</i>.
+This function returns zero if successful, otherwise it returns an error code.
+Details about the <i>snd_mixer_switch_t</i> structure are in the <b>Mixer
+Interface</b> section.
+
+<p>
+
+<H4>int snd_ctl_mixer_switch_write(void *handle int switchn snd_mixer_switch_t
+*data)</H4>
+
+<p>
+Writes the <i>*data</i> structure with data about switch with index <i>switchn</i>
+to kernel. Function returns zero if successful, otherwise it returns an error
+code. Details about the <i>snd_mixer_switch_t</i> structure are in the
+<b>Mixer Interface</b> Interface section.
+
+<p>
+
+<H4>int snd_ctl_pcm_info(void *handle, int dev, snd_pcm_info_t *info)</H4>
+
+<p>
+Fills the <i>*info</i> structure with data about the PCM device. Function
+returns zero if successful, otherwise it returns an error code. Details about
+the <i>snd_pcm_info_t</i> structure are in the <b>Digital Audio (PCM)</b>
+Interface section. The argument <i>dev</i> selects the device number for the
+sound card referenced by <i>*handle</i>. Its range is 0 to N where N is
+<i>struct snd_ctl_hw_info->pcmdevs - 1</i>. This function will work if
+the selected PCM device is busy, too. It should be used to collect information
+about PCM devices without exclusive lock.
+
+<p>
+
+<H4>int snd_ctl_pcm_playback_info(void *handle, int dev, snd_pcm_playback_info_t
+*info) </H4>
+
+<p>
+Fills the <i>*info</i> structure with data about the PCM device and playback
+direction. Function returns zero if successful, otherwise it returns an error
+code. Details about the <i>snd_pcm_playback_info_t</i> structure are in
+the <b>Digital Audio (PCM) Interface</b> section. The argument <i>dev</i>
+selects the device number for the sound card referenced by <i>*handle</i>.
+Its range is 0 to N where N is <i>struct snd_ctl_hw_info->pcmdevs -
+1</i>. This function will work if the selected PCM device is busy, too. It should
+be used to collect information about PCM devices without exclusive lock.
+
+<p>
+
+<H4>int snd_ctl_pcm_playback_switches(void *handle)</H4>
+
+<p>
+Returns count of PCM playback switches. In this context 'switch' means universal
+control interface between kernel and application which allows various types
+of control. Function returns count if successful, otherwise it returns an error
+code. Return value should be zero if sound card doesn't have any PCM playback
+switch.
+
+<p>
+
+<H4>int snd_ctl_pcm_playback_switch(void *handle, const char *switch_id)</H4>
+
+<p>
+Returns index for switch with name <i>switch_id</i>. Function returns switch
+index if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_ctl_pcm_playback_switch_read(void *handle int switchnsnd_pcm_switch_t *data)</H4>
+
+<p>
+Fills the <i>*data</i> structure with data about switch with index <i>switchn</i>.
+Function returns zero if successful, otherwise it returns an error code. Details
+about the <i>snd_pcm_switch_t</i> structure are in the <b>Digital
+Audio (PCM)</b> Interface section.
+
+<p>
+
+<H4>int snd_ctl_pcm_playback_switch_write(void *handle int switchnsnd_pcm_switch_t *data)</H4>
+
+<p>
+Writes the <i>*data</i> structure with data about switch with index <i>switchn</i>
+to kernel. Function returns zero if successful, otherwise it returns an error
+code. Details about the <i>snd_pcm_switch_t</i> structure are in the <b>Digital
+Audio (PCM)</b> Interface section.
+
+<p>
+
+<H4>int snd_ctl_pcm_record_info(void *handle, int dev, snd_pcm_record_info_t
+*info)</H4>
+
+<p>
+Fills the <i>*info</i> structure with data about the PCM device and record
+direction. Function returns zero if successful, otherwise it returns an error
+code. Details about the <i>snd_pcm_record_info_t</i> structure are in
+the <b>Digital Audio (PCM) Interface</b> section. The argument <i>dev</i>
+selects the device number for the sound card referenced by <i>*handle</i>.
+Its range is 0 to N where N is <i>struct snd_ctl_hw_info->pcmdevs -
+1</i>. This function will work if the selected PCM device is busy, too. It should
+be used to collect information about PCM devices without exclusive lock.
+
+<p>
+
+<H4>int snd_ctl_pcm_record_switches(void *handle)</H4>
+
+<p>
+Returns count of PCM record switches. In this context 'switch' means universal
+control interface between kernel and application which allows various types
+of control. Function returns count if successful, otherwise it returns an error
+code. Return value should be zero if sound card doesn't have any PCM record
+switch.
+
+<p>
+
+<H4>int snd_ctl_pcm_record_switch(void *handle, const char *switch_id)</H4>
+
+<p>
+Returns index for switch with name <i>switch_id</i>. Function returns switch
+index if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_ctl_pcm_record_switch_read(void *handle int switchnsnd_pcm_switch_t *data)</H4>
+
+<p>
+Fills the <i>*data</i> structure with data about switch with index <i>switchn</i>.
+Function returns zero if successful, otherwise it returns an error code. Details
+about the <i>snd_pcm_switch_t</i> structure are in the <b>Digital
+Audio (PCM)</b> Interface section.
+
+<p>
+
+<H4>int snd_ctl_pcm_record_switch_write(void *handle int switchnsnd_pcm_switch_t *data)</H4>
+
+<p>
+Writes the <i>*data</i> structure with data about switch with index <i>switchn</i>
+to kernel. Function returns zero if successful, otherwise it returns an error
+code. Details about the <i>snd_pcm_switch_t</i> structure are in the <b>Digital
+Audio (PCM)</b> Interface section.
+
+<p>
+
+<H4>int snd_ctl_rawmidi_info(void *handle, int dev, snd_rawmidi_info_t
+*info)</H4>
+
+<p>
+Fills the <i>*info</i> structure with data about the rawmidi device. Function
+returns zero if successful, otherwise it returns an error code. Details about
+the <i>snd_rawmidi_info_t</i> structure are in the <b>RawMidi Interface</b>
+section. The argument <i>dev</i> selects the device number for the sound card
+referenced by <i>*handle</i>. Its range is 0 to N where N is <i>struct
+snd_ctl_hw_info->mididevs - 1</i>. This function will work if the selected rawmidi
+device is busy, too. It should be used to collect information about rawmidi
+devices without exclusive lock.
+
+<p>
+
+<H4>int snd_ctl_rawmidi_output_info(void *handle, int dev, snd_rawmidi_output_info_t
+*info) </H4>
+
+<p>
+Fills the <i>*info</i> structure with data about the rawmidi device and
+output direction. Function returns zero if successful, otherwise it returns
+an error code. Details about the <i>snd_pcm_playback_info_t</i> structure
+are in the <b>RawMidi Interface</b> section. The argument <i>dev</i> selects
+the device number for the sound card referenced by <i>*handle</i>. Its range
+is 0 to N where N is <i>struct snd_ctl_hw_info->mididevs - 1</i>. This
+function will work if the selected rawmidi device is busy, too. It should be
+used to collect information about rawmidi devices without exclusive lock.
+
+<p>
+
+<H4>int snd_ctl_rawmidi_output_switches(void *handle)</H4>
+
+<p>
+Returns count of rawmidi output switches. In this context 'switch' means universal
+control interface between kernel and application which allows various types
+of control. Function returns count if successful, otherwise it returns an error
+code. Return value should be zero if sound card doesn't have any control switch.
+
+<p>
+
+<H4>int snd_ctl_rawmidi_output_switch(void *handle, const char *switch_id)</H4>
+
+<p>
+Returns index for switch with name <i>switch_id</i>. Function returns switch
+index if successful, otherwise it returns an error code. Return value should
+be zero if sound card doesn't have any rawmidi output switch.
+
+<p>
+
+<H4>int snd_ctl_rawmidi_output_switch_read(void *handle int switchnsnd_rawmidi_switch_t *data)</H4>
+
+<p>
+Fills the <i>*data</i> structure with data about switch with index <i>switchn</i>.
+Function returns zero if successful, otherwise it returns an error code. Details
+about the <i>snd_rawmidi_switch_t</i> structure are in the <b>RawMidi
+Interface</b> section.
+
+<p>
+
+<H4>int snd_ctl_rawmidi_output_switch_write(void *handle int switchnsnd_rawmidi_switch_t *data)</H4>
+
+<p>
+Writes the <i>*data</i> structure with data about switch with index <i>switchn</i>
+to kernel. Function returns zero if successful, otherwise it returns an error
+code. Details about the <i>snd_rawmidi_switch_t</i> structure are in the
+<b>RawMidi Interface</b> section.
+
+<p>
+
+<H4>int snd_ctl_rawmidi_input_info(void *handle, int dev, snd_rawmidi_input_info_t
+*info)</H4>
+
+<p>
+Fills the <i>*info</i> structure with data about the rawmidi device and
+input direction. Function returns zero if successful, otherwise it returns an
+error code. Details about the <i>snd_rawmidi_record_info_t</i> structure
+are in the <b>RawMidi Interface</b> section. The argument <i>dev</i> selects
+the device number for the sound card referenced by <i>*handle</i>. Its range
+is 0 to N where N is <i>struct snd_ctl_hw_info->pcmdevs - 1</i>. This function
+will work if the selected rawmidi device is busy, too. It should be used to
+collect information about rawmidi devices without exclusive lock.
+
+<p>
+
+<H4>int snd_ctl_rawmidi_input_switches(void *handle)</H4>
+
+<p>
+Returns count of rawmidi input switches. In this context 'switch' means universal
+control interface between kernel and application which allows various types
+of control. Function returns count if successful, otherwise it returns an error
+code. Return value should be zero if sound card doesn't have any rawmidi input
+switch.
+
+<p>
+
+<H4>int snd_ctl_rawmidi_input_switch(void *handle, const char *switch_id)</H4>
+
+<p>
+Returns index for switch with name <i>switch_id</i>. Function returns switch
+index if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_ctl_rawmidi_input_switch_read(void *handle int switchnsnd_pcm_switch_t *data)</H4>
+
+<p>
+Fills the <i>*data</i> structure with data about switch with index <i>switchn</i>.
+Function returns zero if successful, otherwise it returns an error code. Details
+about the <i>snd_rawmidi_switch_t</i> structure are in the <b>RawMidi
+Interface</b> Interface section.
+
+<p>
+
+<H4>int snd_ctl_rawmidi_input_switch_write(void *handle int switchnsnd_pcm_switch_t *data)</H4>
+
+<p>
+Writes the <i>*data</i> structure with data about switch with index <i>switchn</i>
+to kernel. Function returns zero if successful, otherwise it returns an error
+code. Details about the <i>snd_rawmidi_switch_t</i> structure are in the
+<b>RawMidi Interface</b> section.
+
+<p>
+ <H4><A NAME="tth_sEc3.1.1">
+3.1.1</A> Examples</H4>
+
+<p>
+The following example shows how all PCM devices can be detected for the first
+sound card (#0) in the system.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+int card = 0, err;
+
+<p>
+void *handle;
+
+<p>
+snd_ctl_hw_info_t info;<br>
+
+<p>
+if ((err = snd_ctl_open(&handle, card)) < 0) {
+
+<p>
+ fprintf(stderr, "open failed: %s\n", snd_strerror(err));
+
+<p>
+ return;
+
+<p>
+}
+
+<p>
+if ((err = snd_ctl_hw_info(handle, &info)) < 0) {
+
+<p>
+ fprintf(stderr, "hw info failed: %s\n",
+
+<p>
+ snd_strerror(err));
+
+<p>
+ snd_ctl_close(handle);
+
+<p>
+ return;
+
+<p>
+}
+
+<p>
+printf("Installed PCM devices for card #i: %i\n",
+
+<p>
+ card + 1, info.pcmdevs);
+
+<p>
+snd_ctl_close(handle);
+</DL>
+<p>
+ <H2><A NAME="tth_sEc4">
+4</A> Mixer Interface</H2>
+
+<p>
+The Mixer Interface allows applications to change the volume level of a sound
+card's input/output channels in both the linear range percentage range
+(0-100) and in decibels. It also supports features like hardware mute, input
+sound source, stereo signal routing etc.
+
+<p>
+ <H3><A NAME="tth_sEc4.1">
+4.1</A> Low-Level Layer</H3>
+
+<p>
+Mixer devices aren't opened exclusively. This allows applications to open a
+device multiple times with one or more processes.
+
+<p>
+
+<H4>int snd_mixer_open(void **handle, int card, int device) </H4>
+
+<p>
+Creates new handle and opens a connection to the kernel sound mixer interface
+for sound card number <i>card</i> (0-N) and mixer device number <i>device</i>.
+Also checks if protocol is compatible to prevent use of old programs with new
+kernel API. Function returns zero if successful, otherwise it returns an error
+code.
+
+<p>
+
+<H4>int snd_mixer_close(void *handle)</H4>
+
+<p>
+Frees all resources allocated to the mixer handle and closes its connection
+to the kernel sound mixer interface. Function returns zero if successful, otherwise
+it returns an error code.
+
+<p>
+
+<H4>int snd_mixer_file_descriptor(void *handle)</H4>
+
+<p>
+Returns the file descriptor for the connection to the kernel sound mixer interface.
+This function should be used only in very special cases. Function returns a
+negative error code if an error was encountered.
+
+<p>
+The file descriptor should be used for the <i>select(2)</i> synchronous multiplexer
+function for determining read direction. Applications should call <i>snd_mixer_read()</i>
+function if some data is waiting to be read. It is recommended that you do this,
+since it leaves place for this function to handle some new kernel API specifications.
+
+<p>
+
+<H4>int snd_mixer_channels(void *handle) </H4>
+
+<p>
+Returns the count of mixer channels for appropriate mixer device, otherwise
+the return value is negative, and signifies an error code. Never returns zero.
+
+<p>
+
+<H4>int snd_mixer_info(void *handle, snd_mixer_info_t *info) </H4>
+
+<p>
+Fills the <i>*info</i> structure with information about the mixer associated
+with <i>*handle</i>. Returns zero if successful, otherwise it returns an
+error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+<i>/* mixer can do only exclusive record */</i>
+
+<p>
+#define SND_MIXER_INFO_CAP_EXCL_RECORD 0x00000001
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_mixer_info {
+
+<p>
+ <i>/* type of sound card - SND_CARD_TYPE_XXXX */</i>
+
+<p>
+ unsigned int type;
+
+<p>
+ <i>/* count of mixer devices */</i>
+
+<p>
+ unsigned int channels;
+
+<p>
+ <i>/* some flags about this device (SND_MIXER_INFO_CAP_XXXX) */</i>
+
+<p>
+ unsigned int caps;
+
+<p>
+ <i>/* ID of this mixer */</i>
+
+<p>
+ unsigned char id[32];
+
+<p>
+ <i>/* name of this device */</i>
+
+<p>
+ unsigned char name[80];
+
+<p>
+ <i>/* reserved for future use */</i>
+
+<p>
+ char reserved[ 32 ];
+
+<p>
+};
+</DL>
+<p>
+
+<H4>int snd_mixer_switches(void *handle)</H4>
+
+<p>
+Returns count of mixer switches. In this context 'switch' means universal control
+interface between kernel and application which allows various types of control.
+Function returns count if successful, otherwise it returns an error code. Return
+value will be zero if sound card doesn't have any mixer switch.
+
+<p>
+
+<H4>int snd_mixer_switch(void *handle, const char *switch_id)</H4>
+
+<p>
+Returns index for switch with name <i>switch_id</i>. Function returns switch
+index if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_mixer_switch_read(void *handle int switchn snd_mixer_switch_t
+*data)</H4>
+
+<p>
+Fills the <i>*data</i> structure with data about switch with index <i>switchn</i>.
+Function returns zero if successful, otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+<i>/* 0 or 1 (enable member of union) */</i>
+
+<p>
+#define SND_MIXER_SW_TYPE_BOOLEAN 0
+
+<p>
+<i>/* 0 to 255 - from low to high (data8[0] member of union) */</i>
+
+<p>
+#define SND_MIXER_SW_TYPE_BYTE 1
+
+<p>
+<i>/* 0 to 65535 - from low to high (data16[0] member of union) */</i>
+
+<p>
+#define SND_MIXER_SW_TYPE_WORD 2
+
+<p>
+<i>/* 0 to 4294967296 ¯ from low to high (data32[0] member of union) */</i>
+
+<p>
+#define SND_MIXER_SW_TYPE_DWORD 3
+
+<p>
+<i>/* user type - no type control */</i>
+
+<p>
+#define SND_MIXER_SW_TYPE_USER (~0)
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+<i>/* well known (named) switches */</i>
+
+<p>
+#define SND_MIXER_SW_LOUDNESS "Loudness" <i>/* bass boost */</i>
+
+<p>
+#define SND_MIXER_SW_SIM_STEREO "Simulated Stereo Enhancement"
+
+<p>
+#define SND_MIXER_SW_3D "3D Stereo Enhancement"
+
+<p>
+<i>/* microphone gain */</i>
+
+<p>
+#define SND_MIXER_SW_MIC_GAIN "MIC Gain"
+
+<p>
+<i>/* microphone auto gain control */</i>
+
+<p>
+#define SND_MIXER_SW_MIC_GAIN "MIC Auto-Gain-Control"
+
+<p>
+<i>/* change microphone impedance */</i>
+
+<p>
+#define SND_MIXER_SW_MIC_GAIN "Change MIC Impedance"
+
+<p>
+<i>/* change line-in to output */</i>
+
+<p>
+#define SND_MIXER_SW_MIC_GAIN "Line In to Output"
+
+<p>
+#define SND_MIXER_SW_IEC958OUT "IEC-958 (S/PDIF) Output"
+
+<p>
+#define SND_MIXER_SW_IEC958IN "IEC-958 (S/PDIF) Input"
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_mixer_switch {
+
+<p>
+ <i>/* switch index (filled by application) */</i>
+
+<p>
+ unsigned int switchn;
+
+<p>
+ <i>/* identification of switch (for driver) */</i>
+
+<p>
+ unsigned char name[32];
+
+<p>
+ <i>/* type of switch value ¯ See SND_CTL_SW_TYPE_XXXX */</i>
+
+<p>
+ unsigned int type;
+
+<p>
+ <i>/* low range value */</i>
+
+<p>
+ unsigned int low;
+
+<p>
+ <i>/* high range value */</i>
+
+<p>
+ unsigned int high;
+
+<p>
+ union {
+
+<p>
+ unsigned int enable; <i>/* 0 = off 1 = on */</i>
+
+<p>
+ unsigned char data8[32]; <i>/* 8-bit data */</i>
+
+<p>
+ unsigned short data16[16]; <i>/* 16-bit data */</i>
+
+<p>
+ unsigned int data32[8]; <i>/* 32-bit data */</i>
+
+<p>
+ } value;
+
+<p>
+ <i>/* reserved for future use ¯ must be zero !!! */</i>
+
+<p>
+ unsigned char reserved[32];
+
+<p>
+}
+</DL>
+<p>
+
+<H4>int snd_mixer_switch_write(void *handle int switchn snd_mixer_switch_t
+*data)</H4>
+
+<p>
+Writes the <i>*data</i> structure with data about switch with index <i>switchn</i>
+to kernel. Function returns zero if successful, otherwise it returns an error
+code.
+
+<p>
+
+<H4>int snd_mixer_exact_mode(void *handle, int enable)</H4>
+
+<p>
+Turns on = 1 or off = 0 (by default) exact mode. This mode allows application
+to set/get volume values in exact range which uses hardware. In non-exact mode
+range is always from percentage 0 to 100 and driver does conversion to hardware
+range. Function returns zero if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_mixer_channel(void *handle, const char *channel_id)</H4>
+
+<p>
+Returns the channel number (index) associated with <i>channel_id</i> (channel
+name), or returns an error code. Note: Below mixer channel IDs are subject to
+change and will be extended if new hardware has support for other mixer input/output
+channels.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+#define SND_MIXER_ID_MASTER "Master"
+
+<p>
+#define SND_MIXER_ID_MASTER1 "Master 1"
+
+<p>
+<i>/* digital master */</i>
+
+<p>
+#define SND_MIXER_ID_MASTERD "Master D"
+
+<p>
+<i>/* second digital master */</i>
+
+<p>
+#define SND_MIXER_ID_MASTERD1 "Master D1"
+
+<p>
+#define SND_MIXER_ID_HEADPHONE "Headphone"
+
+<p>
+#define SND_MIXER_ID_MASTER_MONO "Master M"
+
+<p>
+#define SND_MIXER_ID_3D "3D Wide"
+
+<p>
+#define SND_MIXER_ID_3D_VOLUME "3D Volume"
+
+<p>
+#define SND_MIXER_ID_3D_CENTER "3D Center"
+
+<p>
+#define SND_MIXER_ID_3D_SPACE "3D Space"
+
+<p>
+#define SND_MIXER_ID_3D_DEPTH "3D Depth"
+
+<p>
+#define SND_MIXER_ID_BASS "Bass"
+
+<p>
+#define SND_MIXER_ID_TREBLE "Treble"
+
+<p>
+#define SND_MIXER_ID_FADER "Fader"
+
+<p>
+#define SND_MIXER_ID_SYNTHESIZER "Synth"
+
+<p>
+#define SND_MIXER_ID_SYNTHESIZER1 "Synth 1"
+
+<p>
+#define SND_MIXER_ID_FM "FM"
+
+<p>
+#define SND_MIXER_ID_EFFECT "Effect"
+
+<p>
+#define SND_MIXER_ID_DSP "DSP"
+
+<p>
+#define SND_MIXER_ID_PCM "PCM"
+
+<p>
+#define SND_MIXER_ID_PCM1 "PCM 1"
+
+<p>
+#define SND_MIXER_ID_LINE "Line-In"
+
+<p>
+#define SND_MIXER_ID_MIC "MIC"
+
+<p>
+#define SND_MIXER_ID_CD "CD"
+
+<p>
+#define SND_MIXER_ID_VIDEO "Video"
+
+<p>
+#define SND_MIXER_ID_PHONE "Phone"
+
+<p>
+#define SND_MIXER_ID_GAIN "Record-Gain"
+
+<p>
+#define SND_MIXER_ID_MIC_GAIN "Mic-Gain"
+
+<p>
+#define SND_MIXER_ID_IGAIN "In-Gain"
+
+<p>
+#define SND_MIXER_ID_OGAIN "Out-Gain"
+
+<p>
+#define SND_MIXER_ID_LOOPBACK "Loopback"
+
+<p>
+#define SND_MIXER_ID_SPEAKER "PC Speaker"
+
+<p>
+#define SND_MIXER_ID_MONO "Mono"
+
+<p>
+#define SND_MIXER_ID_MONO1 "Mono 1"
+
+<p>
+#define SND_MIXER_ID_MONO2 "Mono 2"
+
+<p>
+#define SND_MIXER_ID_AUXA "Aux A"
+
+<p>
+#define SND_MIXER_ID_AUXB "Aux B"
+
+<p>
+#define SND_MIXER_ID_AUXC "Aux C"
+</DL>
+<p>
+
+<H4>int snd_mixer_channel_info(void *handle, int channel, snd_mixer_channel_info_t
+*info) </H4>
+
+<p>
+Fills the <i>*info</i> structure. The argument <i>channel</i> specifies
+channel (0 to N) for which is the info requested. Function returns zero if successful,
+otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+<i>/* mixer channel is record source */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_RECORD 0x00000001
+
+<p>
+<i>/* mixer channel is stereo */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_STEREO 0x00000002
+
+<p>
+<i>/* always set at this moment driver emulates mute */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_MUTE 0x00000004
+
+<p>
+<i>/* channel supports hardware mute */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_HWMUTE 0x00000008
+
+<p>
+<i>/* channel does digital (not analog) mixing */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_DIGITAL 0x00000010
+
+<p>
+<i>/* external input channel */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_INPUT 0x00000020
+
+<p>
+<i>/* join mute is supported only */</i>
+
+<p>
+<i>/* left and right channel doesn't have separate mute control */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_JOINMUTE 0x00000040
+
+<p>
+<i>/* join record is supported only *</i>
+
+<p>
+<i>/* left and right channel doesn't have separate record control */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_JOINRECORD 0x00000080
+
+<p>
+<i>/* route left input to right output is supported */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_LTOR_OUT 0x00000100
+
+<p>
+<i>/* route right input to left output is supported */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_RTOL_OUT 0x00000200
+
+<p>
+<i>/* route left input to right ADC is supported */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_LTOR_IN 0x00000400
+
+<p>
+<i>/* route right input to left ADC is supported */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_RTOL_IN 0x00000800
+
+<p>
+<i>/* output route is only switch (cannot be used separately) */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_SWITCH_OUT 0x00001000
+
+<p>
+<i>/* input route is only switch (cannot be used separately) */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_SWITCH_IN 0x00002000
+
+<p>
+<i>/* data can be recorded even if output path is muted */</i>
+
+<p>
+<i>/* (to avoid loopback) */</i>
+
+<p>
+#define SND_MIXER_CINFO_CAP_RECORDBYMUTE 0x00004000
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_mixer_channel_info {
+
+<p>
+<i> /* channel index (filled by application) */</i>
+
+<p>
+ unsigned int channel;
+
+<p>
+<i> /* parent channel # or SND_MIXER_PARENT */</i>
+
+<p>
+ unsigned int parent;
+
+<p>
+<i> /* name of this device */</i>
+
+<p>
+ unsigned char name[12];
+
+<p>
+<i> /* some flags about this device (SND_MIXER_CINFO_XXXX) */</i>
+
+<p>
+ unsigned int caps;
+
+<p>
+<i> /* min. value when exact mode (or always 0) */</i>
+
+<p>
+ int min;
+
+<p>
+<i> /* max. value when exact mode (or always 100) */ </i>
+
+<p>
+ int max;
+
+<p>
+<i> /* minimum decibel value (*100) */</i>
+
+<p>
+ int min_dB;
+
+<p>
+<i> /* maximum decibel value (*100) */</i>
+
+<p>
+ int max_dB;
+
+<p>
+<i> /* step decibel value (*100) */</i>
+
+<p>
+ int step_dB;
+
+<p>
+<i> /* reserved for future use */</i>
+
+<p>
+ unsigned char reserved[16];
+
+<p>
+};
+</DL>
+<p>
+
+<H4>int snd_mixer_channel_read(void *handle, int channel, snd_mixer_channel_t
+*data) </H4>
+
+<p>
+Fills the <i>*data</i> structure. The argument <i>channel</i> specifies
+the channel (0 to N) for which is data requested. Function returns zero if successful,
+otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+/* channel record source flags */
+
+<p>
+#define SND_MIXER_FLG_RECORD_LEFT 0x00000001
+
+<p>
+#define SND_MIXER_FLG_RECORD_RIGHT 0x00000002
+
+<p>
+#define SND_MIXER_FLG_RECORD 0x00000003
+
+<p>
+/* mute channel flags */
+
+<p>
+#define SND_MIXER_FLG_MUTE_LEFT 0x00010000
+
+<p>
+#define SND_MIXER_FLG_MUTE_RIGHT 0x00020000
+
+<p>
+#define SND_MIXER_FLG_MUTE 0x00030000
+
+<p>
+/* input to output route setup */
+
+<p>
+#define SND_MIXER_FLG_LTOR_OUT 0x00100000
+
+<p>
+#define SND_MIXER_FLG_RTOL_OUT 0x00200000
+
+<p>
+#define SND_MIXER_FLG_SWITCH_OUT 0x00300000
+
+<p>
+/* input to ADC route setup */
+
+<p>
+#define SND_MIXER_FLG_LTOR_IN 0x00400000
+
+<p>
+#define SND_MIXER_FLG_RTOL_IN 0x00800000
+
+<p>
+#define SND_MIXER_FLG_SWITCH_IN 0x00c00000
+
+<p>
+/* set volume in decibels from dB variables */
+
+<p>
+#define SND_MIXER_FLG_DECIBEL 0x40000000
+
+<p>
+/* reserved for kernel use, don't use this flag from application */
+
+<p>
+#define SND_MIXER_FLG_FORCE 0x80000000
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_mixer_channel {
+
+<p>
+ /* channel # (filled by application) */
+
+<p>
+ unsigned int channel;
+
+<p>
+ /* some flags to read/write (SND_MIXER_FLG_XXXX) */
+
+<p>
+ unsigned int flags;
+
+<p>
+ /* min - max when exact mode (or 0 - 100) */
+
+<p>
+ int left;
+
+<p>
+ /* min - max when exact mode (or 0 - 100) */
+
+<p>
+ int right;
+
+<p>
+ /* dB * 100 */
+
+<p>
+ int left_dB;
+
+<p>
+ /* dB * 100 */
+
+<p>
+ int right_dB;
+
+<p>
+ unsigned char reserved[16];
+
+<p>
+};
+</DL>
+<p>
+
+<H4>int snd_mixer_channel_write(void *handle, int channel, snd_mixer_channel_t
+*data)</H4>
+
+<p>
+Writes the <i>*data</i> structure to kernel. The <i>channel</i> argument
+specifies the channel (0 to N) for which is data is to be applied. Function
+returns zero if successful, otherwise it returns an error code. This functions
+is the opposite of <i>snd_mixer_channel_read</i>.
+
+<p>
+
+<H4>int snd_mixer_read(void *handle, snd_mixer_callbacks_t *callbacks)</H4>
+
+<p>
+This function reads and parses data from driver. Parsed actions are returned
+back to the application using the <i>callbacks</i> structure. Applications
+should not parse data from the driver in standard cases. This function returns
+immediately after all data is read from driver. Does not block process.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+typedef struct snd_mixer_callbacks {
+
+<p>
+ /* should be used by application */
+
+<p>
+ void *private_data;
+
+<p>
+ void (*channel_was_changed)(void *private_data, int channel);
+
+<p>
+ void (*switch_was_changed)(void *private_data, int switchn);
+
+<p>
+ /* reserved for future use - must be NULL!!! */
+
+<p>
+ void *reserved[14];
+
+<p>
+} snd_mixer_callbacks_t;
+</DL>
+<p>
+ <H4><A NAME="tth_sEc4.1.1">
+4.1.1</A> Examples</H4>
+
+<p>
+The following example shows installed mixer channels for sound card #0 and
+mixer device #0 in the system, and also sets the master volume (if present)
+to 50.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+int card = 0, device = 0, err;
+
+<p>
+void *handle;
+
+<p>
+snd_mixer_info_t info;
+
+<p>
+snd_mixer_channel_t channel;
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+if ((err = snd_mixer_open(&handle, card, device)) < 0) {
+
+<p>
+ fprintf(stderr, "open failed: %s\n", snd_strerror(err));
+
+<p>
+ return;
+
+<p>
+}
+
+<p>
+if ((err = snd_mixer_info(handle, &info)) < 0) {
+
+<p>
+ fprintf(stderr, "info failed: %s\n", snd_strerror(err));
+
+<p>
+ snd_mixer_close(handle);
+
+<p>
+ return;
+
+<p>
+}
+
+<p>
+printf("Installed MIXER channels for card #i and device %i: %i\n", card + 1, device,
+
+<p>
+ info.channels);
+
+<p>
+master = snd_mixer_channel(handle, SND_MIXER_ID_MASTER);
+
+<p>
+if (master >= 0) {
+
+<p>
+ if ((err = snd_mixer_read(handle, master, &channel)) < 0) { fprintf(stderr, "master read failed: %s\n", snd_strerror( err ));
+
+<p>
+ snd_mixer_close( handle );
+
+<p>
+ return;
+
+<p>
+ }
+
+<p>
+ channel.left = channel.right = 50;
+
+<p>
+ if ((err = snd_mixer_write(handle, master, &channel)) < 0 ) { fprintf(stderr, "master write failed: %s\n", snd_strerror( err ));
+
+<p>
+ snd_mixer_close(handle);
+
+<p>
+ return;
+
+<p>
+ }
+
+<p>
+}
+
+<p>
+snd_mixer_close(handle);
+</DL>
+<p>
+ <H2><A NAME="tth_sEc5">
+5</A> Digital Audio (PCM) Interface</H2>
+
+<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 8 kHz (telephone quality) and 48 kHz (DAT tapes).
+
+<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>
+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 DAC.
+
+<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 * 6 dB . This means that 8 bits
+sampling resolution gives dynamic range of 48 dB and 16 bit resolution gives
+96 dB.
+
+<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 8 kHz/8
+bits/mono but 48 kHz/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.5 Mbps 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>
+ <H3><A NAME="tth_sEc5.1">
+5.1</A> Low-Level Layer</H3>
+
+<p>
+Audio devices are opened exclusively for a selected direction. This doesn't
+allow open from more than one processes for the same audio device in the same
+direction, but does allow one open call to each playback direction and second
+open call to record direction independently. Audio devices return EBUSY error
+to applications when other applications have already opened the requested direction.
+
+<p>
+Low-Level layer supports these formats:
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+<i>/* muLaw compressed samples */</i>
+
+<p>
+#define SND_PCM_SFMT_MU_LAW 0
+
+<p>
+<i>/* aLaw compressed samples */</i>
+
+<p>
+#define SND_PCM_SFMT_A_LAW 1
+
+<p>
+<i>/* Ima-ADPM 4:1 compressed samples */</i>
+
+<p>
+#define SND_PCM_SFMT_IMA_ADPCM 2
+
+<p>
+<i>/* Unsigned 8-bit samples (most common 8-bit format) */</i>
+
+<p>
+#define SND_PCM_SFMT_U8 3
+
+<p>
+<i>/* Signed 16-bit Little Endian samples (most common 16-bit format) */</i>
+
+<p>
+#define SND_PCM_SFMT_S16_LE 4
+
+<p>
+<i>/* Signed 16-bit Big Endian samples */</i>
+
+<p>
+#define SND_PCM_SFMT_S16_BE 5
+
+<p>
+<i>/* Signed 8-bit samples */</i>
+
+<p>
+#define SND_PCM_SFMT_S8 6
+
+<p>
+<i>/* Unsigned 16-bit Little Endian samples */</i>
+
+<p>
+#define SND_PCM_SFMT_U16_LE 7
+
+<p>
+<i>/* Unsigned 16-bit Big Endian samples */</i>
+
+<p>
+#define SND_PCM_SFMT_U16_BE 8
+
+<p>
+<i>/* MPEG 1/2 stream */</i>
+
+<p>
+#define SND_PCM_SFMT_MPEG 9
+
+<p>
+<i>/* GSM stream */</i>
+
+<p>
+#define SND_PCM_SFMT_GSM 10
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+#define SND_PCM_FMT_MU_LAW (1 << SND_PCM_SFMT_MU_LAW)
+
+<p>
+#define SND_PCM_FMT_A_LAW (1 << SND_PCM_SFMT_A_LAW)
+
+<p>
+#define SND_PCM_FMT_IMA_ADPCM (1 << SND_PCM_SFMT_IMA_ADPCM)
+
+<p>
+#define SND_PCM_FMT_U8 (1 << SND_PCM_SFMT_U8)
+
+<p>
+#define SND_PCM_FMT_S16_LE (1 << SND_PCM_SFMT_S16_LE)
+
+<p>
+#define SND_PCM_FMT_S16_BE (1 << SND_PCM_SFMT_S16_BE)
+
+<p>
+#define SND_PCM_FMT_S8 (1 << SND_PCM_SFMT_S8)
+
+<p>
+#define SND_PCM_FMT_U16_LE (1 << SND_PCM_SFMT_U16_LE)
+
+<p>
+#define SND_PCM_FMT_U16_BE (1 << SND_PCM_SFMT_U16_BE)
+
+<p>
+#define SND_PCM_FMT_MPEG (1 << SND_PCM_SFMT_MPEG)
+
+<p>
+#define SND_PCM_FMT_GSM (1 << SND_PCM_SFMT_GSM)
+</DL>
+<p>
+Constants with prefix <i>SND_PCM_FMT_</i> are used in info structures and
+constants with prefix <i>SND_PCM_SFMT_</i> are used in format structures.
+
+<p>
+ALSA PCM API uses an enhanced double buffering scheme. This allows the user
+to implement a more comfortable buffer setup. Audio buffer is separated to small
+fragments. Each fragment has the same size. Application can set wakeup limits
+like ``I want to get recorded data when at least two fragments with size 160
+bytes are filled.''. For more information you should see description of <i>snd_pcm_*_params_t</i>
+and <i>snd_pcm_*_status_t</i> structures and the <em>snd_pcm_playback_status(),
+snd_pcm_record_status()</em> functions, documented below.
+
+<p>
+
+<H4>int snd_pcm_open(void **handle, int card, int device, int mode)</H4>
+
+<p>
+Creates a new handle and opens a connection to the kernel sound audio interface
+for sound card number <i>card</i> (0-N) and audio device number <i>device</i>.
+Function also checks if protocol is compatible to prevent use of old programs
+with a new kernel API. Function returns zero if successful otherwise it returns
+an error code. Error code -EBUSY is returned when some process owns the selected
+direction.
+
+<p>
+Default format after opening is mono <i>mu-Law</i> at 8000Hz. This device
+can be used directly for playback of standard .au (Sparc) files.
+
+<p>
+The following modes should be used for the <i>mode</i> argument:
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+#define SND_PCM_OPEN_PLAYBACK (O_WRONLY)
+
+<p>
+#define SND_PCM_OPEN_RECORD (O_RDONLY)
+
+<p>
+#define SND_PCM_OPEN_DUPLEX (O_RDWR)
+</DL>
+<p>
+
+<H4>int snd_pcm_close(void *handle)</H4>
+
+<p>
+Frees all resources allocated with audio handle and closes the connection to
+the kernel sound audio interface. Function returns zero if successful, otherwise
+it returns an error code.
+
+<p>
+
+<H4>int snd_pcm_file_descriptor(void *handle)</H4>
+
+<p>
+Returns the file descriptor of the connection to the kernel sound audio interface.
+Function returns an error code if an error was encountered.
+
+<p>
+The file descriptor should be used for the <i>select(2)</i> synchronous multiplexer
+function for setting the read direction. Application should call <i>snd_pcm_read()</i>
+or <i>snd_pcm_write()</i> functions if data is waiting to be read or a write
+can be performed. Calling these functions is highly recommended, as it leaves
+a place for the API to do things like data conversions, if needed.
+
+<p>
+
+<H4>int snd_pcm_block_mode(void *handle, int enable) </H4>
+
+<p>
+Sets up block (default) or non-block mode for a handle. Block mode suspends
+execution of a program when <i>snd_pcm_read()</i> or <i>snd_pcm_write()</i>
+is called for the time which is needed for the actual playback or record over
+of the selected limit. In non-block mode, programs aren't suspended and the
+above functions return immediately with the count of bytes which were read or
+written by the driver. When used in this way, don't try to use the entire buffer
+after the call, but instead process the number of bytes returned, and call the
+function again.
+
+<p>
+
+<H4>int snd_pcm_info(void *handle, snd_pcm_info_t *info)</H4>
+
+<p>
+Fills the <i>*info</i> structure with data about the PCM device selected
+by <i>*handle</i>. Function returns zero if successful, otherwise it returns
+an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+<i>/* hardware have codec */</i>
+
+<p>
+#define SND_PCM_INFO_CODEC 0x00000001
+
+<p>
+#define SND_PCM_INFO_DSP SND_PCM_INFO_CODEC
+
+<p>
+<i>/* this flag is reserved and should be never used */</i>
+
+<p>
+<i>/* It remains for compatibility with Open Sound System driver. */</i>
+
+<p>
+#define SND_PCM_INFO_MMAP 0x00000002
+
+<p>
+<i>/* playback direction is supported */</i>
+
+<p>
+#define SND_PCM_INFO_PLAYBACK 0x00000100
+
+<p>
+<i>/* record direction is supported */</i>
+
+<p>
+#define SND_PCM_INFO_RECORD 0x00000200
+
+<p>
+#define SND_PCM_INFO_DUPLEX 0x00000400
+
+<p>
+<i>/* rate for playback & record must be same */</i>
+
+<p>
+#define SND_PCM_INFO_DUPLEX_LIMIT 0x00000800
+
+<p>
+<i>/* duplex is supported only by mono (one channel) format */</i>
+
+<p>
+#define SND_PCM_INFO_DUPLEX_MONO 0x00001000
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_pcm_info {
+
+<p>
+<i> /* sound card type */</i>
+
+<p>
+ unsigned int type;
+
+<p>
+<i> /* see SND_PCM_INFO_XXXX */</i>
+
+<p>
+ unsigned int flags;
+
+<p>
+<i> /* ID of this PCM device */</i>
+
+<p>
+ unsigned char id[32];
+
+<p>
+<i> /* name of this device */</i>
+
+<p>
+ unsigned char name[80];
+
+<p>
+<i> /* reserved for future use */</i>
+
+<p>
+ unsigned char reserved[64];
+
+<p>
+};
+</DL>
+<p>
+
+<H4>int snd_pcm_playback_info(void *handle, snd_pcm_playback_info_t *info)</H4>
+
+<p>
+Fills the *info structure with data about PCM playback. Function returns zero
+if successful, otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+#define SND_PCM_PINFO_BATCH 0x00000001
+
+<p>
+#define SND_PCM_PINFO_8BITONLY 0x00000002
+
+<p>
+#define SND_PCM_PINFO_16BITONLY 0x00000004
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_pcm_playback_info {
+
+<p>
+<i> /* see SND_PCM_PINFO_XXXX */</i>
+
+<p>
+ unsigned int flags;
+
+<p>
+<i> /* supported formats */ </i>
+
+<p>
+ unsigned int formats;
+
+<p>
+<i> /* min rate (in Hz) */ </i>
+
+<p>
+ unsigned int min_rate;
+
+<p>
+<i> /* max rate (in Hz) */ </i>
+
+<p>
+ unsigned int max_rate;
+
+<p>
+<i> /* min channels - voices (probably always 1) */ </i>
+
+<p>
+ unsigned int min_channels;
+
+<p>
+<i> /* max channels - voices */ </i>
+
+<p>
+ unsigned int max_channels;
+
+<p>
+<i> /* playback buffer size in bytes */</i>
+
+<p>
+ unsigned int buffer_size;
+
+<p>
+<i> /* min fragment size in bytes */ </i>
+
+<p>
+ unsigned int min_fragment_size;
+
+<p>
+<i> /* max fragment size in bytes */</i>
+
+<p>
+ unsigned int max_fragment_size;
+
+<p>
+<i> /* align fragment value */</i>
+
+<p>
+ unsigned int fragment_align;
+
+<p>
+<i> /* supported formats directly by hardware */</i>
+
+<p>
+ unsigned int hw_formats;
+
+<p>
+<i> /* count of playback switches */</i>
+
+<p>
+ unsigned int switches;
+
+<p>
+<i> /* reserved for future use */</i>
+
+<p>
+ unsigned char reserved[56];
+
+<p>
+};
+</DL>
+<p>
+
+<DL compact><dt><b></b></dt>
+ <dd> [SND_PCM_PINFO_BATCH]Driver implements double buffering with this device.
+This means that the chip used for data processing has its own memory, and output
+will be more delayed than if a traditional codec chip is used.
+<dt><b></b></dt>
+ <dd> [SND_PCM_PINFO_8BITONLY]If this bit is set, the driver uses 8-bit format
+for 16-bit samples and does software conversion. This bit is set on broken SoundBlaster
+16/AWE sound cards which can't do full 16-bit duplex. If this bit is set application
+or higher digital audio layer should do the conversion from 16-bit samples to
+8-bit samples rather than making the driver to do it in the kernel.
+<dt><b></b></dt>
+ <dd> [SND_PCM_PINFO_16BITONLY]If this bit is set, driver uses 16-bit format for
+8-bit samples and does software conversion. This bit is set on broken SoundBlaster
+16/AWE sound cards which can't do full 8-bit duplex. If this bit is set the
+application or higher digital audio layer should do conversion from 8-bit samples
+to 16-bit samples rather than making the driver to do it in the kernel.
+</DL>
+<p>
+
+<H4>int snd_pcm_record_info(void *handle, snd_pcm_record_info_t *info)</H4>
+
+<p>
+Fills the *info structure. Returns zero if successful, otherwise it returns
+an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+#define SND_PCM_RINFO_BATCH 0x00000001
+
+<p>
+#define SND_PCM_RINFO_8BITONLY 0x00000002
+
+<p>
+#define SND_PCM_RINFO_16BITONLY 0x00000004
+
+<p>
+#define SND_PCM_RINFO_OVERRANGE 0x00001000
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_pcm_record_info {
+
+<p>
+<i> /* see SND_PCM_RINFO_XXXX */</i>
+
+<p>
+ unsigned int flags;
+
+<p>
+<i> /* supported formats */ </i>
+
+<p>
+ unsigned int formats;
+
+<p>
+<i> /* min rate (in Hz) */ </i>
+
+<p>
+ unsigned int min_rate;
+
+<p>
+<i> /* max rate (in Hz) */ </i>
+
+<p>
+ unsigned int max_rate;
+
+<p>
+<i> /* min channels - voices (probably always 1) */ </i>
+
+<p>
+ unsigned int min_channels;
+
+<p>
+<i> /* max channels - voices */ </i>
+
+<p>
+ unsigned int max_channels;
+
+<p>
+<i> /* playback buffer size in bytes */</i>
+
+<p>
+ unsigned int buffer_size;
+
+<p>
+<i> /* min fragment size in bytes */ </i>
+
+<p>
+ unsigned int min_fragment_size;
+
+<p>
+<i> /* max fragment size in bytes */</i>
+
+<p>
+ unsigned int max_fragment_size;
+
+<p>
+<i> /* align fragment value */</i>
+
+<p>
+ unsigned int fragment_align;
+
+<p>
+<i> /* supported formats directly by hardware */</i>
+
+<p>
+ unsigned int hw_formats;
+
+<p>
+<i> /* count of record switches */</i>
+
+<p>
+ unsigned int switches;
+
+<p>
+<i> /* reserved for future use */</i>
+
+<p>
+ unsigned char reserved[56];
+
+<p>
+};
+</DL>
+<p>
+
+<DL compact><dt><b></b></dt>
+ <dd> [SND_PCM_RINFO_BATCH]Driver implements double buffering with this device.
+This means that the chip used for data processing has its own memory, and input
+will be more delayed than if a traditional codec chip is used.
+<dt><b></b></dt>
+ <dd> [SND_PCM_RINFO_8BITONLY]If this bit is set, the driver uses 8-bit format
+for 16-bit samples and does software conversion. This bit is set on broken SoundBlaster
+16/AWE sound cards which can't do full 16-bit duplex. If this bit is set application
+or higher digital audio layer should do the conversion from 16-bit samples to
+8-bit samples rather than making the driver to do it in the kernel.
+<dt><b></b></dt>
+ <dd> [SND_PCM_RINFO_16BITONLY]If this bit is set, driver uses 16-bit format for
+8-bit samples and does software conversion. This bit is set on broken SoundBlaster
+16/AWE sound cards which can't do full 8-bit duplex. If this bit is set the
+application or higher digital audio layer should do conversion from 8-bit samples
+to 16-bit samples rather than making the driver to do it in the kernel.
+<dt><b></b></dt>
+ <dd> [SND_PCM_RINFO_OVERRANGE]If this bit is set the hardware can do ADC
+over-range detection.
+</DL>
+<p>
+
+<H4>int snd_pcm_playback_switches(void *handle)</H4>
+
+<p>
+Returns count of PCM playback switches. In this contents switch means universal
+control interface between kernel and application which allows variable type
+control. Function returns count if successful, otherwise it returns an error
+code. Return value should be zero if sound card doesn't have any PCM playback
+switch.
+
+<p>
+
+<H4>int snd_pcm_playback_switch(void *handle, const char *switch_id)</H4>
+
+<p>
+Returns index for switch with name <i>switch_id</i>. Function returns switch
+index if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_pcm_playback_switch_read(void *handle int switchnsnd_pcm_switch_t *data)</H4>
+
+<p>
+Fills the <i>*data</i> structure with data about switch with index <i>switchn</i>.
+Function returns zero if successful, otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+<i>/* 0 or 1 (enable member of union) */</i>
+
+<p>
+#define SND_PCM_SW_TYPE_BOOLEAN 0
+
+<p>
+<i>/* 0 to 255 - from low to high (data8[0] member of union) */</i>
+
+<p>
+#define SND_PCM_SW_TYPE_BYTE 1
+
+<p>
+<i>/* 0 to 65535 - from low to high (data16[0] member of union) */</i>
+
+<p>
+#define SND_PCM_SW_TYPE_WORD 2
+
+<p>
+<i>/* 0 to 4294967296 ¯ from low to high (data32[0] member of union) */</i>
+
+<p>
+#define SND_PCM_SW_TYPE_DWORD 3
+
+<p>
+<i>/* user type - no type control */</i>
+
+<p>
+#define SND_PCM_SW_TYPE_USER (~0)
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_pcm_switch {
+
+<p>
+ <i>/* switch index (filled by application) */</i>
+
+<p>
+ unsigned int switchn;
+
+<p>
+ <i>/* identification of switch (for driver) */</i>
+
+<p>
+ unsigned char name[32];
+
+<p>
+ <i>/* type of switch value ¯ See SND_PCM_SW_TYPE_XXXX */</i>
+
+<p>
+ unsigned int type;
+
+<p>
+ <i>/* low range value */</i>
+
+<p>
+ unsigned int low;
+
+<p>
+ <i>/* high range value */</i>
+
+<p>
+ unsigned int high;
+
+<p>
+ union {
+
+<p>
+ unsigned int enable; <i>/* 0 = off 1 = on */</i>
+
+<p>
+ unsigned char data8[32]; <i>/* 8-bit data */</i>
+
+<p>
+ unsigned short data16[16]; <i>/* 16-bit data */</i>
+
+<p>
+ unsigned int data32[8]; <i>/* 32-bit data */</i>
+
+<p>
+ } value;
+
+<p>
+ <i>/* reserved for future use ¯ must be zero !!! */</i>
+
+<p>
+ unsigned char reserved[32];
+
+<p>
+}
+</DL>
+<p>
+
+<H4>int snd_pcm_playback_switch_write(void *handle int switchnsnd_pcm_switch_t *data)</H4>
+
+<p>
+Writes the <i>*data</i> structure with data about switch with index <i>switchn</i>
+to kernel. Function returns zero if successful, otherwise it returns an error
+code.
+
+<p>
+
+<H4>int snd_pcm_record_switches(void *handle)</H4>
+
+<p>
+Returns count of PCM record switches. In this context 'switch' means universal
+control interface between kernel and application which allows various types
+of control. Function returns count if successful, otherwise it returns an error
+code. Return value should be zero if sound card doesn't have any PCM record
+switch.
+
+<p>
+
+<H4>int snd_pcm_record_switch(void *handle, const char *switch_id)</H4>
+
+<p>
+Returns index for switch with name <i>switch_id</i>. Function returns switch
+index if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_pcm_record_switch_read(void *handle int switchn snd_pcm_switch_t
+*data)</H4>
+
+<p>
+Fills the <i>*data</i> structure with data about switch with index <i>switchn</i>.
+Function returns zero if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_pcm_record_switch_write(void *handle int switchnsnd_pcm_switch_t *data)</H4>
+
+<p>
+Writes the <i>*data</i> structure with data about switch with index <i>switchn</i>
+to kernel. Function returns zero if successful, otherwise it returns an error
+code.
+
+<p>
+
+<H4>int snd_pcm_playback_format(void *handle, snd_pcm_format_t *format)</H4>
+
+<p>
+Sets up format, rate (in Hz) and number of channels for playback, in the desired
+direction. Function returns zero if successful, otherwise it returns an error
+code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_pcm_format {
+
+<p>
+ unsigned int format; <i>/* SND_PCM_SFMT_XXXX */</i>
+
+<p>
+ unsigned int rate; <i>/* rate in Hz */</i>
+
+<p>
+ unsigned int channels; <i>/* channels (voices) */</i>
+
+<p>
+ unsigned char reserved[16];
+
+<p>
+};
+</DL>
+<p>
+
+<H4>int snd_pcm_record_format(void *handle, snd_pcm_format_t *format) </H4>
+
+<p>
+Sets up format, rate (in Hz) and number of channels for used for recording in
+the specified direction. Function returns zero if successful, otherwise it returns
+an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_pcm_format {
+
+<p>
+ unsigned int format; <i>/* SND_PCM_SFMT_XXXX */</i>
+
+<p>
+ unsigned int rate; <i>/* rate in Hz */</i>
+
+<p>
+ unsigned int channels; <i>/* channels (voices) */</i>
+
+<p>
+ unsigned char reserved[16];
+
+<p>
+};
+</DL>
+<p>
+
+<H4>int snd_pcm_playback_params(void *handle, snd_pcm_playback_params_t
+*params)</H4>
+
+<p>
+Sets various parameters for playback direction. Function returns zero if successful,
+otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_pcm_playback_params {
+
+<p>
+ int fragment_size;
+
+<p>
+ int fragments_max;
+
+<p>
+ int fragments_room;
+
+<p>
+<i> /* reserved for future use - must be filled with zero */</i>
+
+<p>
+ unsigned char reserved[16];
+
+<p>
+};
+</DL>
+<p>
+
+<DL compact><dt><b></b></dt>
+ <dd> [fragment_size]Requested size of fragment. This value should be aligned for
+current format (for example to 4 if stereo 16-bit samples are used) or with
+the <i>fragment_align</i> variable from <i>snd_pcm_playback_info_t</i>
+structure. Its range can be from <i>min_fragment_size</i> to <i>max_fragment_size</i>.
+<dt><b></b></dt>
+ <dd> [fragments_max]Maximum number of fragments in queue for wakeup. This number
+doesn't include partly used fragments. If the current count of filled playback
+fragments is greater than this value the driver will block the application or
+return immediately back if non-block mode is active.
+<dt><b></b></dt>
+ <dd> [fragments_room]Minimum number of fragments writable for wakeup. This value
+should in most cases be 1 which means return back to application if at least
+one fragment is free for playback. This value includes partly used fragments,
+too.
+</DL>
+<p>
+
+<H4>int snd_pcm_record_params(void *handle, snd_pcm_record_params_t *params)</H4>
+
+<p>
+Function sets various parameters for the recording direction. Function returns
+zero if successful, otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_pcm_record_params {
+
+<p>
+ int fragment_size;
+
+<p>
+ int fragments_min;
+
+<p>
+<i> /* reserved for future use - must be filled with zero */</i>
+
+<p>
+ unsigned char reserved[16];
+
+<p>
+};
+</DL>
+<p>
+
+<DL compact><dt><b></b></dt>
+ <dd> [fragment_size]Requested size of fragment. This value should be aligned for
+current format (for example to 4 if stereo 16-bit samples are used) or set to
+the <i>fragment_align</i> variable from <i>snd_pcm_playback_info_t</i>
+structure. Its range can be from <i>min_fragment_size</i> to <i>max_fragment_size</i>.
+<dt><b></b></dt>
+ <dd> [fragments_min]Minimum filled fragments for wakeup. Driver blocks the application
+(if block mode is selected) until input buffer is filled with less than the
+number of fragments specified with this value.
+</DL>
+<p>
+
+<H4>int snd_pcm_playback_status(void *handle, snd_pcm_playback_status_t
+*status)</H4>
+
+<p>
+Fills the <i>*status</i> structure. Function returns zero if successful,
+otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_pcm_playback_status {
+
+<p>
+ unsigned int rate;
+
+<p>
+ int fragments;
+
+<p>
+ int fragment_size;
+
+<p>
+ int count;
+
+<p>
+ int queue;
+
+<p>
+ int underrun;
+
+<p>
+ struct timeval time;
+
+<p>
+ struct timeval stime;
+
+<p>
+ int scount;
+
+<p>
+<i> /* reserved for future use - must be filled with zero */</i>
+
+<p>
+ unsigned char reserved[16];
+
+<p>
+};
+</DL>
+<p>
+
+<DL compact><dt><b></b></dt>
+ <dd> [rate]Real playback rate. This value reflects hardware limitations.
+<dt><b></b></dt>
+ <dd> [fragments]Currently allocated fragments by the driver for playback direction.
+<dt><b></b></dt>
+ <dd> [fragment_size]Current fragment size used by driver for the playback direction.
+<dt><b></b></dt>
+ <dd> [count]Count of bytes writable without blocking.
+<dt><b></b></dt>
+ <dd> [queue]Count of bytes in queue. Note: <i>(fragments*fragment_size) -
+queue</i> should not be equal to <i>count</i>.
+<dt><b></b></dt>
+ <dd> [underrun]This value tells the application the number of underruns since the
+last call to <i>snd_pcm_playback_status</i><em>()</em>.
+<dt><b></b></dt>
+ <dd> [time]Estimated time when the next written sample will actually be played (time
+is always in the future). The estimate is calculated with: current time + sample
+queue <em></em>converted to time (number of samples waiting for write to device,
+i.e., the same as the <em>queue</em> member above). This value should be used
+for time synchronization. Returned value is in the same format as returned from
+the standard C function <em>gettimeofday</em>(&<em>time</em>, <em>NULL</em>). This
+variable contains valid information only if playback time mode is enabled (see
+<i>snd_pcm_playback_time()</i> function).
+<dt><b></b></dt>
+ <dd> [stime]Time when playback was started. This variable contains valid information
+only if playback time mode is enabled (see <i>snd_pcm_playback_time()</i>
+function).
+<dt><b></b></dt>
+ <dd> [scount]Number of bytes processed (actually played) from playback start. This
+number is not necessarily the same as byte count written by application.
+</DL>
+<p>
+ <center><img src="pcmbuf.gif">
+<p>
+</center> The figure above shows an example situation in the audio playback buffer in
+the ALSA driver. The driver splits the audio buffer into 16 <em>fragments</em>,
+each being <em>fragment_size</em> bytes long. Fragments 0 and 12-15 are filled
+with samples. Fragment 1 is filled partly (about 75%). Driver is playing and
+current playback position is in fragment 12 (about 35%). As you can seefree space (structure member <i>count</i>) is counted without including the
+fragment which is being played.
+
+<p>
+
+<H4>int snd_pcm_record_status(void *handle, snd_pcm_record_status_t *status)</H4>
+
+<p>
+Fills the <i>*status</i> structure. Function returns zero if successful,
+otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_pcm_record_status {
+
+<p>
+ unsigned int rate;
+
+<p>
+ int fragments;
+
+<p>
+ int fragment_size;
+
+<p>
+ int count;
+
+<p>
+ int free;
+
+<p>
+ int overrun;
+
+<p>
+ struct timeval time;
+
+<p>
+ struct timeval stime;
+
+<p>
+ int scount;
+
+<p>
+ int overrange;
+
+<p>
+<i> /* reserved for future use - must be filled with zero */</i>
+
+<p>
+ unsigned char reserved[16];
+
+<p>
+};
+</DL>
+<p>
+
+<DL compact><dt><b></b></dt>
+ <dd> [rate]Real record rate. This value reflects hardware limitations.
+<dt><b></b></dt>
+ <dd> [fragments]Currently allocated fragments by driver for the record direction.
+<dt><b></b></dt>
+ <dd> [fragment_size]Current fragment size used by driver for the record direction.
+<dt><b></b></dt>
+ <dd> [count]Count of bytes readable without blocking.
+<dt><b></b></dt>
+ <dd> [free]Count of bytes in buffer still free. Note: <i>(fragments*fragment_size)
+- free</i> should not be equal to <i>count</i>.
+<dt><b></b></dt>
+ <dd> [overrun]This value tells application the count of overruns since the last call
+to <i>snd_pcm_record_status</i>.
+<dt><b></b></dt>
+ <dd> [time]Returns a timestamp for the next sample to be read from the record ring
+buffer (time is always in the past). The timestamp is calculated with: current
+time - sample queue converted to time (waiting for application read() + current
+position in fragment is the same as record count + current position in fragment).
+This value should be used for time synchronization. Returned value is in the
+same format as returned by the standard C function gettimeofday(&time, NULL).
+This variable contains right valid information only if record time mode is enabled
+(see <i>snd_pcm_record_time()</i> function).
+<dt><b></b></dt>
+ <dd> [stime]Time when record was started. This variable contains valid information
+only if record time mode is enabled (see <i>snd_pcm_record_time</i> function).
+<dt><b></b></dt>
+ <dd> [scount]Number of bytes processed (actually recorded) from record start (stime).
+This number is not necessarily the same as the byte count read by application.
+<dt><b></b></dt>
+ <dd> [overrange]ADC overrange count. This value is used only when <i>SND_PCM_RINFO_OVERRANGE</i>
+bit in <i>struct snd_pcm_record_info_t->flags</i> is set (if hardware
+supports this feature).
+</DL>
+<p>
+ <center><img src="pcmbuf1.gif">
+<p>
+</center> The figure above shows an example situation in the audio record buffer in the
+ALSA driver. The driver splits the audio buffer into 16 <em>fragments</em>, each
+being <em>fragment_size</em> bytes in length. Fragments 0 and 12-15 are filled
+with samples. Fragment 1 is partly filled (about 75%) and at the end of the
+filled area is the active record position. Data which is ready for the application
+begins in fragment 12 (about 35%). As you can see free space (structure
+member <i>free</i>) is counted without including the fragment which is partly
+filled with samples and the application reads data from this fragment.
+
+<p>
+
+<H4>int snd_pcm_drain_playback(void *handle)</H4>
+
+<p>
+This function stops and drains (destroys) the playback buffers immediately.
+Function returns zero if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_pcm_flush_playback(void *handle)</H4>
+
+<p>
+This function flushes the playback buffers. It blocks the program while the
+all the waiting samples in kernel playback buffers are processed. Function returns
+zero if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_pcm_flush_record(void *handle)</H4>
+
+<p>
+This function flushes (destroys) record buffers. Function returns zero if successful,
+otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_pcm_playback_pause(void *handle int enable)</H4>
+
+<p>
+This function pauses playback if <i>enable</i> is non-zero. To restore playing
+mode call this function with <i>enable</i> equal to zero. Function returns
+zero if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_pcm_playback_time(void *handle, int enable)</H4>
+
+<p>
+This function enables or disables time mode for the playback direction. Time
+mode is useful in synchronizing an application with other events. Function returns
+zero if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_pcm_record_time(void *handle, int enable)</H4>
+
+<p>
+This function enables or disables time mode for record direction. Time mode
+is useful in synchronizing an application with other events. Function returns
+zero if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>ssize_t snd_pcm_write(void *handle, const void *buffer, size_t size)</H4>
+
+<p>
+Writes samples to the device which must be in the proper format specified by
+the <i>snd_pcm_playback_format</i> function. Function returns zero or positive
+value if playback was successful (value represents count of bytes which were
+successfully written to device) or an error value if an error occurred. Function
+will suspend process if block mode is active.
+
+<p>
+
+<H4>ssize_t snd_pcm_read(void *handle, void *buffer, size_t size)</H4>
+
+<p>
+Function reads samples from driver. Samples are in format specified by <i>snd_pcm_record_format</i>
+function. Function returns zero or positive value if record was success (value
+represents count of bytes which was successfully read from device) or negative
+error value if error occurred. Function will suspend process if block mode is
+active.
+
+<p>
+ <H4><A NAME="tth_sEc5.1.1">
+5.1.1</A> Example</H4>
+
+<p>
+The following example shows how to play the first 512kB from the /tmp/test.au
+file with sound card #0 and PCM device #0:
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+int card = 0, device = 0, err, fd, count, size, idx;
+
+<p>
+void *handle;
+
+<p>
+snd_pcm_format_t format;
+
+<p>
+char *buffer;
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+buffer = (char *)malloc(512 * 1024);
+
+<p>
+if (!buffer) return;
+
+<p>
+if ((err = snd_pcm_open(&handle, card, device,
+
+<p>
+ SND_PCM_OPEN_PLAYBACK)) < 0) {
+
+<p>
+ fprintf(stderr, "open failed: %s\n", snd_strerror( err ));
+
+<p>
+ return;
+
+<p>
+}
+
+<p>
+bzero(&format sizeof(format));
+
+<p>
+format.format = SND_PCM_SFMT_MU_LAW;
+
+<p>
+format.rate = 8000;
+
+<p>
+format.channels = 1;
+
+<p>
+if ((err = snd_pcm_playback_format(handle, &format)) < 0) {
+
+<p>
+ fprintf(stderr, "format setup failed: %s\n",
+
+<p>
+ snd_strerror( err ));
+
+<p>
+ snd_pcm_close( handle );
+
+<p>
+ return;
+
+<p>
+}
+
+<p>
+fd = open("/tmp/test.au", O_RDONLY);
+
+<p>
+if (fd < 0) {
+
+<p>
+ perror("open file");
+
+<p>
+ snd_pcm_close(handle);
+
+<p>
+ return;
+
+<p>
+}
+
+<p>
+idx = 0;
+
+<p>
+count = read(fd, buffer, 512 * 1024);
+
+<p>
+if (count <= 0) {
+
+<p>
+ perror("read from file");
+
+<p>
+ snd_pcm_close( handle );
+
+<p>
+ return;
+
+<p>
+}
+
+<p>
+close( fd );
+
+<p>
+if (!memcmp(buffer, ".snd", 4)) {
+
+<p>
+ idx = (buffer[4]<<24)|(buffer[5]<<16)|
+
+<p>
+ (buffer[6]<<8)|(buffer[7]);
+
+<p>
+ if (idx > 128) idx = 128;
+
+<p>
+ if (idx > count) idx = count;
+
+<p>
+}
+
+<p>
+size = snd_pcm_write(handle, &buffer[ idx ], count - idx);
+
+<p>
+printf("Bytes written %i from %i...\n", size, count - idx);
+
+<p>
+snd_pcm_close(handle);
+
+<p>
+free(buffer);
+</DL>
+<p>
+ <H3><A NAME="tth_sEc5.2">
+5.2</A> PCM Loopback Interface</H3>
+
+<p>
+This interface is designed to pass data currently being played or recorded from
+one application to another application for other processing like a graphical
+equalizer sample recorder etc... The programmer should be aware that each
+loopback connection eats CPU time (for data copying from the process which is
+doing the playback or record).
+
+<p>
+
+<H4>int snd_pcm_loopback_open(void **handle, int card, int device, int mode)</H4>
+
+<p>
+Creates a new handle and opens a connection to the kernel sound audio loopback
+interface for sound card number <i>card</i> (0-N) and audio device number
+<i>device</i>. Function also checks if protocol is compatible to prevent use
+of old programs with a new kernel API. Function returns zero if successful otherwise
+it returns an error code. Error code -EBUSY is returned when another process
+owns the selected direction.
+
+<p>
+The following modes should be used for the <i>mode</i> argument:
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+#define SND_PCM_LB_OPEN_PLAYBACK 0
+
+<p>
+#define SND_PCM_LB_OPEN_RECORD 1
+</DL>
+<p>
+
+<H4>int snd_pcm_loopback_close(void *handle)</H4>
+
+<p>
+Frees all resources allocated with audio handle and closes the connection to
+the kernel sound audio interface. Function returns zero if successful, otherwise
+it returns an error code.
+
+<p>
+
+<H4>int snd_pcm_loopback_file_descriptor(void *handle)</H4>
+
+<p>
+Returns the file descriptor of the connection to the kernel sound audio interface.
+Function returns an error code if an error was encountered.
+
+<p>
+The file descriptor should be used for the <i>select(2)</i> synchronous multiplexer
+function for setting the read direction. Application should call <i>snd_pcm_loopback_read()</i>
+function if data is waiting to be read.
+
+<p>
+
+<H4>int snd_pcm_loopback_block_mode(void *handle, int enable) </H4>
+
+<p>
+Sets up block (default) or non-block mode for a handle. Block mode suspends
+execution of a program when <i>snd_pcm_loopback_read()</i> is called for
+the time until some data arrives for file descriptor. In non-block mode, programs
+aren't suspended and the above function returns immediately with the count of
+bytes which were read by the driver. When used in this way, don't try to use
+the entire buffer after the call, but instead process the number of bytes returned,
+and call the function again.
+
+<p>
+
+<H4>int snd_pcm_loopback_stream_mode(void *handle, int mode)</H4>
+
+<p>
+Sets up stream mode which should be one of these values:
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+#define SND_PCM_LB_STREAM_MODE_RAW 0
+
+<p>
+#define SND_PCM_LB_STREAM_MODE_PACKET 1
+</DL>
+<p>
+Mode raw (default mode) means that the stream contains only PCM samples. Packet
+mode is more complicated. The stream contains a header at the begining of the
+packet. Information like data type and data size is contain in this header.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+#define SND_PCM_LB_TYPE_DATA 0 <i>/* sample data */</i>
+
+<p>
+#define SND_PCM_LB_TYPE_FORMAT 1 <i>/* PCM format */</i>
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_pcm_loopback_header {
+
+<p>
+ unsigned int size; <i>/* block size */</i>
+
+<p>
+ unsigned int type; <i>/* block type (SND_PCM_LB_TYPE_*) */</i>
+
+<p>
+};
+</DL>
+<p>
+
+<H4>int snd_pcm_loopback_format(void *handle, snd_pcm_format_t *format) </H4>
+
+<p>
+Get current format for PCM stream.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_pcm_format {
+
+<p>
+ unsigned int format; <i>/* SND_PCM_SFMT_XXXX */</i>
+
+<p>
+ unsigned int rate; <i>/* rate in Hz */</i>
+
+<p>
+ unsigned int channels; <i>/* number of channels (voices) */</i>
+
+<p>
+ unsigned char reserved[16];
+
+<p>
+};
+</DL>
+<p>
+
+<H4>ssize_t snd_pcm_loopback_read(void *handle, void *buffer, size_t size)</H4>
+
+<p>
+This function reads samples or loopback packets from the stream. Data depends
+on stream mode which should be set with <i>snd_pcm_loopback_stream_mode()</i>
+function. Function returns zero or positive value if record was success (value
+represents count of bytes which were successfully read from device) or negative
+error value if error occurred. Function will suspend process if block mode is
+active.
+
+<p>
+ <H2><A NAME="tth_sEc6">
+6</A> RawMidi Interface</H2>
+
+<p>
+RawMidi Interface is designed to write or read raw (unchanged) MIDI data over
+the MIDI line. MIDI stands Musical Instrument Digital Interface and more informations
+about this standard can be found at <b>http://www.midi.org</b>.
+
+<p>
+ <H3><A NAME="tth_sEc6.1">
+6.1</A> Low Level Layer</H3>
+
+<p>
+RawMidi devices are opened exclusively for a selected direction. While more
+than one process may not open a given MIDI device in the same direction simultaniously,
+seperate processes may open a single MIDI device in different directions (i.e.
+process one opens a MIDI device in playback direction and process two opens
+the same device in record direction). Audio devices (with MIDI ports) return
+EBUSY error to applications when other applications have already opened the
+requested direction.
+
+<p>
+
+<H4>int snd_rawmidi_open(void **handle, int card, int device, int mode)</H4>
+
+<p>
+Creates a new handle and opens a connection to the kernel sound audio interface
+for sound card number <i>card</i> (0-N) and rawmidi device number <i>device</i>.
+Function also checks if protocol is compatible to prevent use of old programs
+with a new kernel API. Function returns zero if successful, otherwise it returns
+an error code. Error code -EBUSY is returned when another process owns the selected
+direction.
+
+<p>
+The following modes should be used for the <i>mode</i> argument:
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+#define SND_RAWMIDI_OPEN_OUTPUT (O_WRONLY)
+
+<p>
+#define SND_RAWMIDI_OPEN_INPUT (O_RDONLY)
+
+<p>
+#define SND_RAWMIDI_OPEN_DUPLEX (O_RDWR)
+</DL>
+<p>
+
+<H4>int snd_rawmidi_close(void *handle)</H4>
+
+<p>
+Frees all resources allocated with audio handle and closes the connection to
+the kernel sound rawmidi interface. Function returns zero if successful, otherwise
+it returns an error code.
+
+<p>
+
+<H4>int snd_rawmidi_file_descriptor(void *handle)</H4>
+
+<p>
+Returns the file descriptor of the connection to the kernel sound audio interface.
+Function returns an error code if an error was encountered.
+
+<p>
+The file descriptor should be used for the <i>select(2)</i> synchronous multiplexer
+function for setting the read direction. Application should call <i>snd_rawmidi_read()</i>
+or <i>snd_rawmidi_write()</i> functions if data is waiting to be read or
+a write can be performed. Calling these functions is highly recommended.
+
+<p>
+
+<H4>int snd_rawmidi_block_mode(void *handle, int enable) </H4>
+
+<p>
+Sets up block (default) or non-block mode for a handle. Block mode suspends
+execution of a program when <i>snd_rawmidi_read()</i> or <i>snd_rawmidi_write()</i>
+is called for the time which is needed for the actual output or input over of
+the selected limit. In non-block mode, programs aren't suspended and the above
+functions return immediately with the count of bytes which were read or written
+by the driver. When used in this way, don't try to use the entire buffer after
+the call, but instead process the number of bytes returned, and call the function
+again.
+
+<p>
+
+<H4>int snd_rawmidi_info(void *handle, snd_pcm_info_t *info)</H4>
+
+<p>
+Fills the <i>*info</i> structure with data about the PCM device selected
+by <i>*handle</i>. Function returns zero if successful, otherwise it returns
+an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+<i>/*</i> device is capable rawmidi output *<i>/</i>
+
+<p>
+#define SND_RAWMIDI_INFO_OUTPUT 0x00000001
+
+<p>
+<i>/* device is capable rawmidi input */</i>
+
+<p>
+#define SND_RAWMIDI_INFO_INPUT 0x00000002
+
+<p>
+<i>/* device is capable duplex mode */</i>
+
+<p>
+#define SND_RAWMIDI_INFO_DUPLEX 0x00000004
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_rawmidi_info {
+
+<p>
+<i> /* sound card type */</i>
+
+<p>
+ unsigned int type;
+
+<p>
+<i> /* see SND_RAWMIDI_INFO_XXXX */</i>
+
+<p>
+ unsigned int flags;
+
+<p>
+<i> /* ID of this PCM device */</i>
+
+<p>
+ unsigned char id[32];
+
+<p>
+<i> /* name of this device */</i>
+
+<p>
+ unsigned char name[80];
+
+<p>
+<i> /* reserved for future use */</i>
+
+<p>
+ unsigned char reserved[64];
+
+<p>
+};
+</DL>
+<p>
+
+<H4>int snd_rawmidi_output_info(void *handle, snd_rawmidi_output_info_t
+*info)</H4>
+
+<p>
+Fills the *info structure with data about rawmidi output. Function returns
+zero if successful, otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_rawmidi_output_info {
+
+<p>
+<i> /* count of output switches */</i>
+
+<p>
+ unsigned int switches;
+
+<p>
+<i> /* reserved for future use */</i>
+
+<p>
+ unsigned char reserved[64];
+
+<p>
+};
+</DL>
+<p>
+
+<H4>int snd_rawmidi_input_info(void *handle, snd_pcm_record_info_t *info)</H4>
+
+<p>
+Fills the *info structure. Returns zero if successful, otherwise it returns
+an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_rawmidi_input_info {
+
+<p>
+<i> /* count of output switches */</i>
+
+<p>
+ unsigned int switches;
+
+<p>
+<i> /* reserved for future use */</i>
+
+<p>
+ unsigned char reserved[64];
+
+<p>
+};
+</DL>
+<p>
+
+<H4>int snd_rawmidi_output_switches(void *handle)</H4>
+
+<p>
+Returns count of rawmidi output switches. In this context 'switch' means universal
+control interface between kernel and application which allows various types
+of control. Function returns count if successful, otherwise it returns an error
+code. Return value should be zero if sound card doesn't have any rawmidi output
+switch.
+
+<p>
+
+<H4>int snd_rawmidi_output_switch(void *handle, const char *switch_id)</H4>
+
+<p>
+Returns index for switch with name <i>switch_id</i>. Function returns switch
+index if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_rawmidi_output_switch_read(void *handle int switchnsnd_rawmidi_switch_t *data)</H4>
+
+<p>
+Fills the <i>*data</i> structure with data about switch with index <i>switchn</i>.
+Function returns zero if successful, otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+<i>/* 0 or 1 (enable member of union) */</i>
+
+<p>
+#define SND_PCM_SW_TYPE_BOOLEAN 0
+
+<p>
+<i>/* 0 to 255 - from low to high (data8[0] member of union) */</i>
+
+<p>
+#define SND_PCM_SW_TYPE_BYTE 1
+
+<p>
+<i>/* 0 to 65535 - from low to high (data16[0] member of union) */</i>
+
+<p>
+#define SND_PCM_SW_TYPE_WORD 2
+
+<p>
+<i>/* 0 to 4294967296 ¯ from low to high (data32[0] member of union) */</i>
+
+<p>
+#define SND_PCM_SW_TYPE_DWORD 3
+
+<p>
+<i>/* user type - no type control */</i>
+
+<p>
+#define SND_PCM_SW_TYPE_USER (~0)
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_rawmidi_switch {
+
+<p>
+ <i>/* switch index (filled by application) */</i>
+
+<p>
+ unsigned int switchn;
+
+<p>
+ <i>/* identification of switch (for driver) */</i>
+
+<p>
+ unsigned char name[32];
+
+<p>
+ <i>/* type of switch value ¯ See SND_PCM_SW_TYPE_XXXX */</i>
+
+<p>
+ unsigned int type;
+
+<p>
+ <i>/* low range value */</i>
+
+<p>
+ unsigned int low;
+
+<p>
+ <i>/* high range value */</i>
+
+<p>
+ unsigned int high;
+
+<p>
+ union {
+
+<p>
+ unsigned int enable; <i>/* 0 = off 1 = on */</i>
+
+<p>
+ unsigned char data8[32]; <i>/* 8-bit data */</i>
+
+<p>
+ unsigned short data16[16]; <i>/* 16-bit data */</i>
+
+<p>
+ unsigned int data32[8]; <i>/* 32-bit data */</i>
+
+<p>
+ } value;
+
+<p>
+ <i>/* reserved for future use ¯ must be zero !!! */</i>
+
+<p>
+ unsigned char reserved[32];
+
+<p>
+}
+</DL>
+<p>
+
+<H4>int snd_rawmidi_output_switch_write(void *handle int switchnsnd_rawmidi_switch_t *data)</H4>
+
+<p>
+Writes the <i>*data</i> structure with data about switch with index <i>switchn</i>
+to kernel. Function returns zero if successful, otherwise it returns an error
+code.
+
+<p>
+
+<H4>int snd_rawmidi_input_switches(void *handle)</H4>
+
+<p>
+Returns count of rawmidi input switches. In this context 'switch' means universal
+control interface between kernel and application which allows various types
+of control. Function returns count if successful, otherwise it returns an error
+code. Return value should be zero if sound card doesn't have any rawmidi input
+switch.
+
+<p>
+
+<H4>int snd_rawmidi_input_switch(void *handle, const char *switch_id)</H4>
+
+<p>
+Returns index for switch with name <i>switch_id</i>. Function returns switch
+index if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_rawmidi_input_switch_read(void *handle int switchnsnd_rawmidi_switch_t *data)</H4>
+
+<p>
+Fills the <i>*data</i> structure with data about switch with index <i>switchn</i>.
+Function returns zero if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_rawmidi_input_switch_write(void *handle int switchnsnd_rawmidi_switch_t *data)</H4>
+
+<p>
+Writes the <i>*data</i> structure with data about switch with index <i>switchn</i>
+to kernel. Function returns zero if successful, otherwise it returns an error
+code.
+
+<p>
+
+<H4>int snd_rawmidi_output_params(void *handle, snd_rawmidi_output_params_t
+*params)</H4>
+
+<p>
+Sets various parameters for output direction. Function returns zero if successful,
+otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_rawmidi_output_params {
+
+<p>
+ int size;
+
+<p>
+ int max;
+
+<p>
+ int room;
+
+<p>
+<i> /* reserved for future use - must be filled with zero */</i>
+
+<p>
+ unsigned char reserved[16];
+
+<p>
+};
+</DL>
+<p>
+
+<DL compact><dt><b></b></dt>
+ <dd> [size]Requested queue size of output buffer in bytes (default setup is 4096
+[i386] or 8192 [alpha] bytes - this is system architecture dependent).
+<dt><b></b></dt>
+ <dd> [max]Maximum number of bytes in queue for wakeup. If the current byte count
+of filled portion of output buffer is greater than this value the driver will
+block an application or return immediately if non block mode is active.
+<dt><b></b></dt>
+ <dd> [room]Minimum number of bytes writable for wakeup. This value should be in most
+cases 1 which means return back to application if at least one byte is free
+in output buffer.
+</DL>
+<p>
+
+<H4>int snd_rawmidi_input_params(void *handle, snd_rawmidi_input_params_t
+*params)</H4>
+
+<p>
+Function sets various parameters for the recording direction. Function returns
+zero if successful, otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_rawmidi_input_params {
+
+<p>
+ int size;
+
+<p>
+ int min;
+
+<p>
+<i> /* reserved for future use - must be filled with zero */</i>
+
+<p>
+ unsigned char reserved[16];
+
+<p>
+};
+</DL>
+<p>
+
+<DL compact><dt><b></b></dt>
+ <dd> [size]Requested queue size of input buffer in bytes (default setup is 4096 [i386]
+or 8192 [alpha] bytes - this is system architecture dependent).
+<dt><b></b></dt>
+ <dd> [min]Minimum filled bytes in queue for wakeup. Driver blocks the application
+(if block mode is selected) until input buffer is filled with fewer than the
+number of bytes specified with this value.
+</DL>
+<p>
+
+<H4>int snd_rawmidi_output_status(void *handle, snd_rawmidi_output_status_t
+*status)</H4>
+
+<p>
+Fills the <i>*status</i> structure. Function returns zero if successful,
+otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_rawmidi_output_status {
+
+<p>
+ int size;
+
+<p>
+ int count;
+
+<p>
+ int queue;
+
+<p>
+<i> /* reserved for future use - must be filled with zero */</i>
+
+<p>
+ unsigned char reserved[16];
+
+<p>
+};
+</DL>
+<p>
+
+<DL compact><dt><b></b></dt>
+ <dd> [size]Size of currently allocated queue in bytes.
+<dt><b></b></dt>
+ <dd> [count]Count of bytes writable without blocking.
+<dt><b></b></dt>
+ <dd> [queue]Count of bytes in queue (number of bytes waiting to be output).
+</DL>
+<p>
+
+<H4>int snd_rawmidi_input_status(void *handle, snd_rawmidi_input_status_t
+*status)</H4>
+
+<p>
+Fills the <i>*status</i> structure. Function returns zero if successful,
+otherwise it returns an error code.
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+struct snd_rawmidi_input_status {
+
+<p>
+ int size;
+
+<p>
+ int count;
+
+<p>
+ int free;
+
+<p>
+ int overrun;
+
+<p>
+<i> /* reserved for future use - must be filled with zero */</i>
+
+<p>
+ unsigned char reserved[16];
+
+<p>
+};
+</DL>
+<p>
+
+<DL compact><dt><b></b></dt>
+ <dd> [size]Size of currently allocated queue in bytes.
+<dt><b></b></dt>
+ <dd> [count]Count of bytes readable without blocking.
+<dt><b></b></dt>
+ <dd> [free]Count of bytes in queue still free.
+<dt><b></b></dt>
+ <dd> [overrun]This value tells the application the count of overruns since the last
+call to <i>snd_rawmidi_input_status</i>.
+</DL>
+<p>
+
+<H4>int snd_rawmidi_drain_output(void *handle)</H4>
+
+<p>
+This function stops and drains (destroys) the output queue immediately. Function
+returns zero if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_rawmidi_flush_output(void *handle)</H4>
+
+<p>
+This function flushes the output queue. It blocks the program while the all
+the waiting bytes in kernel output queue are processed. Function returns zero
+if successful, otherwise it returns an error code.
+
+<p>
+
+<H4>int snd_rawmidi_flush_input(void *handle)</H4>
+
+<p>
+This function flushes (destroys) input queue. Function returns zero if successful,
+otherwise it returns an error code.
+
+<p>
+
+<H4>ssize_t snd_rawmidi_write(void *handle, const void *buffer, size_t
+size)</H4>
+
+<p>
+Writes bytes to the output queue. Function returns zero or positive value if
+the write was successful (value represents count of bytes which were successfully
+written to the device) or an error value if error occurred. Function will suspend
+the process if block mode is active.
+
+<p>
+
+<H4>ssize_t snd_rawmidi_read(void *handle, void *buffer, size_t size)</H4>
+
+<p>
+Function reads bytes from input queue. Function returns zero or positive value
+if the read was successful (value represents count of bytes which were successfully
+read from device) or negative error value if error occurred. Function will suspend
+the process if block mode is active.
+
+<p>
+ <H4><A NAME="tth_sEc6.1.1">
+6.1.1</A> Example</H4>
+
+<p>
+The following example shows how to send a control sequence (such as SysEx) to
+a MIDI device. Sound card #0 and rawmidi device #0 are used here:
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+int card = 0, device = 0, err, fd, count, size;
+
+<p>
+void *handle;
+
+<p>
+snd_pcm_format_t format;
+
+<p>
+char *buffer;
+</DL>
+<p>
+
+
+<p>
+
+<DL compact> <dt><b></b></dt>
+ <dd>
+buffer = (char *)malloc(64 * 1024);
+
+<p>
+if (!buffer) return;
+
+<p>
+if ((err = snd_rawmidi_open(&handle, card, device,
+
+<p>
+ SND_RAWMIDI_OPEN_OUTPUT)) < 0) {
+
+<p>
+ fprintf(stderr, "open failed: %s\n", snd_strerror( err ));
+
+<p>
+ return;
+
+<p>
+}
+
+<p>
+if ((err = snd_rawmidi_block_mode(handle 1)) < 0) {
+
+<p>
+ fprintf(stderr, "block failed: %s\n", snd_strerror( err ));
+
+<p>
+ snd_rawmidi_close(handle);
+
+<p>
+ return;
+
+<p>
+}
+
+<p>
+fd = open("/tmp/test.sysex", O_RDONLY);
+
+<p>
+if (fd < 0) {
+
+<p>
+ perror("open file");
+
+<p>
+ snd_rawmidi_close(handle);
+
+<p>
+ return;
+
+<p>
+}
+
+<p>
+idx = 0;
+
+<p>
+count = read(fd, buffer, 64 * 1024);
+
+<p>
+if (count <= 0) {
+
+<p>
+ perror("read from file");
+
+<p>
+ snd_rawmidi_close(handle);
+
+<p>
+ return;
+
+<p>
+}
+
+<p>
+close(fd);
+
+<p>
+size = snd_rawmidi_write(handle, &buffer, count);
+
+<p>
+printf("Bytes written %i from %i...\n", size, count);
+
+<p>
+snd_rawmidi_close(handle);
+
+<p>
+free(buffer);
+
+<p>
+</DL>
+<p><hr><small>File translated from T<sub><font size="-1">E</font></sub>X by <a href="http://hutchinson.belmont.ma.us/tth/">T<sub><font size="-1">T</font></sub>H</a>, version 1.98.<br>On 19 Jan 1999, 16:22.</small>
+</HTML>
--- /dev/null
+#This file was created by <emng> Mon Jan 11 02:36:51 1999
+#LyX 1.0 (C) 1995-1998 Matthias Ettrich and the LyX Team
+\lyxformat 2.15
+\textclass article
+\language default
+\inputencoding default
+\fontscheme default
+\graphics default
+\paperfontsize default
+\spacing single
+\papersize Default
+\paperpackage widemarginsa4
+\use_geometry 0
+\use_amsmath 0
+\paperorientation portrait
+\secnumdepth 3
+\tocdepth 3
+\paragraph_separation indent
+\defskip medskip
+\quotes_language english
+\quotes_times 2
+\papercolumns 1
+\papersides 1
+\paperpagestyle default
+
+\layout Title
+\added_space_top vfill \added_space_bottom vfill
+Advanced Linux Sound Architecture - Library API
+\layout Author
+
+
+\series bold
+Jaroslav Kysela <perex@jcu.cz>
+\series default
+ with assistance from Alan Robinson and Fred Floberg
+\layout Date
+
+1998-11-11
+\layout Standard
+\align center
+
+\shape italic
+This document describes, in full detail, the Advanced Linux Sound Architecture
+ library API.
+
+\layout Standard
+
+
+\begin_inset LatexCommand \tableofcontents
+
+\end_inset
+
+
+\layout Section
+
+Introduction
+\layout Standard
+
+The Advanced Linux Sound Architecture comes with a kernel API & library
+ API.
+ This document describes the library API and how it interfaces with the
+ kernel API.
+ The kernal API will probably never be documented in standalone form.
+
+\layout Standard
+
+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.
+
+\layout Standard
+
+For a complete list of all variables and functions in the API you should
+ look at the following header files:
+\layout Itemize
+
+/usr/include/sys/asoundlib.h
+\layout Itemize
+
+/usr/include/linux/asound.h
+\layout Itemize
+
+/usr/include/linux/asoundid.h
+\layout Section
+
+Error Codes
+\layout Standard
+
+All functions return int (or some sort of signed value).
+ If this value is negative it represents an error code.
+ Codes up to
+\shape italic
+SND_ERROR_BEGIN (500000)
+\shape default
+ represent standard system errors.
+ Codes equal to or greather than this value represent sound library API
+ errors.
+ All error codes begin with the prefix
+\shape italic
+SND_ERROR_
+\shape default
+.
+
+\layout Subsection
+
+Error Codes in Detail
+\layout Standard
+\added_space_top 0.3cm \added_space_bottom 0.3cm \LyXTable
+multicol5
+1 2 0 0 -1 -1 -1 -1
+1 1 0 0
+8 1 1 "" ""
+8 1 1 "" ""
+0 8 1 0 0 0 0 "" ""
+0 8 1 0 0 0 0 "" ""
+
+SND_ERROR_UNCOMPATIBLE_VERSION
+\newline
+500000
+\layout Standard
+
+This error is caused if the driver uses an incompatible kernel API for this
+ interface and hence the library doesn't know how this API can be used.
+
+\layout Subsection
+
+Functions
+\layout Subsubsection*
+
+const char *snd_strerror(int errnum)
+\layout Standard
+
+This function converts an error code to a string.
+ Its functionality is the same as the
+\shape italic
+strerror
+\shape default
+ function from the standard C library, but this function returns error message
+ strings for sound error codes, as well.
+\layout Section
+
+Control Interface
+\layout Standard
+
+The control interface gives applications various information about the currently
+ installed sound driver in the system.
+ The interface should be used to detect if another sound interface is present
+ for a selected soundcard or, for example, to create a list of devices (MIXER,
+ PCM etc) from which the user can select.
+\layout Subsection
+
+Low-Level Layer
+\layout Subsubsection*
+
+int snd_cards(void)
+\layout Standard
+
+Returns the number of soundcards present in the system, if any.
+ Otherwise it returns a negative value, which maps to an error code.
+ This function will return 0 if no soundcards are detected.
+\layout Subsubsection*
+
+unsigned int snd_cards_mask(void)
+\layout Standard
+
+Returns the bitmap of soundcards present in the system, if any.
+ This function will return 0 if no soundcards are detected.
+ The first soundcard is represented with bit 0 (0x00000001).
+ See the documentation on installing ALSA and /etc/conf.modules configuration
+ for information on assigning numbers to soundcards.
+\layout Subsubsection*
+
+int snd_card_name(const char *name)
+\layout Standard
+
+Returns soundcard number for appropriate soundcard name.
+ String
+\shape italic
+name
+\shape default
+ can contain word identification for card (ALSA driver allows the user choose
+ card identification using snd_id module parameter) or soundcard index (1-N)
+ encoded into ASCII.
+\layout Subsubsection*
+
+int snd_ctl_open(void **handle, int card)
+\layout Standard
+
+Creates a new handle and opens communication with the kernel sound control
+ interface for soundcard number
+\shape italic
+card
+\shape default
+ (0-N).
+ The function also checks if the protocol is compatible, so as to prevent
+ the use of old programs with a new kernel API.
+ Function returns zero if successful, otherwise an error code is returned.
+
+\layout Subsubsection*
+
+int snd_ctl_close(void *handle)
+\layout Standard
+
+Frees all resources allocated with control handle and closes the kernel
+ sound control interface.
+ This function returns zero if successful, otherwise it returns an error
+ code.
+\layout Subsubsection*
+
+int snd_ctl_file_descriptor(void *handle)
+\layout Standard
+
+Returns a file descriptor for the kernel sound control interface.
+ This function is normally only used in very special cases.
+ This function returns a negative error code if an error was encountered.
+\layout Subsubsection*
+
+int snd_ctl_hw_info(void *handle, snd_ctl_hw_info_t *info)
+\layout Standard
+
+Fills the info structure with data about the sound hardware referenced by
+ handle.
+ This function returns zero if successful, otherwise it returns an error
+ code.
+\layout LyX-Code
+
+
+\shape italic
+/* driver has MIDI interface */
+\layout LyX-Code
+
+#define SND_CTL_GCAPS_MIDI
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0x0000001
+\layout LyX-Code
+
+
+\shape italic
+/* soundcard has synthesizer */
+\layout LyX-Code
+
+#define SND_CTL_LCAPS_SYNTH
+\protected_separator
+
+\protected_separator
+ 0x0000001
+\layout LyX-Code
+
+
+\shape italic
+/* soundcard has RAW FM/OPL3 */
+\layout LyX-Code
+
+#define SND_CTL_LCAPS_RAWFM
+\protected_separator
+
+\protected_separator
+ 0x0000002
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+struct snd_ctl_hw_info {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* type of card - see SND_CARD_TYPE_XXXX */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int type;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* global capabilities - see SND_CTL_GCAPS_XXXX*/
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int gcaps;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* local capabilities \i \={ }
+ see SND_CTL_LCAPS_XXXX */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int lcaps;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* count of PCM devices (0 to N) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+unsigned int pcmdevs;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* count of MIXER devices (0 to N)*/
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int mixerdevs;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* count of raw MIDI devices (0 to N) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+unsigned int mididevs;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* ID of card (user selectable) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+char id[80];
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* name/info text about soundcard */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ char name[80];
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* count of control switches */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int switches;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* reserved for future use */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[124];
+\layout LyX-Code
+
+};
+\layout Subsubsection*
+
+int snd_ctl_switches(void *handle)
+\layout Standard
+
+Returns the number of control switches.
+ In this context 'switch' means universal control interface between kernel
+ and application which allows various types of control.
+ Function returns count if successful, otherwise it returns an error code.
+ Return value should be zero if the soundcard doesn't have any control switches.
+\layout Subsubsection*
+
+int snd_ctl_switch(void *handle, const char *switch_id)
+\layout Standard
+
+Returns the index for the switch with the name
+\shape italic
+switch_id
+\shape default
+.
+ This function returns switch index if successful, otherwise it returns
+ an error code.
+\layout Subsubsection*
+
+int snd_ctl_switch_read(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_ctl_switch_t *data)
+\layout Standard
+
+Fills the
+\shape italic
+*data
+\shape default
+ structure with data about the switch with index
+\shape italic
+switchn
+\shape default
+.
+ This function returns zero if successful, otherwise it returns an error
+ code.
+\layout LyX-Code
+
+
+\shape italic
+/* 0 or 1 (enable member of union) */
+\layout LyX-Code
+
+#define SND_CTL_SW_TYPE_BOOLEAN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0
+\layout LyX-Code
+
+
+\shape italic
+/* 0 to 255 - from low to high (data8[0] member of union) */
+\layout LyX-Code
+
+#define SND_CTL_SW_TYPE_BYTE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+1
+\layout LyX-Code
+
+
+\shape italic
+/* 0 to 65535 - from low to high (data16[0] member of union) */
+\layout LyX-Code
+
+#define SND_CTL_SW_TYPE_WORD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+2
+\layout LyX-Code
+
+
+\shape italic
+/* 0 to 4294967296 \i \={ }
+ from low to high (data32[0] member of union) */
+\layout LyX-Code
+
+#define SND_CTL_SW_TYPE_DWORD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 3
+\layout LyX-Code
+
+
+\shape italic
+/* user type - no type control */
+\layout LyX-Code
+
+#define SND_CTL_SW_TYPE_USER
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+(~0)
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+
+\shape italic
+/* well known (named) switches */
+\layout LyX-Code
+
+#define SND_CTL_SW_JOYSTICK
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "Joystick"
+\layout LyX-Code
+
+#define SND_CTL_SW_JOYSTICK_ADDRESS
+\protected_separator
+ "Joystick Address"
+\layout LyX-Code
+
+#define SND_CTL_SW_JOYSTICK_SPEED
+\protected_separator
+
+\protected_separator
+ "Joystick Speed"
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+struct snd_ctl_switch {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* switch index (filled by application) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int switchn;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* indentification of switch (for driver) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char name[32];
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* type of switch value - See SND_CTL_SW_TYPE_XXXX */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int type;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* low range value */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int low;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* high range value */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int high;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ union {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int enable;
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* 0 = off\i \c{ }
+ 1 = on */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char data8[32];
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* 8-bit data */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned short data16[16];
+\protected_separator
+
+\shape italic
+/* 16-bit data */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int data32[8];
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* 32-bit data */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ } value;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* reserved for future use \i \={ }
+ must be zero !!! */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[32];
+\layout LyX-Code
+
+}
+\layout Subsubsection*
+
+int snd_ctl_switch_write(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_ctl_switch_t *data)
+\layout Standard
+
+Writes the
+\shape italic
+*data
+\shape default
+ structure with data about the switch with index
+\shape italic
+switchn
+\shape default
+ to kernel.
+ This function returns zero if successful, otherwise it returns an error
+ code.
+\layout Subsubsection*
+
+int snd_ctl_mixer_info(void *handle, int dev, snd_mixer_info_t *info)
+\layout Standard
+
+Fills the *info structure with data about the mixer device.
+ Returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_mixer_info_t
+\shape default
+ structure are in the
+\series bold
+Mixer Interface
+\series default
+ section.
+ The argument
+\shape italic
+dev
+\shape default
+ specifies the device number for the appropriate soundcard.
+ Its range is 0 to N where N is determined by
+\shape italic
+struct snd_ctl_hw_info->mixerdevs - 1
+\shape default
+.
+ It should be used to collect information about mixer devices.
+\layout Subsubsection*
+
+int snd_ctl_mixer_switches(void *handle)
+\layout Standard
+
+Returns count of mixer switches.
+ In this context 'switch' means universal control interface between kernel
+ and application which allows various types control.
+ This function returns count if successful, otherwise it returns an error
+ code.
+ Return value should be zero if soundcard doesn't have any mixer switches.
+\layout Subsubsection*
+
+int snd_ctl_mixer_switch(void *handle, const char *switch_id)
+\layout Standard
+
+Returns the index for the switch with the name
+\shape italic
+switch_id
+\shape default
+.
+ This function returns switch index if successful, otherwise it returns
+ an error code.
+\layout Subsubsection*
+
+int snd_ctl_mixer_switch_read(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_mixer_switch_t
+ *data)
+\layout Standard
+
+Fills the
+\shape italic
+*data
+\shape default
+ structure with data about the switch with index
+\shape italic
+switchn
+\shape default
+.
+ This function returns zero if successful, otherwise it returns an error
+ code.
+ Details about the
+\shape italic
+snd_mixer_switch_t
+\shape default
+ structure are in the
+\series bold
+Mixer Interface
+\series default
+ section.
+\layout Subsubsection*
+
+int snd_ctl_mixer_switch_write(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_mixer_switch_t
+ *data)
+\layout Standard
+
+Writes the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+ to kernel.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_mixer_switch_t
+\shape default
+ structure are in the
+\series bold
+Mixer Interface
+\series default
+ Interface section.
+\layout Subsubsection*
+
+int snd_ctl_pcm_info(void *handle, int dev, snd_pcm_info_t *info)
+\layout Standard
+
+Fills the
+\shape italic
+*info
+\shape default
+ structure with data about the PCM device.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_pcm_info_t
+\shape default
+ structure are in the
+\series bold
+Digital Audio (PCM)
+\series default
+ Interface section.
+ The argument
+\shape italic
+dev
+\shape default
+ selects the device number for the sound card referenced by
+\shape italic
+*handle
+\shape default
+.
+ Its range is 0 to N where N is
+\shape italic
+struct snd_ctl_hw_info->pcmdevs - 1
+\shape default
+.
+ This function will work if the selected PCM device is busy, too.
+ It should be used to collect information about PCM devices without exclusive
+ lock.
+
+\layout Subsubsection*
+
+int snd_ctl_pcm_playback_info(void *handle, int dev, snd_pcm_playback_info_t
+ *info)
+\layout Standard
+
+Fills the
+\shape italic
+*info
+\shape default
+ structure with data about the PCM device and playback direction.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_pcm_playback_info_t
+\shape default
+ structure are in the
+\series bold
+Digital Audio (PCM) Interface
+\series default
+ section.
+ The argument
+\shape italic
+dev
+\shape default
+ selects the device number for the sound card referenced by
+\shape italic
+*handle
+\shape default
+.
+ Its range is 0 to N where N is
+\shape italic
+struct snd_ctl_hw_info->pcmdevs - 1
+\shape default
+.
+ This function will work if the selected PCM device is busy, too.
+ It should be used to collect information about PCM devices without exclusive
+ lock.
+
+\layout Subsubsection*
+
+int snd_ctl_pcm_playback_switches(void *handle)
+\layout Standard
+
+Returns count of PCM playback switches.
+ In this context 'switch' means universal control interface between kernel
+ and application which allows various types of control.
+ Function returns count if successful, otherwise it returns an error code.
+ Return value should be zero if sound card doesn't have any PCM playback
+ switch.
+\layout Subsubsection*
+
+int snd_ctl_pcm_playback_switch(void *handle, const char *switch_id)
+\layout Standard
+
+Returns index for switch with name
+\shape italic
+switch_id
+\shape default
+.
+ Function returns switch index if successful, otherwise it returns an error
+ code.
+\layout Subsubsection*
+
+int snd_ctl_pcm_playback_switch_read(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_pcm_switch_t
+ *data)
+\layout Standard
+
+Fills the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_pcm_switch_t
+\shape default
+ structure are in the
+\series bold
+Digital Audio (PCM)
+\series default
+ Interface section.
+\layout Subsubsection*
+
+int snd_ctl_pcm_playback_switch_write(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_pcm_switch_t
+ *data)
+\layout Standard
+
+Writes the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+ to kernel.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_pcm_switch_t
+\shape default
+ structure are in the
+\series bold
+Digital Audio (PCM)
+\series default
+ Interface section.
+\layout Subsubsection*
+
+int snd_ctl_pcm_record_info(void *handle, int dev, snd_pcm_record_info_t
+ *info)
+\layout Standard
+
+Fills the
+\shape italic
+*info
+\shape default
+ structure with data about the PCM device and record direction.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_pcm_record_info_t
+\shape default
+ structure are in the
+\series bold
+Digital Audio (PCM) Interface
+\series default
+ section.
+ The argument
+\shape italic
+dev
+\shape default
+ selects the device number for the sound card referenced by
+\shape italic
+*handle
+\shape default
+.
+ Its range is 0 to N where N is
+\shape italic
+struct snd_ctl_hw_info->pcmdevs - 1
+\shape default
+.
+ This function will work if the selected PCM device is busy, too.
+ It should be used to collect information about PCM devices without exclusive
+ lock.
+
+\layout Subsubsection*
+
+int snd_ctl_pcm_record_switches(void *handle)
+\layout Standard
+
+Returns count of PCM record switches.
+ In this context 'switch' means universal control interface between kernel
+ and application which allows various types of control.
+ Function returns count if successful, otherwise it returns an error code.
+ Return value should be zero if sound card doesn't have any PCM record switch.
+\layout Subsubsection*
+
+int snd_ctl_pcm_record_switch(void *handle, const char *switch_id)
+\layout Standard
+
+Returns index for switch with name
+\shape italic
+switch_id
+\shape default
+.
+ Function returns switch index if successful, otherwise it returns an error
+ code.
+\layout Subsubsection*
+
+int snd_ctl_pcm_record_switch_read(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_pcm_switch_t
+ *data)
+\layout Standard
+
+Fills the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_pcm_switch_t
+\shape default
+ structure are in the
+\series bold
+Digital Audio (PCM)
+\series default
+ Interface section.
+\layout Subsubsection*
+
+int snd_ctl_pcm_record_switch_write(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_pcm_switch_t
+ *data)
+\layout Standard
+
+Writes the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+ to kernel.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_pcm_switch_t
+\shape default
+ structure are in the
+\series bold
+Digital Audio (PCM)
+\series default
+ Interface section.
+\layout Subsubsection*
+
+int snd_ctl_rawmidi_info(void *handle, int dev, snd_rawmidi_info_t *info)
+\layout Standard
+
+Fills the
+\shape italic
+*info
+\shape default
+ structure with data about the rawmidi device.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_rawmidi_info_t
+\shape default
+ structure are in the
+\series bold
+RawMidi Interface
+\series default
+ section.
+ The argument
+\shape italic
+dev
+\shape default
+ selects the device number for the sound card referenced by
+\shape italic
+*handle
+\shape default
+.
+ Its range is 0 to N where N is
+\shape italic
+struct snd_ctl_hw_info->mididevs - 1
+\shape default
+.
+ This function will work if the selected rawmidi device is busy, too.
+ It should be used to collect information about rawmidi devices without
+ exclusive lock.
+
+\layout Subsubsection*
+
+int snd_ctl_rawmidi_output_info(void *handle, int dev, snd_rawmidi_output_info_t
+ *info)
+\layout Standard
+
+Fills the
+\shape italic
+*info
+\shape default
+ structure with data about the rawmidi device and output direction.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_pcm_playback_info_t
+\shape default
+ structure are in the
+\series bold
+RawMidi Interface
+\series default
+ section.
+ The argument
+\shape italic
+dev
+\shape default
+ selects the device number for the sound card referenced by
+\shape italic
+*handle
+\shape default
+.
+ Its range is 0 to N where N is
+\shape italic
+struct snd_ctl_hw_info->mididevs - 1
+\shape default
+.
+ This function will work if the selected rawmidi device is busy, too.
+ It should be used to collect information about rawmidi devices without
+ exclusive lock.
+
+\layout Subsubsection*
+
+int snd_ctl_rawmidi_output_switches(void *handle)
+\layout Standard
+
+Returns count of rawmidi output switches.
+ In this context 'switch' means universal control interface between kernel
+ and application which allows various types of control.
+ Function returns count if successful, otherwise it returns an error code.
+ Return value should be zero if sound card doesn't have any control switch.
+\layout Subsubsection*
+
+int snd_ctl_rawmidi_output_switch(void *handle, const char *switch_id)
+\layout Standard
+
+Returns index for switch with name
+\shape italic
+switch_id
+\shape default
+.
+ Function returns switch index if successful, otherwise it returns an error
+ code.
+ Return value should be zero if sound card doesn't have any rawmidi output
+ switch.
+\layout Subsubsection*
+
+int snd_ctl_rawmidi_output_switch_read(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_rawmidi_swit
+ch_t *data)
+\layout Standard
+
+Fills the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_rawmidi_switch_t
+\shape default
+ structure are in the
+\series bold
+RawMidi Interface
+\series default
+ section.
+\layout Subsubsection*
+
+int snd_ctl_rawmidi_output_switch_write(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_rawmidi_swi
+tch_t *data)
+\layout Standard
+
+Writes the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+ to kernel.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_rawmidi_switch_t
+\shape default
+ structure are in the
+\series bold
+RawMidi Interface
+\series default
+ section.
+\layout Subsubsection*
+
+int snd_ctl_rawmidi_input_info(void *handle, int dev, snd_rawmidi_input_info_t
+ *info)
+\layout Standard
+
+Fills the
+\shape italic
+*info
+\shape default
+ structure with data about the rawmidi device and input direction.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_rawmidi_record_info_t
+\shape default
+ structure are in the
+\series bold
+RawMidi Interface
+\series default
+ section.
+ The argument
+\shape italic
+dev
+\shape default
+ selects the device number for the sound card referenced by
+\shape italic
+*handle
+\shape default
+.
+ Its range is 0 to N where N is
+\shape italic
+struct snd_ctl_hw_info->pcmdevs - 1
+\shape default
+.
+ This function will work if the selected rawmidi device is busy, too.
+ It should be used to collect information about rawmidi devices without
+ exclusive lock.
+
+\layout Subsubsection*
+
+int snd_ctl_rawmidi_input_switches(void *handle)
+\layout Standard
+
+Returns count of rawmidi input switches.
+ In this context 'switch' means universal control interface between kernel
+ and application which allows various types of control.
+ Function returns count if successful, otherwise it returns an error code.
+ Return value should be zero if sound card doesn't have any rawmidi input
+ switch.
+\layout Subsubsection*
+
+int snd_ctl_rawmidi_input_switch(void *handle, const char *switch_id)
+\layout Standard
+
+Returns index for switch with name
+\shape italic
+switch_id
+\shape default
+.
+ Function returns switch index if successful, otherwise it returns an error
+ code.
+\layout Subsubsection*
+
+int snd_ctl_rawmidi_input_switch_read(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_pcm_switch_t
+ *data)
+\layout Standard
+
+Fills the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_rawmidi_switch_t
+\shape default
+ structure are in the
+\series bold
+RawMidi Interface
+\series default
+ Interface section.
+\layout Subsubsection*
+
+int snd_ctl_rawmidi_input_switch_write(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_pcm_switch_t
+ *data)
+\layout Standard
+
+Writes the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+ to kernel.
+ Function returns zero if successful, otherwise it returns an error code.
+ Details about the
+\shape italic
+snd_rawmidi_switch_t
+\shape default
+ structure are in the
+\series bold
+RawMidi Interface
+\series default
+ section.
+\layout Subsubsection
+
+Examples
+\layout Standard
+
+The following example shows how all PCM devices can be detected for the
+ first sound card (#0) in the system.
+\layout LyX-Code
+
+int card = 0, err;
+\layout LyX-Code
+
+void *handle;
+\layout LyX-Code
+
+snd_ctl_hw_info_t info;
+\newline
+
+\layout LyX-Code
+
+if ((err = snd_ctl_open(&handle, card)) < 0) {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ fprintf(stderr, "open failed: %s
+\backslash
+n", snd_strerror(err));
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ return;
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+if ((err = snd_ctl_hw_info(handle, &info)) < 0) {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ fprintf(stderr, "hw info failed: %s
+\backslash
+n",
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ snd_strerror(err));
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ snd_ctl_close(handle);
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+return;
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+printf("Installed PCM devices for card #i: %i
+\backslash
+n",
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ card + 1, info.pcmdevs);
+\layout LyX-Code
+
+snd_ctl_close(handle);
+\layout Section
+
+Mixer Interface
+\layout Standard
+
+The Mixer Interface allows applications to change the volume level of a
+ sound card's input/output channels in both the linear range\i \c{ }
+ percentage
+ range (0-100) and in decibels.
+ It also supports features like hardware mute, input sound source, stereo
+ signal routing etc.
+\layout Subsection
+
+Low-Level Layer
+\layout Standard
+
+Mixer devices aren't opened exclusively.
+ This allows applications to open a device multiple times with one or more
+ processes.
+\layout Subsubsection*
+
+int snd_mixer_open(void **handle, int card, int device)
+\layout Standard
+
+Creates new handle and opens a connection to the kernel sound mixer interface
+ for sound card number
+\shape italic
+card
+\shape default
+ (0-N) and mixer device number
+\shape italic
+device
+\shape default
+.
+ Also checks if protocol is compatible to prevent use of old programs with
+ new kernel API.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout Subsubsection*
+
+int snd_mixer_close(void *handle)
+\layout Standard
+
+Frees all resources allocated to the mixer handle and closes its connection
+ to the kernel sound mixer interface.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout Subsubsection*
+
+int snd_mixer_file_descriptor(void *handle)
+\layout Standard
+
+Returns the file descriptor for the connection to the kernel sound mixer
+ interface.
+ This function should be used only in very special cases.
+ Function returns a negative error code if an error was encountered.
+\layout Standard
+
+The file descriptor should be used for the
+\shape italic
+select(2)
+\shape default
+ synchronous multiplexer function for determining read direction.
+ Applications should call
+\shape italic
+snd_mixer_read()
+\shape default
+ function if some data is waiting to be read.
+ It is recommended that you do this, since it leaves place for this function
+ to handle some new kernel API specifications.
+\layout Subsubsection*
+
+int snd_mixer_channels(void *handle)
+\layout Standard
+
+Returns the count of mixer channels for appropriate mixer device, otherwise
+ the return value is negative, and signifies an error code.
+ Never returns zero.
+\layout Subsubsection*
+
+int snd_mixer_info(void *handle, snd_mixer_info_t *info)
+\layout Standard
+
+Fills the
+\shape italic
+*info
+\shape default
+ structure with information about the mixer associated with
+\shape italic
+*handle
+\shape default
+.
+ Returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+
+\shape italic
+/* mixer can do only exclusive record */
+\layout LyX-Code
+
+#define SND_MIXER_INFO_CAP_EXCL_RECORD
+\protected_separator
+ 0x00000001
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+struct snd_mixer_info {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* type of sound card - SND_CARD_TYPE_XXXX */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int type;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* count of mixer devices */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+unsigned int channels;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* some flags about this device (SND_MIXER_INFO_CAP_XXXX) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int caps;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* ID of this mixer */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char id[32];
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* name of this device */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char name[80];
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* reserved for future use */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ char reserved[ 32 ];
+\layout LyX-Code
+
+};
+\layout Subsubsection*
+
+int snd_mixer_switches(void *handle)
+\layout Standard
+
+Returns count of mixer switches.
+ In this context 'switch' means universal control interface between kernel
+ and application which allows various types of control.
+ Function returns count if successful, otherwise it returns an error code.
+ Return value will be zero if sound card doesn't have any mixer switch.
+\layout Subsubsection*
+
+int snd_mixer_switch(void *handle, const char *switch_id)
+\layout Standard
+
+Returns index for switch with name
+\shape italic
+switch_id
+\shape default
+.
+ Function returns switch index if successful, otherwise it returns an error
+ code.
+\layout Subsubsection*
+
+int snd_mixer_switch_read(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_mixer_switch_t *data)
+\layout Standard
+
+Fills the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+
+\shape italic
+/* 0 or 1 (enable member of union) */
+\layout LyX-Code
+
+#define SND_MIXER_SW_TYPE_BOOLEAN
+\protected_separator
+
+\protected_separator
+ 0
+\layout LyX-Code
+
+
+\shape italic
+/* 0 to 255 - from low to high (data8[0] member of union) */
+\layout LyX-Code
+
+#define SND_MIXER_SW_TYPE_BYTE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+1
+\layout LyX-Code
+
+
+\shape italic
+/* 0 to 65535 - from low to high (data16[0] member of union) */
+\layout LyX-Code
+
+#define SND_MIXER_SW_TYPE_WORD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+2
+\layout LyX-Code
+
+
+\shape italic
+/* 0 to 4294967296 \i \={ }
+ from low to high (data32[0] member of union) */
+\layout LyX-Code
+
+#define SND_MIXER_SW_TYPE_DWORD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 3
+\layout LyX-Code
+
+
+\shape italic
+/* user type - no type control */
+\layout LyX-Code
+
+#define SND_MIXER_SW_TYPE_USER
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+(~0)
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+
+\shape italic
+/* well known (named) switches */
+\layout LyX-Code
+
+#define SND_MIXER_SW_LOUDNESS
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "Loudness"
+\protected_separator
+
+\shape italic
+/* bass boost */
+\layout LyX-Code
+
+#define SND_MIXER_SW_SIM_STEREO
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "Simulated Stereo Enhancement"
+\layout LyX-Code
+
+#define SND_MIXER_SW_3D
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "3D Stereo Enhancement"
+\layout LyX-Code
+
+
+\shape italic
+/* microphone gain */
+\layout LyX-Code
+
+#define SND_MIXER_SW_MIC_GAIN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "MIC Gain"
+\layout LyX-Code
+
+
+\shape italic
+/* microphone auto gain control */
+\layout LyX-Code
+
+#define SND_MIXER_SW_MIC_GAIN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "MIC Auto-Gain-Control"
+\layout LyX-Code
+
+
+\shape italic
+/* change microphone impedance */
+\layout LyX-Code
+
+#define SND_MIXER_SW_MIC_GAIN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "Change MIC Impedance"
+\layout LyX-Code
+
+
+\shape italic
+/* change line-in to output */
+\layout LyX-Code
+
+#define SND_MIXER_SW_MIC_GAIN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "Line In to Output"
+\layout LyX-Code
+
+#define SND_MIXER_SW_IEC958OUT
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "IEC-958 (S/PDIF) Output"
+\layout LyX-Code
+
+#define SND_MIXER_SW_IEC958IN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "IEC-958 (S/PDIF) Input"
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+struct snd_mixer_switch {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* switch index (filled by application) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int switchn;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* identification of switch (for driver) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char name[32];
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* type of switch value \i \={ }
+ See SND_CTL_SW_TYPE_XXXX */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int type;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* low range value */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int low;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* high range value */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int high;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ union {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int enable;
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* 0 = off\i \c{ }
+ 1 = on */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char data8[32];
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* 8-bit data */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned short data16[16];
+\protected_separator
+
+\shape italic
+/* 16-bit data */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int data32[8];
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* 32-bit data */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ } value;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* reserved for future use \i \={ }
+ must be zero !!! */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[32];
+\layout LyX-Code
+
+}
+\layout Subsubsection*
+
+int snd_mixer_switch_write(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_mixer_switch_t *data)
+\layout Standard
+
+Writes the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+ to kernel.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout Subsubsection*
+
+int snd_mixer_exact_mode(void *handle, int enable)
+\layout Standard
+
+Turns on = 1 or off = 0 (by default) exact mode.
+ This mode allows application to set/get volume values in exact range which
+ uses hardware.
+ In non-exact mode range is always from percentage 0 to 100 and driver does
+ conversion to hardware range.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout Subsubsection*
+
+int snd_mixer_channel(void *handle, const char *channel_id)
+\layout Standard
+
+Returns the channel number (index) associated with
+\shape italic
+channel_id
+\shape default
+ (channel name), or returns an error code.
+ Note: Below mixer channel IDs are subject to change and will be extended
+ if new hardware has support for other mixer input/output channels.
+\layout LyX-Code
+
+#define SND_MIXER_ID_MASTER
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Master"
+\layout LyX-Code
+
+#define SND_MIXER_ID_MASTER1
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Master 1"
+\layout LyX-Code
+
+
+\shape italic
+/* digital master */
+\layout LyX-Code
+
+#define SND_MIXER_ID_MASTERD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Master D"
+\layout LyX-Code
+
+
+\shape italic
+/* second digital master */
+\layout LyX-Code
+
+#define SND_MIXER_ID_MASTERD1
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Master D1"
+\layout LyX-Code
+
+#define SND_MIXER_ID_HEADPHONE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Headphone"
+\layout LyX-Code
+
+#define SND_MIXER_ID_MASTER_MONO
+\protected_separator
+
+\protected_separator
+"Master M"
+\layout LyX-Code
+
+#define SND_MIXER_ID_3D
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"3D Wide"
+\layout LyX-Code
+
+#define SND_MIXER_ID_3D_VOLUME
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"3D Volume"
+\layout LyX-Code
+
+#define SND_MIXER_ID_3D_CENTER
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"3D Center"
+\layout LyX-Code
+
+#define SND_MIXER_ID_3D_SPACE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"3D Space"
+\layout LyX-Code
+
+#define SND_MIXER_ID_3D_DEPTH
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"3D Depth"
+\layout LyX-Code
+
+#define SND_MIXER_ID_BASS
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Bass"
+\layout LyX-Code
+
+#define SND_MIXER_ID_TREBLE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Treble"
+\layout LyX-Code
+
+#define SND_MIXER_ID_FADER
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "Fader"
+\layout LyX-Code
+
+#define SND_MIXER_ID_SYNTHESIZER
+\protected_separator
+ "Synth"
+\layout LyX-Code
+
+#define SND_MIXER_ID_SYNTHESIZER1
+\protected_separator
+"Synth 1"
+\layout LyX-Code
+
+#define SND_MIXER_ID_FM
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"FM"
+\layout LyX-Code
+
+#define SND_MIXER_ID_EFFECT
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Effect"
+\layout LyX-Code
+
+#define SND_MIXER_ID_DSP
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"DSP"
+\layout LyX-Code
+
+#define SND_MIXER_ID_PCM
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "PCM"
+\layout LyX-Code
+
+#define SND_MIXER_ID_PCM1
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"PCM 1"
+\layout LyX-Code
+
+#define SND_MIXER_ID_LINE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Line-In"
+\layout LyX-Code
+
+#define SND_MIXER_ID_MIC
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "MIC"
+\layout LyX-Code
+
+#define SND_MIXER_ID_CD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"CD"
+\layout LyX-Code
+
+#define SND_MIXER_ID_VIDEO
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Video"
+\layout LyX-Code
+
+#define SND_MIXER_ID_PHONE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Phone"
+\layout LyX-Code
+
+#define SND_MIXER_ID_GAIN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Record-Gain"
+\layout LyX-Code
+
+#define SND_MIXER_ID_MIC_GAIN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Mic-Gain"
+\layout LyX-Code
+
+#define SND_MIXER_ID_IGAIN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "In-Gain"
+\layout LyX-Code
+
+#define SND_MIXER_ID_OGAIN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "Out-Gain"
+\layout LyX-Code
+
+#define SND_MIXER_ID_LOOPBACK
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Loopback"
+\layout LyX-Code
+
+#define SND_MIXER_ID_SPEAKER
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "PC Speaker"
+\layout LyX-Code
+
+#define SND_MIXER_ID_MONO
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ "Mono"
+\layout LyX-Code
+
+#define SND_MIXER_ID_MONO1
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Mono 1"
+\layout LyX-Code
+
+#define SND_MIXER_ID_MONO2
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Mono 2"
+\layout LyX-Code
+
+#define SND_MIXER_ID_AUXA
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Aux A"
+\layout LyX-Code
+
+#define SND_MIXER_ID_AUXB
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Aux B"
+\layout LyX-Code
+
+#define SND_MIXER_ID_AUXC
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+"Aux C"
+\layout Subsubsection*
+
+int snd_mixer_channel_info(void *handle, int channel, snd_mixer_channel_info_t
+ *info)
+\layout Standard
+
+Fills the
+\shape italic
+*info
+\shape default
+ structure.
+ The argument
+\shape italic
+channel
+\shape default
+ specifies channel (0 to N) for which is the info requested.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+
+\shape italic
+/* mixer channel is record source */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_RECORD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00000001
+\layout LyX-Code
+
+
+\shape italic
+/* mixer channel is stereo */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_STEREO
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00000002
+\layout LyX-Code
+
+
+\shape italic
+/* always set at this moment\i \c{ }
+ driver emulates mute */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_MUTE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00000004
+\layout LyX-Code
+
+
+\shape italic
+/* channel supports hardware mute */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_HWMUTE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00000008
+\layout LyX-Code
+
+
+\shape italic
+/* channel does digital (not analog) mixing */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_DIGITAL
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0x00000010
+\layout LyX-Code
+
+
+\shape italic
+/* external input channel */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_INPUT
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0x00000020
+\layout LyX-Code
+
+
+\shape italic
+/* join mute is supported only */
+\layout LyX-Code
+
+
+\shape italic
+/* left and right channel doesn't have separate mute control */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_JOINMUTE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00000040
+\layout LyX-Code
+
+
+\shape italic
+/* join record is supported only *
+\layout LyX-Code
+
+
+\shape italic
+/* left and right channel doesn't have separate record control */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_JOINRECORD
+\protected_separator
+
+\protected_separator
+ 0x00000080
+\layout LyX-Code
+
+
+\shape italic
+/* route left input to right output is supported */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_LTOR_OUT
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00000100
+\layout LyX-Code
+
+
+\shape italic
+/* route right input to left output is supported */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_RTOL_OUT
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00000200
+\layout LyX-Code
+
+
+\shape italic
+/* route left input to right ADC is supported */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_LTOR_IN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0x00000400
+\layout LyX-Code
+
+
+\shape italic
+/* route right input to left ADC is supported */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_RTOL_IN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0x00000800
+\layout LyX-Code
+
+
+\shape italic
+/* output route is only switch (cannot be used separately) */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_SWITCH_OUT
+\protected_separator
+
+\protected_separator
+ 0x00001000
+\layout LyX-Code
+
+
+\shape italic
+/* input route is only switch (cannot be used separately) */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_SWITCH_IN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0x00002000
+\layout LyX-Code
+
+
+\shape italic
+/* data can be recorded even if output path is muted */
+\layout LyX-Code
+
+
+\shape italic
+/* (to avoid loopback) */
+\layout LyX-Code
+
+#define SND_MIXER_CINFO_CAP_RECORDBYMUTE
+\protected_separator
+ 0x00004000
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+struct snd_mixer_channel_info {
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* channel index (filled by application) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int channel;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* parent channel # or SND_MIXER_PARENT */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int parent;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* name of this device */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char name[12];
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* some flags about this device (SND_MIXER_CINFO_XXXX) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int caps;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* min.
+ value when exact mode (or always 0) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int min;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* max.
+ value when exact mode (or always 100) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int max;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* minimum decibel value (*100) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int min_dB;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* maximum decibel value (*100) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int max_dB;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* step decibel value (*100) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int step_dB;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[16];
+\layout LyX-Code
+
+};
+\layout Subsubsection*
+
+int snd_mixer_channel_read(void *handle, int channel, snd_mixer_channel_t
+ *data)
+\layout Standard
+
+Fills the
+\shape italic
+*data
+\shape default
+ structure.
+ The argument
+\shape italic
+channel
+\shape default
+ specifies the channel (0 to N) for which is data requested.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+/* channel record source flags */
+\layout LyX-Code
+
+#define SND_MIXER_FLG_RECORD_LEFT
+\protected_separator
+ 0x00000001
+\layout LyX-Code
+
+#define SND_MIXER_FLG_RECORD_RIGHT 0x00000002
+\layout LyX-Code
+
+#define SND_MIXER_FLG_RECORD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00000003
+\layout LyX-Code
+
+/* mute channel flags */
+\layout LyX-Code
+
+#define SND_MIXER_FLG_MUTE_LEFT
+\protected_separator
+
+\protected_separator
+0x00010000
+\layout LyX-Code
+
+#define SND_MIXER_FLG_MUTE_RIGHT
+\protected_separator
+ 0x00020000
+\layout LyX-Code
+
+#define SND_MIXER_FLG_MUTE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00030000
+\layout LyX-Code
+
+/* input to output route setup */
+\layout LyX-Code
+
+#define SND_MIXER_FLG_LTOR_OUT
+\protected_separator
+
+\protected_separator
+ 0x00100000
+\layout LyX-Code
+
+#define SND_MIXER_FLG_RTOL_OUT
+\protected_separator
+
+\protected_separator
+ 0x00200000
+\layout LyX-Code
+
+#define SND_MIXER_FLG_SWITCH_OUT
+\protected_separator
+ 0x00300000
+\layout LyX-Code
+
+/* input to ADC route setup */
+\layout LyX-Code
+
+#define SND_MIXER_FLG_LTOR_IN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00400000
+\layout LyX-Code
+
+#define SND_MIXER_FLG_RTOL_IN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00800000
+\layout LyX-Code
+
+#define SND_MIXER_FLG_SWITCH_IN
+\protected_separator
+
+\protected_separator
+ 0x00c00000
+\layout LyX-Code
+
+/* set volume in decibels from dB variables */
+\layout LyX-Code
+
+#define SND_MIXER_FLG_DECIBEL
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0x40000000
+\layout LyX-Code
+
+/* reserved for kernel use, don't use this flag from application */
+\layout LyX-Code
+
+#define SND_MIXER_FLG_FORCE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0x80000000
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+struct snd_mixer_channel {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* channel # (filled by application) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int channel;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* some flags to read/write (SND_MIXER_FLG_XXXX) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int flags;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* min - max when exact mode (or 0 - 100) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int left;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* min - max when exact mode (or 0 - 100) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int right;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* dB * 100 */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int left_dB;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* dB * 100 */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int right_dB;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[16];
+\layout LyX-Code
+
+};
+\layout Subsubsection*
+
+int snd_mixer_channel_write(void *handle, int channel, snd_mixer_channel_t
+ *data)
+\layout Standard
+
+Writes the
+\shape italic
+*data
+\shape default
+ structure to kernel.
+ The
+\shape italic
+channel
+\shape default
+ argument specifies the channel (0 to N) for which is data is to be applied.
+ Function returns zero if successful, otherwise it returns an error code.
+ This functions is the opposite of
+\shape italic
+snd_mixer_channel_read
+\shape default
+.
+\layout Subsubsection*
+
+int snd_mixer_read(void *handle, snd_mixer_callbacks_t *callbacks)
+\layout Standard
+
+This function reads and parses data from driver.
+ Parsed actions are returned back to the application using the
+\shape italic
+callbacks
+\shape default
+ structure.
+ Applications should not parse data from the driver in standard cases.
+ This function returns immediately after all data is read from driver.
+ Does not block process.
+\layout LyX-Code
+
+typedef struct snd_mixer_callbacks {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* should be used by application */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ void *private_data;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ void (*channel_was_changed)(void *private_data, int channel);
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ void (*switch_was_changed)(void *private_data,
+\protected_separator
+int switchn);
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use - must be NULL!!! */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ void *reserved[14];
+\layout LyX-Code
+
+} snd_mixer_callbacks_t;
+\layout Subsubsection
+
+Examples
+\layout Standard
+
+The following example shows installed mixer channels for sound card #0 and
+ mixer device #0 in the system, and also sets the master volume (if present)
+ to 50.
+\layout LyX-Code
+
+int card = 0, device = 0, err;
+\layout LyX-Code
+
+void *handle;
+\layout LyX-Code
+
+snd_mixer_info_t info;
+\layout LyX-Code
+
+snd_mixer_channel_t channel;
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+if ((err = snd_mixer_open(&handle, card, device)) < 0) {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ fprintf(stderr, "open failed: %s
+\backslash
+n", snd_strerror(err));
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ return;
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+if ((err = snd_mixer_info(handle, &info)) < 0) {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ fprintf(stderr, "info failed: %s
+\backslash
+n", snd_strerror(err));
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ snd_mixer_close(handle);
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ return;
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+printf("Installed MIXER channels for card #i and device %i: %i
+\backslash
+n",
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ card + 1, device,
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ info.channels);
+\layout LyX-Code
+
+master = snd_mixer_channel(handle, SND_MIXER_ID_MASTER);
+\layout LyX-Code
+
+if (master >= 0) {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ if ((err = snd_mixer_read(handle, master, &channel)) < 0) {
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ fprintf(stderr, "master read failed: %s
+\backslash
+n",
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ snd_strerror( err ));
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ snd_mixer_close( handle );
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ return;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ }
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ channel.left = channel.right = 50;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ if ((err = snd_mixer_write(handle, master, &channel)) < 0 ) {
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ fprintf(stderr, "master write failed: %s
+\backslash
+n",
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ snd_strerror( err ));
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ snd_mixer_close(handle);
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ return;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ }
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+snd_mixer_close(handle);
+\layout Section
+
+Digital Audio (PCM) Interface
+\layout Standard
+
+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 8 kHz (telephone quality) and
+ 48 kHz (DAT tapes).
+\layout Standard
+
+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).
+\layout Standard
+
+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 DAC.
+\layout Standard
+
+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 * 6 dB
+ .
+ This means that 8 bits sampling resolution gives dynamic range of 48 dB
+ and 16 bit resolution gives 96 dB.
+\layout Standard
+
+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 8 kHz/8 bits/mono but 48 kHz/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.5 Mbps 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.
+
+\layout Subsection
+
+Low-Level Layer
+\layout Standard
+
+Audio devices are opened exclusively for a selected direction.
+ This doesn't allow open from more than one processes for the same audio
+ device in the same direction, but does allow one open call to each playback
+ direction and second open call to record direction independently.
+ Audio devices return EBUSY error to applications when other applications
+ have already opened the requested direction.
+\layout Standard
+
+Low-Level layer supports these formats:
+\layout LyX-Code
+
+
+\shape italic
+/* muLaw compressed samples */
+\layout LyX-Code
+
+#define SND_PCM_SFMT_MU_LAW
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0
+\layout LyX-Code
+
+
+\shape italic
+/* aLaw compressed samples */
+\layout LyX-Code
+
+#define SND_PCM_SFMT_A_LAW
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+1
+\layout LyX-Code
+
+
+\shape italic
+/* Ima-ADPM 4:1 compressed samples */
+\layout LyX-Code
+
+#define SND_PCM_SFMT_IMA_ADPCM
+\protected_separator
+
+\protected_separator
+2
+\layout LyX-Code
+
+
+\shape italic
+/* Unsigned 8-bit samples (most common 8-bit format) */
+\layout LyX-Code
+
+#define SND_PCM_SFMT_U8
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 3
+\layout LyX-Code
+
+
+\shape italic
+/* Signed 16-bit Little Endian samples (most common 16-bit format) */
+\layout LyX-Code
+
+#define SND_PCM_SFMT_S16_LE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 4
+\layout LyX-Code
+
+
+\shape italic
+/* Signed 16-bit Big Endian samples */
+\layout LyX-Code
+
+#define SND_PCM_SFMT_S16_BE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 5
+\layout LyX-Code
+
+
+\shape italic
+/* Signed 8-bit samples */
+\layout LyX-Code
+
+#define SND_PCM_SFMT_S8
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 6
+\layout LyX-Code
+
+
+\shape italic
+/* Unsigned 16-bit Little Endian samples */
+\layout LyX-Code
+
+#define SND_PCM_SFMT_U16_LE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 7
+\layout LyX-Code
+
+
+\shape italic
+/* Unsigned 16-bit Big Endian samples */
+\layout LyX-Code
+
+#define SND_PCM_SFMT_U16_BE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 8
+\layout LyX-Code
+
+
+\shape italic
+/* MPEG 1/2 stream */
+\layout LyX-Code
+
+#define SND_PCM_SFMT_MPEG
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 9
+\layout LyX-Code
+
+
+\shape italic
+/* GSM stream */
+\layout LyX-Code
+
+#define SND_PCM_SFMT_GSM
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+10
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+#define SND_PCM_FMT_MU_LAW
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ (1 << SND_PCM_SFMT_MU_LAW)
+\layout LyX-Code
+
+#define SND_PCM_FMT_A_LAW
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+(1 << SND_PCM_SFMT_A_LAW)
+\layout LyX-Code
+
+#define SND_PCM_FMT_IMA_ADPCM
+\protected_separator
+
+\protected_separator
+(1 << SND_PCM_SFMT_IMA_ADPCM)
+\layout LyX-Code
+
+#define SND_PCM_FMT_U8
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ (1 << SND_PCM_SFMT_U8)
+\layout LyX-Code
+
+#define SND_PCM_FMT_S16_LE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ (1 << SND_PCM_SFMT_S16_LE)
+\layout LyX-Code
+
+#define SND_PCM_FMT_S16_BE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ (1 << SND_PCM_SFMT_S16_BE)
+\layout LyX-Code
+
+#define SND_PCM_FMT_S8
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ (1 << SND_PCM_SFMT_S8)
+\layout LyX-Code
+
+#define SND_PCM_FMT_U16_LE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ (1 << SND_PCM_SFMT_U16_LE)
+\layout LyX-Code
+
+#define SND_PCM_FMT_U16_BE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ (1 << SND_PCM_SFMT_U16_BE)
+\layout LyX-Code
+
+#define SND_PCM_FMT_MPEG
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ (1 << SND_PCM_SFMT_MPEG)
+\layout LyX-Code
+
+#define SND_PCM_FMT_GSM
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+(1 << SND_PCM_SFMT_GSM)
+\layout Standard
+
+Constants with prefix
+\shape italic
+SND_PCM_FMT_
+\shape default
+ are used in info structures and constants with prefix
+\shape italic
+SND_PCM_SFMT_
+\shape default
+ are used in format structures.
+\layout Standard
+
+ALSA PCM API uses an enhanced double buffering scheme.
+ This allows the user to implement a more comfortable buffer setup.
+ Audio buffer is separated to small fragments.
+ Each fragment has the same size.
+ Application can set wakeup limits like
+\begin_inset Quotes eld
+\end_inset
+
+I want to get recorded data when at least two fragments with size 160 bytes
+ are filled.
+\begin_inset Quotes erd
+\end_inset
+
+.
+ For more information you should see description of
+\shape italic
+snd_pcm_*_params_t
+\shape default
+ and
+\shape italic
+snd_pcm_*_status_t
+\shape default
+ structures and the
+\emph on
+snd_pcm_playback_status(), snd_pcm_record_status()
+\emph default
+functions, documented below.
+\layout Subsubsection*
+
+int snd_pcm_open(void **handle, int card, int device, int mode)
+\layout Standard
+
+Creates a new handle and opens a connection to the kernel sound audio interface
+ for sound card number
+\shape italic
+card
+\shape default
+ (0-N) and audio device number
+\shape italic
+device
+\shape default
+.
+ Function also checks if protocol is compatible to prevent use of old programs
+ with a new kernel API.
+ Function returns zero if successful otherwise it returns an error code.
+ Error code -EBUSY is returned when some process owns the selected direction.
+\layout Standard
+
+Default format after opening is mono
+\shape italic
+mu-Law
+\shape default
+ at 8000Hz.
+ This device can be used directly for playback of standard .au (Sparc) files.
+
+\layout Standard
+
+The following modes should be used for the
+\shape italic
+mode
+\shape default
+ argument:
+\layout LyX-Code
+
+#define SND_PCM_OPEN_PLAYBACK
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+(O_WRONLY)
+\layout LyX-Code
+
+#define SND_PCM_OPEN_RECORD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+(O_RDONLY)
+\layout LyX-Code
+
+#define SND_PCM_OPEN_DUPLEX
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+(O_RDWR)
+\layout Subsubsection*
+
+int snd_pcm_close(void *handle)
+\layout Standard
+
+Frees all resources allocated with audio handle and closes the connection
+ to the kernel sound audio interface.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout Subsubsection*
+
+int snd_pcm_file_descriptor(void *handle)
+\layout Standard
+
+Returns the file descriptor of the connection to the kernel sound audio
+ interface.
+ Function returns an error code if an error was encountered.
+\layout Standard
+
+The file descriptor should be used for the
+\shape italic
+select(2)
+\shape default
+ synchronous multiplexer function for setting the read direction.
+ Application should call
+\shape italic
+snd_pcm_read()
+\shape default
+ or
+\shape italic
+snd_pcm_write()
+\shape default
+ functions if data is waiting to be read or a write can be performed.
+ Calling these functions is highly recommended, as it leaves a place for
+ the API to do things like data conversions, if needed.
+\layout Subsubsection*
+
+int snd_pcm_block_mode(void *handle, int enable)
+\layout Standard
+
+Sets up block (default) or non-block mode for a handle.
+ Block mode suspends execution of a program when
+\shape italic
+snd_pcm_read()
+\shape default
+ or
+\shape italic
+snd_pcm_write()
+\shape default
+ is called for the time which is needed for the actual playback or record
+ over of the selected limit.
+ In non-block mode, programs aren't suspended and the above functions return
+ immediately with the count of bytes which were read or written by the driver.
+ When used in this way, don't try to use the entire buffer after the call,
+ but instead process the number of bytes returned, and call the function
+ again.
+\layout Subsubsection*
+
+int snd_pcm_info(void *handle, snd_pcm_info_t *info)
+\layout Standard
+
+Fills the
+\shape italic
+*info
+\shape default
+ structure with data about the PCM device selected by
+\shape italic
+*handle
+\shape default
+.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+
+\shape italic
+/* hardware have codec */
+\layout LyX-Code
+
+#define SND_PCM_INFO_CODEC
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0x00000001
+\layout LyX-Code
+
+#define SND_PCM_INFO_DSP
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+SND_PCM_INFO_CODEC
+\layout LyX-Code
+
+
+\shape italic
+/* this flag is reserved and should be never used */
+\layout LyX-Code
+
+
+\shape italic
+/* It remains for compatibility with Open Sound System driver.
+ */
+\layout LyX-Code
+
+#define SND_PCM_INFO_MMAP
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00000002
+\layout LyX-Code
+
+
+\shape italic
+/* playback direction is supported */
+\layout LyX-Code
+
+#define SND_PCM_INFO_PLAYBACK
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00000100
+\layout LyX-Code
+
+
+\shape italic
+/* record direction is supported */
+\layout LyX-Code
+
+#define SND_PCM_INFO_RECORD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00000200
+\layout LyX-Code
+
+#define SND_PCM_INFO_DUPLEX
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00000400
+\layout LyX-Code
+
+
+\shape italic
+/* rate for playback & record must be same */
+\layout LyX-Code
+
+#define SND_PCM_INFO_DUPLEX_LIMIT
+\protected_separator
+ 0x00000800
+\layout LyX-Code
+
+
+\shape italic
+/* duplex is supported only by mono (one channel) format */
+\layout LyX-Code
+
+#define SND_PCM_INFO_DUPLEX_MONO
+\protected_separator
+
+\protected_separator
+0x00001000
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+struct snd_pcm_info {
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* sound card type */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int type;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* see SND_PCM_INFO_XXXX */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int flags;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* ID of this PCM device */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char id[32];
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* name of this device */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char name[80];
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[64];
+\layout LyX-Code
+
+};
+\layout Subsubsection*
+
+int snd_pcm_playback_info(void *handle, snd_pcm_playback_info_t *info)
+\layout Standard
+
+Fills the *info structure with data about PCM playback.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+#define SND_PCM_PINFO_BATCH
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0x00000001
+\layout LyX-Code
+
+#define SND_PCM_PINFO_8BITONLY
+\protected_separator
+ 0x00000002
+\layout LyX-Code
+
+#define SND_PCM_PINFO_16BITONLY
+\protected_separator
+0x00000004
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+struct snd_pcm_playback_info {
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* see SND_PCM_PINFO_XXXX */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int flags;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* supported formats */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int formats;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* min rate (in Hz) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int min_rate;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* max rate (in Hz) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int max_rate;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* min channels - voices (probably always 1) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int min_channels;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* max channels - voices */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int max_channels;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* playback buffer size in bytes */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int buffer_size;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* min fragment size in bytes */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int min_fragment_size;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* max fragment size in bytes */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int max_fragment_size;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* align fragment value */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int fragment_align;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* supported formats directly by hardware */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int hw_formats;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* count of playback switches */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int switches;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[56];
+\layout LyX-Code
+
+};
+\layout Description
+
+SND_PCM_PINFO_BATCH Driver implements double buffering with this device.
+ This means that the chip used for data processing has its own memory, and
+ output will be more delayed than if a traditional codec chip is used.
+\layout Description
+
+SND_PCM_PINFO_8BITONLY If this bit is set, the driver uses 8-bit format
+ for 16-bit samples and does software conversion.
+ This bit is set on broken SoundBlaster 16/AWE sound cards which can't do
+ full 16-bit duplex.
+ If this bit is set application or higher digital audio layer should do
+ the conversion from 16-bit samples to 8-bit samples rather than making
+ the driver to do it in the kernel.
+\layout Description
+
+SND_PCM_PINFO_16BITONLY If this bit is set, driver uses 16-bit format for
+ 8-bit samples and does software conversion.
+ This bit is set on broken SoundBlaster 16/AWE sound cards which can't do
+ full 8-bit duplex.
+ If this bit is set the application or higher digital audio layer should
+ do conversion from 8-bit samples to 16-bit samples rather than making the
+ driver to do it in the kernel.
+
+\layout Subsubsection*
+
+int snd_pcm_record_info(void *handle, snd_pcm_record_info_t *info)
+\layout Standard
+
+Fills the *info structure.
+ Returns zero if successful, otherwise it returns an error code.
+
+\layout LyX-Code
+
+#define SND_PCM_RINFO_BATCH
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0x00000001
+\layout LyX-Code
+
+#define SND_PCM_RINFO_8BITONLY
+\protected_separator
+ 0x00000002
+\layout LyX-Code
+
+#define SND_PCM_RINFO_16BITONLY
+\protected_separator
+0x00000004
+\layout LyX-Code
+
+#define SND_PCM_RINFO_OVERRANGE
+\protected_separator
+0x00001000
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+struct snd_pcm_record_info {
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* see SND_PCM_RINFO_XXXX */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int flags;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* supported formats */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int formats;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* min rate (in Hz) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int min_rate;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* max rate (in Hz) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int max_rate;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* min channels - voices (probably always 1) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int min_channels;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* max channels - voices */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int max_channels;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* playback buffer size in bytes */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int buffer_size;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* min fragment size in bytes */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int min_fragment_size;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* max fragment size in bytes */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int max_fragment_size;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* align fragment value */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int fragment_align;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* supported formats directly by hardware */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int hw_formats;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* count of record switches */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int switches;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[56];
+\layout LyX-Code
+
+};
+\layout Description
+
+SND_PCM_RINFO_BATCH Driver implements double buffering with this device.
+ This means that the chip used for data processing has its own memory, and
+ input will be more delayed than if a traditional codec chip is used.
+\layout Description
+
+SND_PCM_RINFO_8BITONLY If this bit is set, the driver uses 8-bit format
+ for 16-bit samples and does software conversion.
+ This bit is set on broken SoundBlaster 16/AWE sound cards which can't do
+ full 16-bit duplex.
+ If this bit is set application or higher digital audio layer should do
+ the conversion from 16-bit samples to 8-bit samples rather than making
+ the driver to do it in the kernel.
+\layout Description
+
+SND_PCM_RINFO_16BITONLY If this bit is set, driver uses 16-bit format for
+ 8-bit samples and does software conversion.
+ This bit is set on broken SoundBlaster 16/AWE sound cards which can't do
+ full 8-bit duplex.
+ If this bit is set the application or higher digital audio layer should
+ do conversion from 8-bit samples to 16-bit samples rather than making the
+ driver to do it in the kernel.
+
+\layout Description
+
+SND_PCM_RINFO_OVERRANGE If this bit is set\i \c{ }
+ the hardware can do ADC over-range
+ detection.
+\layout Subsubsection*
+
+int snd_pcm_playback_switches(void *handle)
+\layout Standard
+
+Returns count of PCM playback switches.
+ In this contents switch means universal control interface between kernel
+ and application which allows variable type control.
+ Function returns count if successful, otherwise it returns an error code.
+ Return value should be zero if sound card doesn't have any PCM playback
+ switch.
+\layout Subsubsection*
+
+int snd_pcm_playback_switch(void *handle, const char *switch_id)
+\layout Standard
+
+Returns index for switch with name
+\shape italic
+switch_id
+\shape default
+.
+ Function returns switch index if successful, otherwise it returns an error
+ code.
+\layout Subsubsection*
+
+int snd_pcm_playback_switch_read(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_pcm_switch_t
+ *data)
+\layout Standard
+
+Fills the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout LyX-Code
+
+
+\shape italic
+/* 0 or 1 (enable member of union) */
+\layout LyX-Code
+
+#define SND_PCM_SW_TYPE_BOOLEAN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0
+\layout LyX-Code
+
+
+\shape italic
+/* 0 to 255 - from low to high (data8[0] member of union) */
+\layout LyX-Code
+
+#define SND_PCM_SW_TYPE_BYTE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+1
+\layout LyX-Code
+
+
+\shape italic
+/* 0 to 65535 - from low to high (data16[0] member of union) */
+\layout LyX-Code
+
+#define SND_PCM_SW_TYPE_WORD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+2
+\layout LyX-Code
+
+
+\shape italic
+/* 0 to 4294967296 \i \={ }
+ from low to high (data32[0] member of union) */
+\layout LyX-Code
+
+#define SND_PCM_SW_TYPE_DWORD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 3
+\layout LyX-Code
+
+
+\shape italic
+/* user type - no type control */
+\layout LyX-Code
+
+#define SND_PCM_SW_TYPE_USER
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+(~0)
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+struct snd_pcm_switch {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* switch index (filled by application) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int switchn;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* identification of switch (for driver) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char name[32];
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* type of switch value \i \={ }
+ See SND_PCM_SW_TYPE_XXXX */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int type;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* low range value */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int low;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* high range value */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int high;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ union {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int enable;
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* 0 = off\i \c{ }
+ 1 = on */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char data8[32];
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* 8-bit data */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned short data16[16];
+\protected_separator
+
+\shape italic
+/* 16-bit data */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int data32[8];
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* 32-bit data */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ } value;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* reserved for future use \i \={ }
+ must be zero !!! */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[32];
+\layout LyX-Code
+
+}
+\layout Subsubsection*
+
+int snd_pcm_playback_switch_write(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_pcm_switch_t
+ *data)
+\layout Standard
+
+Writes the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+ to kernel.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout Subsubsection*
+
+int snd_pcm_record_switches(void *handle)
+\layout Standard
+
+Returns count of PCM record switches.
+ In this context 'switch' means universal control interface between kernel
+ and application which allows various types of control.
+ Function returns count if successful, otherwise it returns an error code.
+ Return value should be zero if sound card doesn't have any PCM record switch.
+\layout Subsubsection*
+
+int snd_pcm_record_switch(void *handle, const char *switch_id)
+\layout Standard
+
+Returns index for switch with name
+\shape italic
+switch_id
+\shape default
+.
+ Function returns switch index if successful, otherwise it returns an error
+ code.
+\layout Subsubsection*
+
+int snd_pcm_record_switch_read(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_pcm_switch_t
+ *data)
+\layout Standard
+
+Fills the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout Subsubsection*
+
+int snd_pcm_record_switch_write(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_pcm_switch_t
+ *data)
+\layout Standard
+
+Writes the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+ to kernel.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout Subsubsection*
+
+int snd_pcm_playback_format(void *handle, snd_pcm_format_t *format)
+\layout Standard
+
+Sets up format, rate (in Hz) and number of channels for playback, in the
+ desired direction.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+struct snd_pcm_format {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int format;
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* SND_PCM_SFMT_XXXX */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int rate;
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* rate in Hz */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int channels;
+\protected_separator
+
+\shape italic
+/* channels (voices) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[16];
+\layout LyX-Code
+
+};
+\layout Subsubsection*
+
+int snd_pcm_record_format(void *handle, snd_pcm_format_t *format)
+\layout Standard
+
+Sets up format, rate (in Hz) and number of channels for used for recording
+ in the specified direction.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout LyX-Code
+
+struct snd_pcm_format {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int format;
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* SND_PCM_SFMT_XXXX */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int rate;
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* rate in Hz */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int channels;
+\protected_separator
+
+\shape italic
+/* channels (voices) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[16];
+\layout LyX-Code
+
+};
+\layout Subsubsection*
+
+int snd_pcm_playback_params(void *handle, snd_pcm_playback_params_t *params)
+\layout Standard
+
+Sets various parameters for playback direction.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout LyX-Code
+
+struct snd_pcm_playback_params {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int fragment_size;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int fragments_max;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int fragments_room;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use - must be filled with zero */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[16];
+\layout LyX-Code
+
+};
+\layout Description
+
+fragment_size Requested size of fragment.
+ This value should be aligned for current format (for example to 4 if stereo
+ 16-bit samples are used) or with the
+\shape italic
+fragment_align
+\shape default
+ variable from
+\shape italic
+snd_pcm_playback_info_t
+\shape default
+ structure.
+ Its range can be from
+\shape italic
+min_fragment_size
+\shape default
+ to
+\shape italic
+max_fragment_size
+\shape default
+.
+\layout Description
+
+fragments_max Maximum number of fragments in queue for wakeup.
+ This number doesn't include partly used fragments.
+ If the current count of filled playback fragments is greater than this
+ value the driver will block the application or return immediately back
+ if non-block mode is active.
+\layout Description
+
+fragments_room Minimum number of fragments writable for wakeup.
+ This value should in most cases be 1 which means return back to application
+ if at least one fragment is free for playback.
+ This value includes partly used fragments, too.
+\layout Subsubsection*
+
+int snd_pcm_record_params(void *handle, snd_pcm_record_params_t *params)
+\layout Standard
+
+Function sets various parameters for the recording direction.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+struct snd_pcm_record_params {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int fragment_size;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int fragments_min;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use - must be filled with zero */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[16];
+\layout LyX-Code
+
+};
+\layout Description
+
+fragment_size Requested size of fragment.
+ This value should be aligned for current format (for example to 4 if stereo
+ 16-bit samples are used) or set to the
+\shape italic
+fragment_align
+\shape default
+ variable from
+\shape italic
+snd_pcm_playback_info_t
+\shape default
+ structure.
+ Its range can be from
+\shape italic
+min_fragment_size
+\shape default
+ to
+\shape italic
+max_fragment_size
+\shape default
+.
+\layout Description
+
+fragments_min Minimum filled fragments for wakeup.
+ Driver blocks the application (if block mode is selected) until input buffer
+ is filled with less than the number of fragments specified with this value.
+\layout Subsubsection*
+
+int snd_pcm_playback_status(void *handle, snd_pcm_playback_status_t *status)
+\layout Standard
+
+Fills the
+\shape italic
+*status
+\shape default
+ structure.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+struct snd_pcm_playback_status {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int rate;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int fragments;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int fragment_size;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int count;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int queue;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int underrun;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ struct timeval time;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ struct timeval stime;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int scount;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use - must be filled with zero */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[16];
+\layout LyX-Code
+
+};
+\layout Description
+
+rate Real playback rate.
+ This value reflects hardware limitations.
+
+\layout Description
+
+fragments Currently allocated fragments by the driver for playback direction.
+\layout Description
+
+fragment_size Current fragment size used by driver for the playback direction.
+\layout Description
+
+count Count of bytes writable without blocking.
+\layout Description
+
+queue Count of bytes in queue.
+ Note:
+\shape italic
+(fragments*fragment_size) - queue
+\shape default
+ should not be equal to
+\shape italic
+count
+\shape default
+.
+\layout Description
+
+underrun This value tells the application the number of underruns since
+ the last call to
+\shape italic
+snd_pcm_playback_status
+\shape default
+\emph on
+()
+\emph default
+.
+
+\layout Description
+
+time Estimated time when the next written sample will actually be played
+ (time is always in the future).
+ The estimate is calculated with: current time + sample queue
+\emph on
+
+\emph default
+converted to time (number of samples waiting for write to device, i.e., the
+ same as the
+\emph on
+queue
+\emph default
+member above).
+ This value should be used for time synchronization.
+ Returned value is in the same format as returned from the standard C function
+
+\emph on
+gettimeofday
+\emph default
+(&
+\emph on
+time
+\emph default
+,
+\emph on
+NULL
+\emph default
+).
+ This variable contains valid information only if playback time mode is
+ enabled (see
+\shape italic
+snd_pcm_playback_time()
+\shape default
+ function).
+
+\layout Description
+
+stime Time when playback was started.
+ This variable contains valid information only if playback time mode is
+ enabled (see
+\shape italic
+snd_pcm_playback_time()
+\shape default
+ function).
+\layout Description
+
+scount Number of bytes processed (actually played) from playback start.
+ This number is not necessarily the same as byte count written by application.
+\layout Standard
+\added_space_top 0.3cm \added_space_bottom 0.3cm \align center
+
+\begin_inset Figure size 654 212
+file pcmbuf.ps
+width 3 100
+flags 9
+
+\end_inset
+
+
+\layout Standard
+
+The figure above shows an example situation in the audio playback buffer
+ in the ALSA driver.
+ The driver splits the audio buffer into 16
+\emph on
+fragments
+\emph default
+, each being
+\emph on
+ fragment_size
+\emph default
+bytes long.
+ Fragments 0 and 12-15 are filled with samples.
+ Fragment 1 is filled partly (about 75%).
+ Driver is playing and current playback position is in fragment 12 (about
+ 35%).
+ As you can see\i \c{ }
+ free space (structure member
+\shape italic
+count
+\shape default
+) is counted without including the fragment which is being played.
+\layout Subsubsection*
+
+int snd_pcm_record_status(void *handle, snd_pcm_record_status_t *status)
+\layout Standard
+
+Fills the
+\shape italic
+*status
+\shape default
+ structure.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+struct snd_pcm_record_status {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int rate;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int fragments;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int fragment_size;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int count;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int free;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int overrun;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ struct timeval time;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ struct timeval stime;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int scount;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int overrange;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use - must be filled with zero */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[16];
+\layout LyX-Code
+
+};
+\layout Description
+
+rate Real record rate.
+ This value reflects hardware limitations.
+\layout Description
+
+fragments Currently allocated fragments by driver for the record direction.
+\layout Description
+
+fragment_size Current fragment size used by driver for the record direction.
+\layout Description
+
+count Count of bytes readable without blocking.
+\layout Description
+
+free Count of bytes in buffer still free.
+ Note:
+\shape italic
+(fragments*fragment_size) - free
+\shape default
+ should not be equal to
+\shape italic
+count
+\shape default
+.
+\layout Description
+
+overrun This value tells application the count of overruns since the last
+ call to
+\shape italic
+snd_pcm_record_status
+\shape default
+.
+\layout Description
+
+time Returns a timestamp for the next sample to be read from the record
+ ring buffer (time is always in the past).
+ The timestamp is calculated with: current time - sample queue converted
+ to time (waiting for application read() + current position in fragment
+ is the same as record count + current position in fragment).
+ This value should be used for time synchronization.
+ Returned value is in the same format as returned by the standard C function
+ gettimeofday(&time, NULL).
+ This variable contains right valid information only if record time mode
+ is enabled (see
+\shape italic
+snd_pcm_record_time()
+\shape default
+ function).
+
+\layout Description
+
+stime Time when record was started.
+ This variable contains valid information only if record time mode is enabled
+ (see
+\shape italic
+snd_pcm_record_time
+\shape default
+ function).
+\layout Description
+
+scount Number of bytes processed (actually recorded) from record start (stime).
+ This number is not necessarily the same as the byte count read by application.
+\layout Description
+
+overrange ADC overrange count.
+ This value is used only when
+\shape italic
+SND_PCM_RINFO_OVERRANGE
+\shape default
+ bit in
+\shape italic
+struct snd_pcm_record_info_t->flags
+\shape default
+ is set (if hardware supports this feature).
+\layout Standard
+\added_space_top 0.3cm \added_space_bottom 0.3cm \align center
+
+\begin_inset Figure size 595 121
+file pcmbuf1.ps
+width 3 100
+flags 9
+
+\end_inset
+
+
+\layout Standard
+
+The figure above shows an example situation in the audio record buffer in
+ the ALSA driver.
+ The driver splits the audio buffer into 16
+\emph on
+fragments
+\emph default
+, each being
+\emph on
+fragment_size
+\emph default
+bytes in length.
+ Fragments 0 and 12-15 are filled with samples.
+ Fragment 1 is partly filled (about 75%) and at the end of the filled area
+ is the active record position.
+ Data which is ready for the application begins in fragment 12 (about 35%).
+ As you can see\i \c{ }
+ free space (structure member
+\shape italic
+free
+\shape default
+) is counted without including the fragment which is partly filled with
+ samples and the application reads data from this fragment.
+\layout Subsubsection*
+
+int snd_pcm_drain_playback(void *handle)
+\layout Standard
+
+This function stops and drains (destroys) the playback buffers immediately.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout Subsubsection*
+
+int snd_pcm_flush_playback(void *handle)
+\layout Standard
+
+This function flushes the playback buffers.
+ It blocks the program while the all the waiting samples in kernel playback
+ buffers are processed.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout Subsubsection*
+
+int snd_pcm_flush_record(void *handle)
+\layout Standard
+
+This function flushes (destroys) record buffers.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout Subsubsection*
+
+int snd_pcm_playback_pause(void *handle\i \c{ }
+ int enable)
+\layout Standard
+
+This function pauses playback if
+\shape italic
+enable
+\shape default
+ is non-zero.
+ To restore playing mode call this function with
+\shape italic
+enable
+\shape default
+ equal to zero.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout Subsubsection*
+
+int snd_pcm_playback_time(void *handle, int enable)
+\layout Standard
+
+This function enables or disables time mode for the playback direction.
+ Time mode is useful in synchronizing an application with other events.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout Subsubsection*
+
+int snd_pcm_record_time(void *handle, int enable)
+\layout Standard
+
+This function enables or disables time mode for record direction.
+ Time mode is useful in synchronizing an application with other events.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout Subsubsection*
+
+ssize_t snd_pcm_write(void *handle, const void *buffer, size_t size)
+\layout Standard
+
+Writes samples to the device which must be in the proper format specified
+ by the
+\shape italic
+snd_pcm_playback_format
+\shape default
+ function.
+ Function returns zero or positive value if playback was successful (value
+ represents count of bytes which were successfully written to device) or
+ an error value if an error occurred.
+ Function will suspend process if block mode is active.
+\layout Subsubsection*
+
+ssize_t snd_pcm_read(void *handle, void *buffer, size_t size)
+\layout Standard
+
+Function reads samples from driver.
+ Samples are in format specified by
+\shape italic
+snd_pcm_record_format
+\shape default
+ function.
+ Function returns zero or positive value if record was success (value represents
+ count of bytes which was successfully read from device) or negative error
+ value if error occurred.
+ Function will suspend process if block mode is active.
+\layout Subsubsection
+
+Example
+\layout Standard
+
+The following example shows how to play the first 512kB from the /tmp/test.au
+ file with sound card #0 and PCM device #0:
+\layout LyX-Code
+
+int card = 0, device = 0, err, fd, count, size, idx;
+\layout LyX-Code
+
+void *handle;
+\layout LyX-Code
+
+snd_pcm_format_t format;
+\layout LyX-Code
+
+char *buffer;
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+buffer = (char *)malloc(512 * 1024);
+\layout LyX-Code
+
+if (!buffer) return;
+\layout LyX-Code
+
+if ((err = snd_pcm_open(&handle, card, device,
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ SND_PCM_OPEN_PLAYBACK)) < 0) {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ fprintf(stderr, "open failed: %s
+\backslash
+n", snd_strerror( err ));
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ return;
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+bzero(&format\i \c{ }
+ sizeof(format));
+\layout LyX-Code
+
+format.format = SND_PCM_SFMT_MU_LAW;
+\layout LyX-Code
+
+format.rate = 8000;
+\layout LyX-Code
+
+format.channels = 1;
+\layout LyX-Code
+
+if ((err = snd_pcm_playback_format(handle, &format)) < 0) {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ fprintf(stderr, "format setup failed: %s
+\backslash
+n",
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+snd_strerror( err ));
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ snd_pcm_close( handle );
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ return;
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+fd = open("/tmp/test.au", O_RDONLY);
+\layout LyX-Code
+
+if (fd < 0) {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ perror("open file");
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ snd_pcm_close(handle);
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ return;
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+idx = 0;
+\layout LyX-Code
+
+count = read(fd, buffer, 512 * 1024);
+\layout LyX-Code
+
+if (count <= 0) {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ perror("read from file");
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ snd_pcm_close( handle );
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ return;
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+close( fd );
+\layout LyX-Code
+
+if (!memcmp(buffer, ".snd", 4)) {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ idx = (buffer[4]<<24)|(buffer[5]<<16)|
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ (buffer[6]<<8)|(buffer[7]);
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ if (idx > 128) idx = 128;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ if (idx > count) idx = count;
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+size = snd_pcm_write(handle, &buffer[ idx ], count - idx);
+\layout LyX-Code
+
+printf("Bytes written %i from %i...
+\backslash
+n", size, count - idx);
+\layout LyX-Code
+
+snd_pcm_close(handle);
+\layout LyX-Code
+
+free(buffer);
+\layout Subsection
+
+PCM Loopback Interface
+\layout Standard
+
+This interface is designed to pass data currently being played or recorded
+ from one application to another application for other processing like a
+ graphical equalizer\i \c{ }
+ sample recorder etc...
+ The programmer should be aware that each loopback connection eats CPU time
+ (for data copying from the process which is doing the playback or record).
+\layout Subsubsection*
+
+int snd_pcm_loopback_open(void **handle, int card, int device, int mode)
+\layout Standard
+
+Creates a new handle and opens a connection to the kernel sound audio loopback
+ interface for sound card number
+\shape italic
+card
+\shape default
+ (0-N) and audio device number
+\shape italic
+device
+\shape default
+.
+ Function also checks if protocol is compatible to prevent use of old programs
+ with a new kernel API.
+ Function returns zero if successful otherwise it returns an error code.
+ Error code -EBUSY is returned when another process owns the selected direction.
+\layout Standard
+
+The following modes should be used for the
+\shape italic
+mode
+\shape default
+ argument:
+\layout LyX-Code
+
+#define SND_PCM_LB_OPEN_PLAYBACK
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0
+\layout LyX-Code
+
+#define SND_PCM_LB_OPEN_RECORD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+1
+\layout Subsubsection*
+
+int snd_pcm_loopback_close(void *handle)
+\layout Standard
+
+Frees all resources allocated with audio handle and closes the connection
+ to the kernel sound audio interface.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout Subsubsection*
+
+int snd_pcm_loopback_file_descriptor(void *handle)
+\layout Standard
+
+Returns the file descriptor of the connection to the kernel sound audio
+ interface.
+ Function returns an error code if an error was encountered.
+\layout Standard
+
+The file descriptor should be used for the
+\shape italic
+select(2)
+\shape default
+ synchronous multiplexer function for setting the read direction.
+ Application should call
+\shape italic
+snd_pcm_loopback_read()
+\shape default
+ function if data is waiting to be read.
+\layout Subsubsection*
+
+int snd_pcm_loopback_block_mode(void *handle, int enable)
+\layout Standard
+
+Sets up block (default) or non-block mode for a handle.
+ Block mode suspends execution of a program when
+\shape italic
+snd_pcm_loopback_read()
+\shape default
+ is called for the time until some data arrives for file descriptor.
+ In non-block mode, programs aren't suspended and the above function returns
+ immediately with the count of bytes which were read by the driver.
+ When used in this way, don't try to use the entire buffer after the call,
+ but instead process the number of bytes returned, and call the function
+ again.
+\layout Subsubsection*
+
+int snd_pcm_loopback_stream_mode(void *handle, int mode)
+\layout Standard
+
+Sets up stream mode which should be one of these values:
+\layout LyX-Code
+
+#define SND_PCM_LB_STREAM_MODE_RAW
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0
+\layout LyX-Code
+
+#define SND_PCM_LB_STREAM_MODE_PACKET
+\protected_separator
+1
+\layout Standard
+
+Mode raw (default mode) means that the stream contains only PCM samples.
+ Packet mode is more complicated.
+ The stream contains a header at the begining of the packet.
+ Information like data type and data size is contain in this header.
+\layout LyX-Code
+
+#define SND_PCM_LB_TYPE_DATA
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0
+\protected_separator
+
+\shape italic
+/* sample data */
+\layout LyX-Code
+
+#define SND_PCM_LB_TYPE_FORMAT
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 1
+\protected_separator
+
+\shape italic
+/* PCM format */
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+struct snd_pcm_loopback_header {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int size;
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* block size */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int type;
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* block type (SND_PCM_LB_TYPE_*) */
+\layout LyX-Code
+
+};
+\layout Subsubsection*
+
+int snd_pcm_loopback_format(void *handle, snd_pcm_format_t *format)
+\layout Standard
+
+Get current format for PCM stream.
+
+\layout LyX-Code
+
+struct snd_pcm_format {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int format;
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* SND_PCM_SFMT_XXXX */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int rate;
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* rate in Hz */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int channels;
+\protected_separator
+
+\shape italic
+/* number of channels (voices) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[16];
+\layout LyX-Code
+
+};
+\layout Subsubsection*
+
+ssize_t snd_pcm_loopback_read(void *handle, void *buffer, size_t size)
+\layout Standard
+
+This function reads samples or loopback packets from the stream.
+ Data depends on stream mode which should be set with
+\shape italic
+snd_pcm_loopback_stream_mode()
+\shape default
+ function.
+ Function returns zero or positive value if record was success (value represents
+ count of bytes which were successfully read from device) or negative error
+ value if error occurred.
+ Function will suspend process if block mode is active.
+\layout Section
+
+RawMidi Interface
+\layout Standard
+
+RawMidi Interface is designed to write or read raw (unchanged) MIDI data
+ over the MIDI line.
+ MIDI stands Musical Instrument Digital Interface and more informations
+ about this standard can be found at
+\series bold
+http://www.midi.org
+\series default
+.
+\layout Subsection
+
+Low Level Layer
+\layout Standard
+
+RawMidi devices are opened exclusively for a selected direction.
+ While more than one process may not open a given MIDI device in the same
+ direction simultaniously, seperate processes may open a single MIDI device
+ in different directions (i.e.
+ process one opens a MIDI device in playback direction and process two opens
+ the same device in record direction).
+ Audio devices (with MIDI ports) return EBUSY error to applications when
+ other applications have already opened the requested direction.
+\layout Subsubsection*
+
+int snd_rawmidi_open(void **handle, int card, int device, int mode)
+\layout Standard
+
+Creates a new handle and opens a connection to the kernel sound audio interface
+ for sound card number
+\shape italic
+card
+\shape default
+ (0-N) and rawmidi device number
+\shape italic
+device
+\shape default
+.
+ Function also checks if protocol is compatible to prevent use of old programs
+ with a new kernel API.
+ Function returns zero if successful, otherwise it returns an error code.
+ Error code -EBUSY is returned when another process owns the selected direction.
+\layout Standard
+
+The following modes should be used for the
+\shape italic
+mode
+\shape default
+ argument:
+\layout LyX-Code
+
+#define SND_RAWMIDI_OPEN_OUTPUT
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+(O_WRONLY)
+\layout LyX-Code
+
+#define SND_RAWMIDI_OPEN_INPUT
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+(O_RDONLY)
+\layout LyX-Code
+
+#define SND_RAWMIDI_OPEN_DUPLEX
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+(O_RDWR)
+\layout Subsubsection*
+
+int snd_rawmidi_close(void *handle)
+\layout Standard
+
+Frees all resources allocated with audio handle and closes the connection
+ to the kernel sound rawmidi interface.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout Subsubsection*
+
+int snd_rawmidi_file_descriptor(void *handle)
+\layout Standard
+
+Returns the file descriptor of the connection to the kernel sound audio
+ interface.
+ Function returns an error code if an error was encountered.
+\layout Standard
+
+The file descriptor should be used for the
+\shape italic
+select(2)
+\shape default
+ synchronous multiplexer function for setting the read direction.
+ Application should call
+\shape italic
+snd_rawmidi_read()
+\shape default
+ or
+\shape italic
+snd_rawmidi_write()
+\shape default
+ functions if data is waiting to be read or a write can be performed.
+ Calling these functions is highly recommended.
+\layout Subsubsection*
+
+int snd_rawmidi_block_mode(void *handle, int enable)
+\layout Standard
+
+Sets up block (default) or non-block mode for a handle.
+ Block mode suspends execution of a program when
+\shape italic
+snd_rawmidi_read()
+\shape default
+ or
+\shape italic
+snd_rawmidi_write()
+\shape default
+ is called for the time which is needed for the actual output or input over
+ of the selected limit.
+ In non-block mode, programs aren't suspended and the above functions return
+ immediately with the count of bytes which were read or written by the driver.
+ When used in this way, don't try to use the entire buffer after the call,
+ but instead process the number of bytes returned, and call the function
+ again.
+\layout Subsubsection*
+
+int snd_rawmidi_info(void *handle, snd_pcm_info_t *info)
+\layout Standard
+
+Fills the
+\shape italic
+*info
+\shape default
+ structure with data about the PCM device selected by
+\shape italic
+*handle
+\shape default
+.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+
+\shape italic
+/*
+\shape default
+ device is capable rawmidi output *
+\shape italic
+/
+\layout LyX-Code
+
+#define SND_RAWMIDI_INFO_OUTPUT
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0x00000001
+\layout LyX-Code
+
+
+\shape italic
+/* device is capable rawmidi input */
+\layout LyX-Code
+
+#define SND_RAWMIDI_INFO_INPUT
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0x00000002
+\layout LyX-Code
+
+
+\shape italic
+/* device is capable duplex mode */
+\layout LyX-Code
+
+#define SND_RAWMIDI_INFO_DUPLEX
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+0x00000004
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+struct snd_rawmidi_info {
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* sound card type */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int type;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* see SND_RAWMIDI_INFO_XXXX */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int flags;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* ID of this PCM device */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char id[32];
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* name of this device */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char name[80];
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[64];
+\layout LyX-Code
+
+};
+\layout Subsubsection*
+
+int snd_rawmidi_output_info(void *handle, snd_rawmidi_output_info_t *info)
+\layout Standard
+
+Fills the *info structure with data about rawmidi output.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+struct snd_rawmidi_output_info {
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* count of output switches */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int switches;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[64];
+\layout LyX-Code
+
+};
+\layout Subsubsection*
+
+int snd_rawmidi_input_info(void *handle, snd_pcm_record_info_t *info)
+\layout Standard
+
+Fills the *info structure.
+ Returns zero if successful, otherwise it returns an error code.
+
+\layout LyX-Code
+
+struct snd_rawmidi_input_info {
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* count of output switches */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int switches;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[64];
+\layout LyX-Code
+
+};
+\layout Subsubsection*
+
+int snd_rawmidi_output_switches(void *handle)
+\layout Standard
+
+Returns count of rawmidi output switches.
+ In this context 'switch' means universal control interface between kernel
+ and application which allows various types of control.
+ Function returns count if successful, otherwise it returns an error code.
+ Return value should be zero if sound card doesn't have any rawmidi output
+ switch.
+\layout Subsubsection*
+
+int snd_rawmidi_output_switch(void *handle, const char *switch_id)
+\layout Standard
+
+Returns index for switch with name
+\shape italic
+switch_id
+\shape default
+.
+ Function returns switch index if successful, otherwise it returns an error
+ code.
+\layout Subsubsection*
+
+int snd_rawmidi_output_switch_read(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_rawmidi_switch_t
+ *data)
+\layout Standard
+
+Fills the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout LyX-Code
+
+
+\shape italic
+/* 0 or 1 (enable member of union) */
+\layout LyX-Code
+
+#define SND_PCM_SW_TYPE_BOOLEAN
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 0
+\layout LyX-Code
+
+
+\shape italic
+/* 0 to 255 - from low to high (data8[0] member of union) */
+\layout LyX-Code
+
+#define SND_PCM_SW_TYPE_BYTE
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+1
+\layout LyX-Code
+
+
+\shape italic
+/* 0 to 65535 - from low to high (data16[0] member of union) */
+\layout LyX-Code
+
+#define SND_PCM_SW_TYPE_WORD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+2
+\layout LyX-Code
+
+
+\shape italic
+/* 0 to 4294967296 \i \={ }
+ from low to high (data32[0] member of union) */
+\layout LyX-Code
+
+#define SND_PCM_SW_TYPE_DWORD
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ 3
+\layout LyX-Code
+
+
+\shape italic
+/* user type - no type control */
+\layout LyX-Code
+
+#define SND_PCM_SW_TYPE_USER
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+(~0)
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+struct snd_rawmidi_switch {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* switch index (filled by application) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int switchn;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* identification of switch (for driver) */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char name[32];
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* type of switch value \i \={ }
+ See SND_PCM_SW_TYPE_XXXX */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int type;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* low range value */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int low;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* high range value */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int high;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ union {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int enable;
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* 0 = off\i \c{ }
+ 1 = on */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char data8[32];
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* 8-bit data */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned short data16[16];
+\protected_separator
+
+\shape italic
+/* 16-bit data */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned int data32[8];
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* 32-bit data */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ } value;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\shape italic
+/* reserved for future use \i \={ }
+ must be zero !!! */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[32];
+\layout LyX-Code
+
+}
+\layout Subsubsection*
+
+int snd_rawmidi_output_switch_write(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_rawmidi_switch_
+t *data)
+\layout Standard
+
+Writes the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+ to kernel.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout Subsubsection*
+
+int snd_rawmidi_input_switches(void *handle)
+\layout Standard
+
+Returns count of rawmidi input switches.
+ In this context 'switch' means universal control interface between kernel
+ and application which allows various types of control.
+ Function returns count if successful, otherwise it returns an error code.
+ Return value should be zero if sound card doesn't have any rawmidi input
+ switch.
+\layout Subsubsection*
+
+int snd_rawmidi_input_switch(void *handle, const char *switch_id)
+\layout Standard
+
+Returns index for switch with name
+\shape italic
+switch_id
+\shape default
+.
+ Function returns switch index if successful, otherwise it returns an error
+ code.
+\layout Subsubsection*
+
+int snd_rawmidi_input_switch_read(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_rawmidi_switch_t
+ *data)
+\layout Standard
+
+Fills the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout Subsubsection*
+
+int snd_rawmidi_input_switch_write(void *handle\i \c{ }
+ int switchn\i \c{ }
+ snd_rawmidi_switch_t
+ *data)
+\layout Standard
+
+Writes the
+\shape italic
+*data
+\shape default
+ structure with data about switch with index
+\shape italic
+switchn
+\shape default
+ to kernel.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout Subsubsection*
+
+int snd_rawmidi_output_params(void *handle, snd_rawmidi_output_params_t
+ *params)
+\layout Standard
+
+Sets various parameters for output direction.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout LyX-Code
+
+struct snd_rawmidi_output_params {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int size;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int max;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int room;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use - must be filled with zero */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[16];
+\layout LyX-Code
+
+};
+\layout Description
+
+size Requested queue size of output buffer in bytes (default setup is 4096
+ [i386] or 8192 [alpha] bytes - this is system architecture dependent).
+\layout Description
+
+max Maximum number of bytes in queue for wakeup.
+ If the current byte count of filled portion of output buffer is greater
+ than this value the driver will block an application or return immediately
+ if non block mode is active.
+\layout Description
+
+room Minimum number of bytes writable for wakeup.
+ This value should be in most cases 1 which means return back to application
+ if at least one byte is free in output buffer.
+\layout Subsubsection*
+
+int snd_rawmidi_input_params(void *handle, snd_rawmidi_input_params_t *params)
+\layout Standard
+
+Function sets various parameters for the recording direction.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+struct snd_rawmidi_input_params {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int size;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int min;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use - must be filled with zero */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[16];
+\layout LyX-Code
+
+};
+\layout Description
+
+size Requested queue size of input buffer in bytes (default setup is 4096
+ [i386] or 8192 [alpha] bytes - this is system architecture dependent).
+\layout Description
+
+min Minimum filled bytes in queue for wakeup.
+ Driver blocks the application (if block mode is selected) until input buffer
+ is filled with fewer than the number of bytes specified with this value.
+\layout Subsubsection*
+
+int snd_rawmidi_output_status(void *handle, snd_rawmidi_output_status_t
+ *status)
+\layout Standard
+
+Fills the
+\shape italic
+*status
+\shape default
+ structure.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+struct snd_rawmidi_output_status {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int size;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int count;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int queue;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use - must be filled with zero */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[16];
+\layout LyX-Code
+
+};
+\layout Description
+
+size Size of currently allocated queue in bytes.
+\layout Description
+
+count Count of bytes writable without blocking.
+\layout Description
+
+queue Count of bytes in queue (number of bytes waiting to be output).
+\layout Subsubsection*
+
+int snd_rawmidi_input_status(void *handle, snd_rawmidi_input_status_t *status)
+\layout Standard
+
+Fills the
+\shape italic
+*status
+\shape default
+ structure.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout LyX-Code
+
+struct snd_rawmidi_input_status {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int size;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int count;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int free;
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ int overrun;
+\layout LyX-Code
+
+
+\shape italic
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ /* reserved for future use - must be filled with zero */
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ unsigned char reserved[16];
+\layout LyX-Code
+
+};
+\layout Description
+
+size Size of currently allocated queue in bytes.
+\layout Description
+
+count Count of bytes readable without blocking.
+\layout Description
+
+free Count of bytes in queue still free.
+\layout Description
+
+overrun This value tells the application the count of overruns since the
+ last call to
+\shape italic
+snd_rawmidi_input_status
+\shape default
+.
+\layout Subsubsection*
+
+int snd_rawmidi_drain_output(void *handle)
+\layout Standard
+
+This function stops and drains (destroys) the output queue immediately.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout Subsubsection*
+
+int snd_rawmidi_flush_output(void *handle)
+\layout Standard
+
+This function flushes the output queue.
+ It blocks the program while the all the waiting bytes in kernel output
+ queue are processed.
+ Function returns zero if successful, otherwise it returns an error code.
+\layout Subsubsection*
+
+int snd_rawmidi_flush_input(void *handle)
+\layout Standard
+
+This function flushes (destroys) input queue.
+ Function returns zero if successful, otherwise it returns an error code.
+
+\layout Subsubsection*
+
+ssize_t snd_rawmidi_write(void *handle, const void *buffer, size_t size)
+\layout Standard
+
+Writes bytes to the output queue.
+ Function returns zero or positive value if the write was successful (value
+ represents count of bytes which were successfully written to the device)
+ or an error value if error occurred.
+ Function will suspend the process if block mode is active.
+\layout Subsubsection*
+
+ssize_t snd_rawmidi_read(void *handle, void *buffer, size_t size)
+\layout Standard
+
+Function reads bytes from input queue.
+ Function returns zero or positive value if the read was successful (value
+ represents count of bytes which were successfully read from device) or
+ negative error value if error occurred.
+ Function will suspend the process if block mode is active.
+\layout Subsubsection
+
+Example
+\layout Standard
+
+The following example shows how to send a control sequence (such as SysEx)
+ to a MIDI device.
+ Sound card #0 and rawmidi device #0 are used here:
+\layout LyX-Code
+
+int card = 0, device = 0, err, fd, count, size;
+\layout LyX-Code
+
+void *handle;
+\layout LyX-Code
+
+snd_pcm_format_t format;
+\layout LyX-Code
+
+char *buffer;
+\layout Standard
+
+
+\protected_separator
+
+\layout LyX-Code
+
+buffer = (char *)malloc(64 * 1024);
+\layout LyX-Code
+
+if (!buffer) return;
+\layout LyX-Code
+
+if ((err = snd_rawmidi_open(&handle, card, device,
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ SND_RAWMIDI_OPEN_OUTPUT)) < 0) {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ fprintf(stderr, "open failed: %s
+\backslash
+n", snd_strerror( err ));
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ return;
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+if ((err = snd_rawmidi_block_mode(handle\i \c{ }
+ 1)) < 0) {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ fprintf(stderr, "block failed: %s
+\backslash
+n", snd_strerror( err ));
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ snd_rawmidi_close(handle);
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ return;
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+fd = open("/tmp/test.sysex", O_RDONLY);
+\layout LyX-Code
+
+if (fd < 0) {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ perror("open file");
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ snd_rawmidi_close(handle);
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ return;
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+idx = 0;
+\layout LyX-Code
+
+count = read(fd, buffer, 64 * 1024);
+\layout LyX-Code
+
+if (count <= 0) {
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ perror("read from file");
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ snd_rawmidi_close(handle);
+\layout LyX-Code
+
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+
+\protected_separator
+ return;
+\layout LyX-Code
+
+}
+\layout LyX-Code
+
+close(fd);
+\layout LyX-Code
+
+size = snd_rawmidi_write(handle, &buffer, count);
+\layout LyX-Code
+
+printf("Bytes written %i from %i...
+\backslash
+n", size, count);
+\layout LyX-Code
+
+snd_rawmidi_close(handle);
+\layout LyX-Code
+
+free(buffer);
+\the_end
--- /dev/null
+%!PS-Adobe-2.0
+%%Title: pcmbuf-v1.ps
+%%Creator: fig2dev Version 3.2 Patchlevel 1
+%%CreationDate: Sat Jan 9 11:22:52 1999
+%%For: emng@cyphyn.219.org (Fred Floberg,,,,)
+%%Orientation: Portrait
+%%BoundingBox: 67 318 544 473
+%%Pages: 1
+%%BeginSetup
+%%IncludeFeature: *PageSize Letter
+%%EndSetup
+%%Magnification: 1.0000
+%%EndComments
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col1 {0.000 0.000 1.000 srgb} bind def
+/col2 {0.000 1.000 0.000 srgb} bind def
+/col3 {0.000 1.000 1.000 srgb} bind def
+/col4 {1.000 0.000 0.000 srgb} bind def
+/col5 {1.000 0.000 1.000 srgb} bind def
+/col6 {1.000 1.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col8 {0.000 0.000 0.560 srgb} bind def
+/col9 {0.000 0.000 0.690 srgb} bind def
+/col10 {0.000 0.000 0.820 srgb} bind def
+/col11 {0.530 0.810 1.000 srgb} bind def
+/col12 {0.000 0.560 0.000 srgb} bind def
+/col13 {0.000 0.690 0.000 srgb} bind def
+/col14 {0.000 0.820 0.000 srgb} bind def
+/col15 {0.000 0.560 0.560 srgb} bind def
+/col16 {0.000 0.690 0.690 srgb} bind def
+/col17 {0.000 0.820 0.820 srgb} bind def
+/col18 {0.560 0.000 0.000 srgb} bind def
+/col19 {0.690 0.000 0.000 srgb} bind def
+/col20 {0.820 0.000 0.000 srgb} bind def
+/col21 {0.560 0.000 0.560 srgb} bind def
+/col22 {0.690 0.000 0.690 srgb} bind def
+/col23 {0.820 0.000 0.820 srgb} bind def
+/col24 {0.500 0.190 0.000 srgb} bind def
+/col25 {0.630 0.250 0.000 srgb} bind def
+/col26 {0.750 0.380 0.000 srgb} bind def
+/col27 {1.000 0.500 0.500 srgb} bind def
+/col28 {1.000 0.630 0.630 srgb} bind def
+/col29 {1.000 0.750 0.750 srgb} bind def
+/col30 {1.000 0.880 0.880 srgb} bind def
+/col31 {1.000 0.840 0.000 srgb} bind def
+
+end
+save
+56.5 503.5 translate
+1 -1 scale
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+ 4 -2 roll dup 1 exch sub 3 -1 roll mul add
+ 4 -2 roll dup 1 exch sub 3 -1 roll mul add
+ 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+ bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+ 4 -2 roll mul srgb} bind def
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+%%EndProlog
+
+$F2psBegin
+10 setmiterlimit
+n -1000 3934 m -1000 -1000 l 8744 -1000 l 8744 3934 l cp clip
+ 0.06299 0.06299 sc
+%%Page: 1 1
+% Polyline
+7.500 slw
+ [60] 0 sd
+gs clippath
+6224 1493 m 6300 1395 l 6279 1517 l 6333 1393 l 6279 1369 l cp
+clip
+n 6300 1395 m 5670 2835 l 5985 2835 l gs col0 s gr gr
+ [] 0 sd
+% arrowhead
+n 6224 1493 m 6300 1395 l 6279 1517 l col0 s
+% Polyline
+ [60] 0 sd
+gs clippath
+6774 1516 m 6750 1395 l 6828 1491 l 6771 1369 l 6716 1394 l cp
+clip
+n 6750 1395 m 7425 2835 l 7155 2835 l gs col0 s gr gr
+ [] 0 sd
+% arrowhead
+n 6774 1516 m 6750 1395 l 6828 1491 l col0 s
+/Times-Roman ff 180.00 scf sf
+180 1800 m
+gs 1 -1 sc (fragments) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+6030 2880 m
+gs 1 -1 sc (fragment_size) col0 sh gr
+% Polyline
+n 450 855 m 900 855 l 900 1350 l 450 1350 l cp gs col0 s gr
+% Polyline
+n 900 855 m 1350 855 l 1350 1350 l 900 1350 l cp gs col0 s gr
+% Polyline
+n 1350 855 m 1800 855 l 1800 1350 l 1350 1350 l cp gs col0 s gr
+% Polyline
+n 1800 855 m 2250 855 l 2250 1350 l 1800 1350 l cp gs col0 s gr
+% Polyline
+n 2250 855 m 2700 855 l 2700 1350 l 2250 1350 l cp gs col0 s gr
+% Polyline
+n 2700 855 m 3150 855 l 3150 1350 l 2700 1350 l cp gs col0 s gr
+% Polyline
+n 3150 855 m 3600 855 l 3600 1350 l 3150 1350 l cp gs col0 s gr
+% Polyline
+n 3600 855 m 4050 855 l 4050 1350 l 3600 1350 l cp gs col0 s gr
+% Polyline
+n 4050 855 m 4500 855 l 4500 1350 l 4050 1350 l cp gs col0 s gr
+% Polyline
+n 4500 855 m 4950 855 l 4950 1350 l 4500 1350 l cp gs col0 s gr
+% Polyline
+n 4950 855 m 5400 855 l 5400 1350 l 4950 1350 l cp gs col0 s gr
+% Polyline
+n 5400 855 m 5850 855 l 5850 1350 l 5400 1350 l cp gs col0 s gr
+% Polyline
+n 5850 855 m 6300 855 l 6300 1350 l 5850 1350 l cp gs col0 s gr
+% Polyline
+n 6300 855 m 6750 855 l 6750 1350 l 6300 1350 l cp gs col0 s gr
+% Polyline
+n 6750 855 m 7200 855 l 7200 1350 l 6750 1350 l cp gs col0 s gr
+% Polyline
+n 7200 855 m 7650 855 l 7650 1350 l 7200 1350 l cp gs col0 s gr
+% Polyline
+n 5850 855 m 6300 1350 l 6750 855 l 7200 1350 l 7650 855 l gs col0 s gr
+% Polyline
+n 5850 1350 m 6300 855 l 6750 1350 l 7200 855 l 7650 1350 l gs col0 s gr
+% Polyline
+n 450 855 m 900 1350 l 1215 855 l gs col0 s gr
+% Polyline
+n 450 1350 m 900 855 l 1215 1350 l gs col0 s gr
+% Polyline
+ [15 45] 45 sd
+n 1215 855 m 1215 1350 l gs col0 s gr [] 0 sd
+% Polyline
+gs clippath
+1095 690 m 1215 720 l 1095 750 l 1230 750 l 1230 690 l cp
+clip
+n 450 720 m 1215 720 l gs col0 s gr gr
+
+% arrowhead
+n 1095 690 m 1215 720 l 1095 750 l col0 s
+% Polyline
+30.000 slw
+ [45 22 15 22] 0 sd
+n 6030 855 m 6030 1350 l gs col0 s gr [] 0 sd
+% Polyline
+7.500 slw
+gs clippath
+5730 690 m 5850 720 l 5730 750 l 5865 750 l 5865 690 l cp
+1335 750 m 1215 720 l 1335 690 l 1200 690 l 1200 750 l cp
+clip
+n 1215 720 m 5850 720 l gs col0 s gr gr
+
+% arrowhead
+n 1335 750 m 1215 720 l 1335 690 l col0 s
+% arrowhead
+n 5730 690 m 5850 720 l 5730 750 l col0 s
+% Polyline
+gs clippath
+6150 750 m 6030 720 l 6150 690 l 6015 690 l 6015 750 l cp
+clip
+n 6030 720 m 7650 720 l gs col0 s gr gr
+
+% arrowhead
+n 6150 750 m 6030 720 l 6150 690 l col0 s
+/Times-Roman ff 180.00 scf sf
+405 1570 m
+gs 1 -1 sc (0) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+2205 1570 m
+gs 1 -1 sc (4) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+4005 1570 m
+gs 1 -1 sc (8) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+5760 1570 m
+gs 1 -1 sc (12) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+7560 1570 m
+gs 1 -1 sc (16) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+585 585 m
+gs 1 -1 sc (queue) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+2925 585 m
+gs 1 -1 sc (count) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+6750 585 m
+gs 1 -1 sc (queue) col0 sh gr
+$F2psEnd
+rs
+showpage
--- /dev/null
+%!PS-Adobe-2.0
+%%Title: done/pcmbuf1.ps
+%%Creator: fig2dev Version 3.2 Patchlevel 1
+%%CreationDate: Mon Jan 11 04:04:40 1999
+%%For: emng@cyphyn.219.org (Fred Floberg,,,,)
+%%Orientation: Portrait
+%%BoundingBox: 42 358 570 433
+%%Pages: 1
+%%BeginSetup
+%%IncludeFeature: *PageSize Letter
+%%EndSetup
+%%Magnification: 1.0000
+%%EndComments
+/$F2psDict 200 dict def
+$F2psDict begin
+$F2psDict /mtrx matrix put
+/col-1 {0 setgray} bind def
+/col0 {0.000 0.000 0.000 srgb} bind def
+/col1 {0.000 0.000 1.000 srgb} bind def
+/col2 {0.000 1.000 0.000 srgb} bind def
+/col3 {0.000 1.000 1.000 srgb} bind def
+/col4 {1.000 0.000 0.000 srgb} bind def
+/col5 {1.000 0.000 1.000 srgb} bind def
+/col6 {1.000 1.000 0.000 srgb} bind def
+/col7 {1.000 1.000 1.000 srgb} bind def
+/col8 {0.000 0.000 0.560 srgb} bind def
+/col9 {0.000 0.000 0.690 srgb} bind def
+/col10 {0.000 0.000 0.820 srgb} bind def
+/col11 {0.530 0.810 1.000 srgb} bind def
+/col12 {0.000 0.560 0.000 srgb} bind def
+/col13 {0.000 0.690 0.000 srgb} bind def
+/col14 {0.000 0.820 0.000 srgb} bind def
+/col15 {0.000 0.560 0.560 srgb} bind def
+/col16 {0.000 0.690 0.690 srgb} bind def
+/col17 {0.000 0.820 0.820 srgb} bind def
+/col18 {0.560 0.000 0.000 srgb} bind def
+/col19 {0.690 0.000 0.000 srgb} bind def
+/col20 {0.820 0.000 0.000 srgb} bind def
+/col21 {0.560 0.000 0.560 srgb} bind def
+/col22 {0.690 0.000 0.690 srgb} bind def
+/col23 {0.820 0.000 0.820 srgb} bind def
+/col24 {0.500 0.190 0.000 srgb} bind def
+/col25 {0.630 0.250 0.000 srgb} bind def
+/col26 {0.750 0.380 0.000 srgb} bind def
+/col27 {1.000 0.500 0.500 srgb} bind def
+/col28 {1.000 0.630 0.630 srgb} bind def
+/col29 {1.000 0.750 0.750 srgb} bind def
+/col30 {1.000 0.880 0.880 srgb} bind def
+/col31 {1.000 0.840 0.000 srgb} bind def
+
+end
+save
+34.0 464.5 translate
+1 -1 scale
+
+/cp {closepath} bind def
+/ef {eofill} bind def
+/gr {grestore} bind def
+/gs {gsave} bind def
+/sa {save} bind def
+/rs {restore} bind def
+/l {lineto} bind def
+/m {moveto} bind def
+/rm {rmoveto} bind def
+/n {newpath} bind def
+/s {stroke} bind def
+/sh {show} bind def
+/slc {setlinecap} bind def
+/slj {setlinejoin} bind def
+/slw {setlinewidth} bind def
+/srgb {setrgbcolor} bind def
+/rot {rotate} bind def
+/sc {scale} bind def
+/sd {setdash} bind def
+/ff {findfont} bind def
+/sf {setfont} bind def
+/scf {scalefont} bind def
+/sw {stringwidth} bind def
+/tr {translate} bind def
+/tnt {dup dup currentrgbcolor
+ 4 -2 roll dup 1 exch sub 3 -1 roll mul add
+ 4 -2 roll dup 1 exch sub 3 -1 roll mul add
+ 4 -2 roll dup 1 exch sub 3 -1 roll mul add srgb}
+ bind def
+/shd {dup dup currentrgbcolor 4 -2 roll mul 4 -2 roll mul
+ 4 -2 roll mul srgb} bind def
+/$F2psBegin {$F2psDict begin /$F2psEnteredState save def} def
+/$F2psEnd {$F2psEnteredState restore end} def
+%%EndProlog
+
+$F2psBegin
+10 setmiterlimit
+n -1000 2674 m -1000 -1000 l 9509 -1000 l 9509 2674 l cp clip
+ 0.06299 0.06299 sc
+%%Page: 1 1
+/Times-Roman ff 180.00 scf sf
+135 1620 m
+gs 1 -1 sc (fragments) col0 sh gr
+% Polyline
+7.500 slw
+n 1215 900 m 1665 900 l 1665 1395 l 1215 1395 l cp gs col0 s gr
+% Polyline
+n 1665 900 m 2115 900 l 2115 1395 l 1665 1395 l cp gs col0 s gr
+% Polyline
+n 2115 900 m 2565 900 l 2565 1395 l 2115 1395 l cp gs col0 s gr
+% Polyline
+n 2565 900 m 3015 900 l 3015 1395 l 2565 1395 l cp gs col0 s gr
+% Polyline
+n 3015 900 m 3465 900 l 3465 1395 l 3015 1395 l cp gs col0 s gr
+% Polyline
+n 3465 900 m 3915 900 l 3915 1395 l 3465 1395 l cp gs col0 s gr
+% Polyline
+n 3915 900 m 4365 900 l 4365 1395 l 3915 1395 l cp gs col0 s gr
+% Polyline
+n 4365 900 m 4815 900 l 4815 1395 l 4365 1395 l cp gs col0 s gr
+% Polyline
+n 4815 900 m 5265 900 l 5265 1395 l 4815 1395 l cp gs col0 s gr
+% Polyline
+n 5265 900 m 5715 900 l 5715 1395 l 5265 1395 l cp gs col0 s gr
+% Polyline
+n 5715 900 m 6165 900 l 6165 1395 l 5715 1395 l cp gs col0 s gr
+% Polyline
+n 6165 900 m 6615 900 l 6615 1395 l 6165 1395 l cp gs col0 s gr
+% Polyline
+n 6615 900 m 7065 900 l 7065 1395 l 6615 1395 l cp gs col0 s gr
+% Polyline
+n 7065 900 m 7515 900 l 7515 1395 l 7065 1395 l cp gs col0 s gr
+% Polyline
+n 7515 900 m 7965 900 l 7965 1395 l 7515 1395 l cp gs col0 s gr
+% Polyline
+n 7965 900 m 8415 900 l 8415 1395 l 7965 1395 l cp gs col0 s gr
+% Polyline
+n 6615 900 m 7065 1395 l 7515 900 l 7965 1395 l 8415 900 l gs col0 s gr
+% Polyline
+n 6615 1395 m 7065 900 l 7515 1395 l 7965 900 l 8415 1395 l gs col0 s gr
+% Polyline
+gs clippath
+1860 735 m 1980 765 l 1860 795 l 1995 795 l 1995 735 l cp
+clip
+n 1215 765 m 1980 765 l gs col0 s gr gr
+
+% arrowhead
+n 1860 735 m 1980 765 l 1860 795 l col0 s
+% Polyline
+gs clippath
+6495 735 m 6615 765 l 6495 795 l 6630 795 l 6630 735 l cp
+2280 795 m 2160 765 l 2280 735 l 2145 735 l 2145 795 l cp
+clip
+n 2160 765 m 6615 765 l gs col0 s gr gr
+
+% arrowhead
+n 2280 795 m 2160 765 l 2280 735 l col0 s
+% arrowhead
+n 6495 735 m 6615 765 l 6495 795 l col0 s
+% Polyline
+gs clippath
+6915 795 m 6795 765 l 6915 735 l 6780 735 l 6780 795 l cp
+clip
+n 6795 765 m 8415 765 l gs col0 s gr gr
+
+% arrowhead
+n 6915 795 m 6795 765 l 6915 735 l col0 s
+% Polyline
+ [45 22 15 22] 0 sd
+n 1980 900 m 1980 1395 l gs col0 s gr [] 0 sd
+% Polyline
+ [15 45] 45 sd
+n 6795 900 m 6795 1395 l gs col0 s gr [] 0 sd
+% Polyline
+n 1215 900 m 1665 1395 l 1980 900 l gs col0 s gr
+% Polyline
+n 1215 1395 m 1665 900 l 1980 1395 l gs col0 s gr
+/Times-Roman ff 180.00 scf sf
+1170 1615 m
+gs 1 -1 sc (0) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+2970 1615 m
+gs 1 -1 sc (4) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+4770 1615 m
+gs 1 -1 sc (8) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+6525 1615 m
+gs 1 -1 sc (12) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+8325 1615 m
+gs 1 -1 sc (16) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+7515 630 m
+gs 1 -1 sc (count) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+1350 630 m
+gs 1 -1 sc (count) col0 sh gr
+/Times-Roman ff 180.00 scf sf
+4095 630 m
+gs 1 -1 sc (free) col0 sh gr
+$F2psEnd
+rs
+showpage
+++ /dev/null
-<HTML>
-<HEAD>
-<TITLE>Advanced Linux Sound Architecture - Library API: Introduction</TITLE>
-</HEAD>
-<BODY>
-Previous
-<A HREF="soundapi-2.html">Next</A>
-<A HREF="soundapi.html#toc1">Table of Contents</A>
-<HR>
-<H2><A NAME="s1">1. Introduction</A></H2>
-
-<P>The Advanced Linux Sound Architecture comes with a kernel API & library API.
-This document describes the library API and how it interfaces with the kernel
-API. The kernal API will probably never be documented in standalone form.</P>
-<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 next
-major improvements in usability, making the application code simpler and
-better looking. In addition, some of the some fixes/compatibility code in,
-may be placed in the library code instead of the kernel driver.</P>
-<P>For a complete list of all variables and functions in the API you should look
-at the following header files:
-<OL>
-<LI>/usr/include/sys/asoundlib.h</LI>
-<LI>/usr/include/linux/asound.h</LI>
-<LI>/usr/include/linux/asoundid.h</LI>
-</OL>
-</P>
-
-<HR>
-Previous
-<A HREF="soundapi-2.html">Next</A>
-<A HREF="soundapi.html#toc1">Table of Contents</A>
-</BODY>
-</HTML>
+++ /dev/null
-<HTML>
-<HEAD>
-<TITLE>Advanced Linux Sound Architecture - Library API: Error Codes</TITLE>
-</HEAD>
-<BODY>
-<A HREF="soundapi-1.html">Previous</A>
-<A HREF="soundapi-3.html">Next</A>
-<A HREF="soundapi.html#toc2">Table of Contents</A>
-<HR>
-<H2><A NAME="s2">2. Error Codes</A></H2>
-
-<P>All functions return int (or some sort of signed value). If this value
-is negative it represents an error code. Codes up to SND_ERROR_BEGIN (500000)
-represents standard system errors. Codes equal or greather than this value
-represents sound library API errors. All error codes begin with the prefix
-<I>SND_ERROR_</I>.</P>
-
-<H2><A NAME="ss2.1">2.1 Error Codes in Detail</A></H2>
-
-<P>
-<DL>
-<DT><B>SND_ERROR_UNCOMPATIBLE_VERSION (500000)</B><DD><P>This error is caused if the driver uses an incompatible kernel API for this
-interface and hence the library doesn't know how this API can be used.</P>
-</DL>
-</P>
-
-
-<H2><A NAME="ss2.2">2.2 Functions</A></H2>
-
-
-
-<H3>const char *snd_strerror( int errnum ) </H3>
-
-<P>This functions converts error code to a string. Its functionality is the same
-as the <I>strerror</I> function from the standard C library, but this
-function returns correct strings for sound error codes, too.</P>
-
-
-<HR>
-<A HREF="soundapi-1.html">Previous</A>
-<A HREF="soundapi-3.html">Next</A>
-<A HREF="soundapi.html#toc2">Table of Contents</A>
-</BODY>
-</HTML>
+++ /dev/null
-<HTML>
-<HEAD>
-<TITLE>Advanced Linux Sound Architecture - Library API: Control Interface</TITLE>
-</HEAD>
-<BODY>
-<A HREF="soundapi-2.html">Previous</A>
-<A HREF="soundapi-4.html">Next</A>
-<A HREF="soundapi.html#toc3">Table of Contents</A>
-<HR>
-<H2><A NAME="s3">3. Control Interface</A></H2>
-
-<P>The control interfaces gives application various information about the
-currently installed sound driver in the system. The interface should be used
-to detect if another sound interface is present for selected soundcard or,
-for example, to create a list of devices (MIXER, PCM etc) from which
-the user can select.</P>
-
-<H2><A NAME="ss3.1">3.1 Low-Level Layer</A></H2>
-
-<H3>int snd_cards( void ) </H3>
-
-<P>Returns the number of soundcards present in the system, if any. Otherwise
-it returns a negative value, which maps to an error code. This function
-will return 0 if no soundcards are detected.</P>
-
-<H3>unsigned int snd_cards_mask( void ) </H3>
-
-<P>Returns the bitmap of soundcards present in the system, if any. Otherwise
-it returns a negative value, which maps to an error code. This function
-will return 0 if no soundcards are detected. First soundcard is represented
-with bit 0.</P>
-
-<H3>int snd_ctl_open( void **handle, int card ) </H3>
-
-<P>Creates a new handle and opens communication with the kernel sound
-control interface for soundcard number <I>card</I> (0-N). The function
-also checks if protocol is compatible, so as to prevent the use of old
-programs with a new kernel API. Function returns zero if successful,
-otherwise an error code is returned.</P>
-
-<H3>int snd_ctl_close( void *handle ) </H3>
-
-<P>Function frees all resources allocated with control handle and
-closes the kernel sound control interface. Function returns zero if
-successful, otherwise it returns an error code.</P>
-
-<H3>int snd_ctl_file_descriptor( void *handle ) </H3>
-
-<P>Function returns file descriptor for the kernel sound control interface.
-This function should be used in very special cases. Function returns
-a negative error code if some error was encountered.</P>
-
-<H3>int snd_ctl_hw_info( void *handle, struct snd_ctl_hw_info *info ) </H3>
-
-<P>Fills the info structure with data about the sound hardware referenced
-by handle. Function returns zero if successful, otherwise it returns
-an error code.
-<HR>
-<PRE>
- #define SND_CTL_GCAPS_MIDI 0x0000001 /* driver has MIDI interface */
-
- #define SND_CTL_LCAPS_SYNTH 0x0000001 /* soundcard has synthesizer */
- #define SND_CTL_LCAPS_RAWFM 0x0000002 /* soundcard has RAW FM/OPL3 */
-
- struct snd_ctl_hw_info {
- unsigned int type; /* type of card - see SND_CARD_TYPE_XXXX */
- unsigned int gcaps; /* see SND_CTL_GCAPS_XXXX */
- unsigned int lcaps; /* see SND_CTL_LCAPS_XXXX */
- unsigned int pcmdevs; /* count of PCM devices (0 to N) */
- unsigned int mixerdevs; /* count of MIXER devices (0 to N) */
- unsigned int mididevs; /* count of raw MIDI devices (0 to N) */
- char id[8]; /* ID of card (user selectable) */
- char name[80]; /* name/info text about soundcard */
- unsigned char reserved[128]; /* reserved for future use */
- };
-
-</PRE>
-<HR>
-</P>
-
-<H3>int snd_ctl_pcm_info( void *handle, int dev, snd_pcm_info_t *info ) </H3>
-
-<P>Fills the *info structure with data about the PCM device. Function returns
-zero if successful, otherwise it returns an error code. Details about
-the snd_pcm_info_t structure are in the <B>Digital Audio (PCM) Interface</B>
-section. The argument <I>dev</I> selects the device number for the
-soundcard referenced by *handle. Its range is 0 to N where N is
-<I>struct snd_ctl_hw_info -> pcmdevs - 1</I>. This function will work if
-the selected PCM device is busy, too. It should be used to collect
-information about PCM devices without exclusive lock.</P>
-
-<H3>int snd_ctl_pcm_playback_info( void *handle, int dev, snd_pcm_playback_info_t *info ) </H3>
-
-<P>Fills the *info structure with data about the PCM device and playback direction.
-Function returns zero if successful, otherwise it returns an error code.
-Details about the snd_pcm_playback_info_t structure are in the
-<B>Digital Audio (PCM) Interface</B> section. The argument <I>dev</I>
-selects the device number for the soundcard referenced by *handle. Its
-range is 0 to N where N is <I>struct snd_ctl_hw_info -> pcmdevs - 1</I>.
-This function will work if the selected PCM device is busy, too. It should
-be used to collect information about PCM devices without exclusive lock.</P>
-
-<H3>int snd_ctl_pcm_record_info( void *handle, int dev, snd_pcm_record_info_t *info ) </H3>
-
-<P>Fills the *info structure with data about the PCM device and record direction.
-Function returns zero if successful, otherwise it returns an error code.
-Details about the snd_pcm_record_info_t structure are in the
-<B>Digital Audio (PCM) Interface</B> section. The argument <I>dev</I>
-selects the device number for the soundcard referenced by *handle. Its
-range is 0 to N where N is <I>struct snd_ctl_hw_info -> pcmdevs - 1</I>.
-This function will work if the selected PCM device is busy, too. It should
-be used to collect information about PCM devices without exclusive lock.</P>
-
-<H3>int snd_ctl_mixer_info( void *handle, int dev, snd_mixer_info_t *info ) </H3>
-
-<P>Fills the *info structure with data about the mixer device. Returns zero
-if successful, otherwise it returns an error code. Details about the
-snd_mixer_info_t structure are in the <B>Mixer Interface</B> section.
-The argument <I>dev</I> specifies the device number for the appropriate
-soundcard. Its range is 0 to N where N found from
-<I>struct snd_ctl_hw_info -> mixerdevs - 1</I>.
-It should be used to collect information about mixer devices.</P>
-
-
-<H2><A NAME="ss3.2">3.2 Examples</A></H2>
-
-<P>The following example shows how all PCM devices can be detected for the first
-soundcard (#0) in the system.</P>
-<P>
-<BLOCKQUOTE><CODE>
-<HR>
-<PRE>
-int card = 0, err;
-void *handle;
-stuct snd_ctl_hw_info info;
-
-if ( (err = snd_ctl_open( &handle, card )) < 0 ) {
- fprintf( stderr, "open failed: %s\n", snd_strerror( err ) );
- return;
-}
-if ( (err = snd_ctl_hw_info( handle, &info )) < 0 ) {
- fprintf( stderr, "hw info failed: %s\n", snd_strerror( err ) );
- snd_ctl_close( handle );
- return;
-}
-printf( "Installed PCM devices for card #i: %i\n", card + 1, info.pcmdevs );
-snd_ctl_close( handle );
-</PRE>
-<HR>
-</CODE></BLOCKQUOTE>
-</P>
-
-
-<HR>
-<A HREF="soundapi-2.html">Previous</A>
-<A HREF="soundapi-4.html">Next</A>
-<A HREF="soundapi.html#toc3">Table of Contents</A>
-</BODY>
-</HTML>
+++ /dev/null
-<HTML>
-<HEAD>
-<TITLE>Advanced Linux Sound Architecture - Library API: Mixer Interface</TITLE>
-</HEAD>
-<BODY>
-<A HREF="soundapi-3.html">Previous</A>
-<A HREF="soundapi-5.html">Next</A>
-<A HREF="soundapi.html#toc4">Table of Contents</A>
-<HR>
-<H2><A NAME="s4">4. Mixer Interface</A></H2>
-
-<P>The Mixer Interface allows applications to change the volume level of
-a soundcard's input/output channels in both the linear range (0-100)
-and in decibels. It also supports features like hardware mute, input
-sound source, etc.</P>
-
-<H2><A NAME="ss4.1">4.1 Low-Level Layer</A></H2>
-
-<P>Mixer devices aren't opened exclusively. This allows applications to
-open a device multiple times with one or more processes.</P>
-
-<H3>int snd_mixer_open( void **handle, int card, int device ) </H3>
-
-<P>Creates new handle and opens a connection to the kernel sound
-mixer interface for soundcard number <I>card</I> (0-N) and mixer
-device number <I>device</I>. Also checks if protocol is
-compatible to prevent use of old programs with new kernel API. Function
-returns zero if successful, otherwise it returns an error code.</P>
-
-<H3>int snd_mixer_close( void *handle ) </H3>
-
-<P>Frees all resources allocated to the mixer handle and
-closes its connection to the kernel sound mixer interface. Function
-returns zero if successful, otherwise it returns an error code.</P>
-
-<H3>int snd_mixer_file_descriptor( void *handle ) </H3>
-
-<P>Returns the file descriptor for the connection to the kernel sound
-mixer interface. This function should be used only in very
-special cases. Function returns a negative error code if an
-error was encountered. </P>
-<P>The file descriptor should be used for the <I>select</I> synchronous
-multiplexer function for deterimeing read direction. Applications should
-call <I>snd_mixer_read</I> function if some data is waiting to be read.
-It is recomended that you do this, since it leaves place for this function
-to handle some new kernel API specifications.</P>
-
-<H3>int snd_mixer_channels( void *handle ) </H3>
-
-<P>Returns the count of mixer channels for appropriate mixer device, otherwise
-the return value is negative, and signifies an error code. Never returns
-zero.</P>
-
-<H3>int snd_mixer_info( void *handle, snd_mixer_info_t *info ) </H3>
-
-<P>Fills the *info structure with information about the mixer associated with
-*handle. Returns zero if successful, otherwise it returns an error code.
-<HR>
-<PRE>
- #define SND_MIXER_INFO_CAP_EXCL_RECORD 0x00000001
-
- struct snd_mixer_info {
- unsigned int type; /* type of soundcard - SND_CARD_TYPE_XXXX */
- unsigned int channels; /* count of mixer devices */
- unsigned int caps; /* some flags about this device (SND_MIXER_INFO_CAP_XXXX) */
- unsigned char id[32]; /* ID of this mixer */
- unsigned char name[80]; /* name of this device */
- char reserved[ 32 ]; /* reserved for future use */
- };
-
-</PRE>
-<HR>
-</P>
-
-<H3>int snd_mixer_channel( void *handle, const char *channel_id ) </H3>
-
-<P>Returns the channel number (index) associated with channel_id (channel name),
-or returns an error code.
-<HR>
-<PRE>
- #define SND_MIXER_ID_MASTER "Master"
- #define SND_MIXER_ID_BASS "Bass"
- #define SND_MIXER_ID_TREBLE "Treble"
- #define SND_MIXER_ID_SYNTHESIZER "Synth"
- #define SND_MIXER_ID_SYNTHESIZER1 "Synth 1"
- #define SND_MIXER_ID_FM "FM"
- #define SND_MIXER_ID_EFFECT "Effect"
- #define SND_MIXER_ID_PCM "PCM"
- #define SND_MIXER_ID_PCM1 "PCM 1"
- #define SND_MIXER_ID_LINE "Line-In"
- #define SND_MIXER_ID_MIC "MIC"
- #define SND_MIXER_ID_CD "CD"
- #define SND_MIXER_ID_GAIN "Record-Gain"
- #define SND_MIXER_ID_IGAIN "In-Gain"
- #define SND_MIXER_ID_OGAIN "Out-Gain"
- #define SND_MIXER_ID_LOOPBACK "Loopback"
- #define SND_MIXER_ID_SPEAKER "PC Speaker"
- #define SND_MIXER_ID_AUXA "Aux A"
- #define SND_MIXER_ID_AUXB "Aux B"
- #define SND_MIXER_ID_AUXC "Aux C"
-
-</PRE>
-<HR>
- </P>
-
-<H3>int snd_mixer_exact_mode( void *handle, int enable ) </H3>
-
-<P>Turns on or off (by default) exact mode. This mode allows to application
-set/get volume values in exact range which uses hardware. In non-exact
-mode is range always from 0 to 100 and conversion to hardware range does
-driver. Function returns zero if successful, otherwise it returns an error
-code.</P>
-
-<H3>int snd_mixer_channel_info( void *handle, int channel, snd_mixer_channel_info_t *info ) </H3>
-
-<P>Fills the *info structure. The argument <I>channel</I> specifies channel
-(0 to N) for which is the info requested. Function returns zero if
-successful, otherwise it returns an error code.
-<HR>
-<PRE>
- #define SND_MIXER_CINFO_CAP_RECORD 0x00000001
- #define SND_MIXER_CINFO_CAP_STEREO 0x00000002
- #define SND_MIXER_CINFO_CAP_MUTE 0x00000004
- #define SND_MIXER_CINFO_CAP_HWMUTE 0x00000008 /* channel supports hardware mute */
- #define SND_MIXER_CINFO_CAP_DIGITAL 0x00000010 /* channel does digital (not analog) mixing */
- #define SND_MIXER_CINOF_CAP_INPUT 0x00000020 /* input channel */
-
- struct snd_mixer_channel_info {
- unsigned int channel; /* channel # (filled by application) */
- unsigned int parent; /* parent channel # or SND_MIXER_PARENT */
- unsigned char name[12]; /* name of this device */
- unsigned int caps; /* some flags about this device (SND_MIXER_CINFO_XXXX) */
- int min; /* min. value when exact mode (or always 0) */
- int max; /* max. value when exact mode (or always 100) */
- int min_dB; /* minimum decibel value (*100) */
- int max_dB; /* maximum decibel value (*100) */
- int step_dB; /* step decibel value (*100) */
- unsigned char reserved[16];
- };
-
-</PRE>
-<HR>
-</P>
-
-<H3>int snd_mixer_channel_read( void *handle, int channel, snd_mixer_channel_t *data ) </H3>
-
-<P>Fills the *data structure. The argument <I>channel</I> specifies
-the channel (0 to N) for which is data requested. Function returns
-zero if successful, otherwise it returns an error code.
-<HR>
-<PRE>
- #define SND_MIXER_FLG_RECORD 0x00000001 /* channel record source flag */
- #define SND_MIXER_FLG_MUTE_LEFT 0x00010000
- #define SND_MIXER_FLG_MUTE_RIGHT 0x00020000
- #define SND_MIXER_FLG_MUTE 0x00030000
- #define SND_MIXER_FLG_DECIBEL 0x40000000
- #define SND_MIXER_FLG_FORCE 0x80000000
-
- struct snd_mixer_channel {
- unsigned int channel; /* channel # (filled by application) */
- unsigned int flags; /* some flags to read/write (SND_MIXER_FLG_XXXX) */
- int left; /* min - max when exact mode (or 0 - 100) */
- int right; /* min - max when exact mode (or 0 - 100) */
- int left_dB; /* dB * 100 */
- int right_dB; /* dB * 100 */
- unsigned char reserved[16];
- };
-
-</PRE>
-<HR>
-</P>
-<P>
-<DL>
-<DT><B>SND_MIXER_FLG_RECORD</B><DD><P>Record source flag.</P>
-<DT><B>SND_MIXER_FLG_DECIBEL</B><DD><P>If this bit is set, driver set volume from dB variables <I>left_dB</I>
-and <I>right_dB</I>.</P>
-<DT><B>SND_MIXER_FLG_FORCE</B><DD><P>Force set - this bit shouldn't be used from user space. Reserved for
-kernel.</P>
-</DL>
-</P>
-
-<H3>int snd_mixer_channel_write( void *handle, int channel, snd_mixer_channel_t *data ) </H3>
-
-<P>Writes the *data structure to kernel. The <I>channel</I> argument
-specifies the channel (0 to N) for which is data is to be applied.
-Function returns zero if successful, otherwise it returns an error code.
-This functions is the opposite of <I>snd_mixer_channel_read</I>.</P>
-
-<H3>int snd_mixer_special_read( void *handle, snd_mixer_special_t *special ) </H3>
-
-<P>Not documented...</P>
-
-<H3>int snd_mixer_special_write( void *handle, snd_mixer_special_t *special ) </H3>
-
-<P>Not documented...</P>
-
-<H3>int snd_mixer_read( void *handle, snd_mixer_callbacks_t *callbacks ) </H3>
-
-<P>This function reads and parses data from driver. Parsed actions are returned
-back to the application using the <I>callbacks</I> structure. Applications
-should not parse data from the driver in standard cases. This function
-returns immediately after all data is read from driver. Does not
-block process.
-<HR>
-<PRE>
- typedef struct snd_mixer_callbacks {
- void *private_data; /* should be used by application */
- void (*channel_was_changed)( void *private_data, int channel );
- void *reserved[15]; /* reserved for future use - must be NULL!!! */
- } snd_mixer_callbacks_t;
-
-</PRE>
-<HR>
-</P>
-
-
-<H2><A NAME="ss4.2">4.2 Examples</A></H2>
-
-<P>The following example shows installed mixer channels for soundcard #0 and
-mixer device #0 in the system, and also sets the master volume (if present)
-to 50.</P>
-<P>
-<BLOCKQUOTE><CODE>
-<HR>
-<PRE>
-int card = 0, device = 0, err;
-void *handle;
-snd_mixer_info_t info;
-snd_mixer_channel_t channel;
-
-if ( (err = snd_mixer_open( &handle, card, device )) < 0 ) {
- fprintf( stderr, "open failed: %s\n", snd_strerror( err ) );
- return;
-}
-if ( (err = snd_mixer_info( handle, &info )) < 0 ) {
- fprintf( stderr, "info failed: %s\n", snd_strerror( err ) );
- snd_mixer_close( handle );
- return;
-}
-printf( "Installed MIXER channels for card #i and device %i: %i\n",
- card + 1, device, info.channels );
-master = snd_mixer_channel( handle, SND_MIXER_ID_MASTER );
-if ( master >= 0 ) {
- if ( (err = snd_mixer_read( handle, master, &channel )) < 0 ) {
- fprintf( stderr, "master read failed: %s\n", snd_strerror( err ) );
- snd_mixer_close( handle );
- return;
- }
- channel -> left = channel -> right = 50;
- if ( (err = snd_mixer_write( handle, master, &channel )) < 0 ) {
- fprintf( stderr, "master write failed: %s\n", snd_strerror( err ) );
- snd_mixer_close( handle );
- return;
- }
-}
-snd_mixer_close( handle );
-</PRE>
-<HR>
-</CODE></BLOCKQUOTE>
-</P>
-
-
-<HR>
-<A HREF="soundapi-3.html">Previous</A>
-<A HREF="soundapi-5.html">Next</A>
-<A HREF="soundapi.html#toc4">Table of Contents</A>
-</BODY>
-</HTML>
+++ /dev/null
-<HTML>
-<HEAD>
-<TITLE>Advanced Linux Sound Architecture - Library API: Digital Audio (PCM) Interface</TITLE>
-</HEAD>
-<BODY>
-<A HREF="soundapi-4.html">Previous</A>
-Next
-<A HREF="soundapi.html#toc5">Table of Contents</A>
-<HR>
-<H2><A NAME="s5">5. Digital Audio (PCM) Interface</A></H2>
-
-<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 8 kHz (telephone
-quality) and 48 kHz (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 than 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, a 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 DAC. </P>
-<P>Sample encoding limits the dynamic range of 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 * 6 dB . This means that
-8 bits sampling resolution gives dynamic range of 48 dB and 16 bit resolution
-gives 96 dB. </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 8 kHz/8 bits/mono but 48 kHz/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.5 Mbps 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 out of the scope of this document. </P>
-
-<H2><A NAME="ss5.1">5.1 Low-Level Layer</A></H2>
-
-<P>Audio devices are opened exclusively for a selected direction. This doesn't
-allow open from more than one processes for the same audio device in the
-same direction, but does allow one open call to each playback direction and
-second open call to record direction independently. Audio devices return
-EBUSY error to applications when other applications have already opened the
-requested direction.</P>
-<P>Low-Level layer supports these formats:
-<BLOCKQUOTE><CODE>
-<HR>
-<PRE>
-#define SND_PCM_SFMT_MU_LAW 0
-#define SND_PCM_SFMT_A_LAW 1
-#define SND_PCM_SFMT_IMA_ADPCM 2
-#define SND_PCM_SFMT_U8 3
-#define SND_PCM_SFMT_S16_LE 4
-#define SND_PCM_SFMT_S16_BE 5
-#define SND_PCM_SFMT_S8 6
-#define SND_PCM_SFMT_U16_LE 7
-#define SND_PCM_SFMT_U16_BE 8
-#define SND_PCM_SFMT_MPEG 9
-#define SND_PCM_SFMT_GSM 10
-
-#define SND_PCM_FMT_MU_LAW (1 << SND_PCM_SFMT_MU_LAW)
-#define SND_PCM_FMT_A_LAW (1 << SND_PCM_SFMT_A_LAW)
-#define SND_PCM_FMT_IMA_ADPCM (1 << SND_PCM_SFMT_IMA_ADPCM)
-#define SND_PCM_FMT_U8 (1 << SND_PCM_SFMT_U8)
-#define SND_PCM_FMT_S16_LE (1 << SND_PCM_SFMT_S16_LE)
-#define SND_PCM_FMT_S16_BE (1 << SND_PCM_SFMT_S16_BE)
-#define SND_PCM_FMT_S8 (1 << SND_PCM_SFMT_S8)
-#define SND_PCM_FMT_U16_LE (1 << SND_PCM_SFMT_U16_LE)
-#define SND_PCM_FMT_U16_BE (1 << SND_PCM_SFMT_U16_BE)
-#define SND_PCM_FMT_MPEG (1 << SND_PCM_SFMT_MPEG)
-#define SND_PCM_FMT_GSM (1 << SND_PCM_SFMT_GSM)
-</PRE>
-<HR>
-</CODE></BLOCKQUOTE>
-
-Constants with prefix <B>SND_PCM_FMT_</B> are used in info structures
-and constants with prefix <B>SND_PCM_SFMT_</B> are used in format structures.</P>
-
-<H3>int snd_pcm_open( void **handle, int card, int device, int mode ) </H3>
-
-<P>Creates a new handle and opens a connection to kernel sound
-audio interface for soundcard number <I>card</I> (0-N) and audio
-device number <I>device</I>. Function also checks if protocol is
-compatible to prevent use of old programs with a new kernel API. Function
-returns zero if successful,ful otherwise it returns an error code.
-Error code -EBUSY is returned when some process ownes the selected direction.</P>
-<P>Default format after opening is mono <I>mu-Law</I> at 8000Hz. This device
-can be used directly for playback of standard .au (Sparc) files.</P>
-<P>The following modes should be used for the <I>mode</I> argument:
-<HR>
-<PRE>
- #define SND_PCM_OPEN_PLAYBACK (O_WRONLY)
- #define SND_PCM_OPEN_RECORD (O_RDONLY)
- #define SND_PCM_OPEN_DUPLEX (O_RDWR)
-
-</PRE>
-<HR>
-</P>
-
-<H3>int snd_pcm_close( void *handle ) </H3>
-
-<P>Frees all resources allocated with audio handle and
-closes the connection to the kernel sound audio interface. Function
-returns zero if successful, otherwise it returns an error code.</P>
-
-<H3>int snd_pcm_file_descriptor( void *handle ) </H3>
-
-<P>Returns the file descriptor of the connection to the kernel sound
-audio interface. Function returns an error code if an
-error was encountered. </P>
-<P>The file descriptor should be used for the <I>select</I> synchronous
-multiplexer function for setting the read direction. Application should
-call <I>snd_pcm_read</I> or <I>snd_pcm_write</I> functions if some
-data is waiting for reading or a write can be performed. Calling this
-function is highly recomended, as it leaves a place for the API to things
-like data conversions, if needed.</P>
-
-<H3>int snd_pcm_block_mode( void *handle, int enable ) </H3>
-
-<P>Sets up block (default) or nonblock mode for a handle. Block mode suspends
-execution of a program when <I>snd_pcm_read</I> or <I>snd_pcm_write</I>
-is called for the time which is needed for the actual playback or record
-over of the entire buffer. In nonblock mode, programs aren't suspended and
-the above functions returns immediately with the count of bytes which were
-read or written by the driver. When used in this way, don't try to use the
-entire buffer after the call, but instead process the number of bytes
-returned, and call the function again.</P>
-
-<H3>int snd_pcm_info( void *handle, snd_pcm_info_t *info ) </H3>
-
-<P>Fills the *info structure with data about the PCM device selected by
-*handle. Function returns zero if successful, otherwise it returns
-an error code.
-<HR>
-<PRE>
- #define SND_PCM_INFO_CODEC 0x00000001
- #define SND_PCM_INFO_DSP SND_PCM_INFO_CODEC
- #define SND_PCM_INFO_MMAP 0x00000002 /* reserved */
- #define SND_PCM_INFO_PLAYBACK 0x00000100
- #define SND_PCM_INFO_RECORD 0x00000200
- #define SND_PCM_INFO_DUPLEX 0x00000400
- #define SND_PCM_INFO_DUPLEX_LIMIT 0x00000800 /* rate for playback & record are same */
-
- struct snd_pcm_info {
- unsigned int type; /* soundcard type */
- unsigned int flags; /* see SND_PCM_INFO_XXXX */
- unsigned char id[32]; /* ID of this PCM device */
- unsigned char name[80]; /* name of this device */
- unsigned char reserved[64]; /* reserved for future use */
- };
-
-</PRE>
-<HR>
-
-<DL>
-<DT><B>SND_PCM_INFO_MMAP</B><DD><P>This flag is reserved and should be never used. It remains for
-compatibility with Open Sound System driver.</P>
-<DT><B>SND_PCM_INFO_DUPLEX_LIMIT</B><DD><P>If this bit is set, rate must be same for playback and record direction.</P>
-</DL>
-</P>
-
-<H3>int snd_pcm_playback_info( void *handle, snd_pcm_playback_info_t *info ) </H3>
-
-<P>Fills the *info structure with data about PCM playback. Function returns
-zero if successful, otherwise it returns an error code.
-<HR>
-<PRE>
- #define SND_PCM_PINFO_BATCH 0x00000001
- #define SND_PCM_PINFO_8BITONLY 0x00000002
- #define SND_PCM_PINFO_16BITONLY 0x00000004
-
- struct snd_pcm_playback_info {
- unsigned int flags; /* see SND_PCM_PINFO_XXXX */
- unsigned int formats; /* supported formats */
- unsigned int min_rate; /* min rate (in Hz) */
- unsigned int max_rate; /* max rate (in Hz) */
- unsigned int min_channels; /* min channels (probably always 1) */
- unsigned int max_channels; /* max channels */
- unsigned int buffer_size; /* playback buffer size */
- unsigned int min_fragment_size; /* min fragment size in bytes */
- unsigned int max_fragment_size; /* max fragment size in bytes */
- unsigned int fragment_align; /* align fragment value */
- unsigned char reserved[64]; /* reserved for future use */
- };
-
-</PRE>
-<HR>
-
-<DL>
-<DT><B>SND_PCM_PINFO_BATCH</B><DD><P>Driver implements double buffering with this device. This means that
-the chip used for data processing has its own memory, and output should be
-more delayed than if a traditional codec chip is used.</P>
-<DT><B>SND_PCM_PINFO_8BITONLY</B><DD><P>If this bit is set, the driver uses 8-bit format for 16-bit samples and
-does software conversion. This bit is set on broken SoundBlaster 16/AWE
-soundcards which can't do full 16-bit duplex. If this bit is set
-application or highter digital audio layer should do the conversion from
-16-bit samples to 8-bit samples rather than making the driver to do it in
-the kernel.</P>
-<DT><B>SND_PCM_PINFO_16BITONLY</B><DD><P>If this bit is set, driver uses 16-bit format for 8-bit samples and
-does software conversion. This bit is set on broken SoundBlaster 16/AWE
-soundcards which can't do full 8-bit duplex. If this bit is set the
-application or highter digital audio layer should do conversion from
-8-bit samples to 16-bit samples rather than making the driver to do it in
-the kernel.</P>
-</DL>
-</P>
-
-<H3>int snd_pcm_record_info( void *handle, snd_pcm_record_info_t *info ) </H3>
-
-<P>Fills the *info structure. Returns zero if successful, otherwise it returns
-an error code.
-<HR>
-<PRE>
- #define SND_PCM_RINFO_BATCH 0x00000001
- #define SND_PCM_RINFO_8BITONLY 0x00000002
- #define SND_PCM_RINFO_16BITONLY 0x00000004
-
- struct snd_pcm_record_info {
- unsigned int flags; /* see to SND_PCM_RINFO_XXXX */
- unsigned int formats; /* supported formats */
- unsigned int min_rate; /* min rate (in Hz) */
- unsigned int max_rate; /* max rate (in Hz) */
- unsigned int min_channels; /* min channels (probably always 1) */
- unsigned int max_channels; /* max channels */
- unsigned int buffer_size; /* record buffer size */
- unsigned int min_fragment_size; /* min fragment size in bytes */
- unsigned int max_fragment_size; /* max fragment size in bytes */
- unsigned int fragment_align; /* align fragment value */
- unsigned char reserved[64]; /* reserved for future... */
- };
-
-</PRE>
-<HR>
-
-<DL>
-<DT><B>SND_PCM_PINFO_BATCH</B><DD><P>Driver implements buffering for this device. This means that
-the chip used for data processing has its own memory and output should be
-more delayed than if a traditional codec chip is used.</P>
-<DT><B>SND_PCM_PINFO_8BITONLY</B><DD><P>If this bit is set, the device uses 8-bit format for 16-bit samples and
-does software conversion. This bit is set on broken SoundBlaster 16/AWE
-soundcards which can't do full 16-bit duplex. If this bit is set the
-application or highter digital audio layer should do conversion from
-16-bit samples to 8-bit samples rather than making the driver to do it in
-the kernel.</P>
-<DT><B>SND_PCM_PINFO_16BITONLY</B><DD><P>If this bit is set, the device uses a 16-bit format for 8-bit samples and
-does software conversion. This bit is set on broken SoundBlaster 16/AWE
-soundcards which can't do full 8-bit duplex. If this bit is set the
-application or highter digital audio layer should do the conversion from
-8-bit samples to 16-bit samples rather than making the driver to do it in
-the kernel.</P>
-</DL>
-</P>
-
-<H3>int snd_pcm_playback_format( void *handle, snd_pcm_format_t *format ) </H3>
-
-<P>Sets up format, rate (in Hz) and number of channels for playback, in the
-desired direction. Function returns zero if successful, otherwise it
-returns an error code.
-<HR>
-<PRE>
- struct snd_pcm_format {
- unsigned int format; /* SND_PCM_SFMT_XXXX */
- unsigned int rate; /* rate in Hz */
- unsigned int channels; /* channels (voices) */
- unsigned char reserved[16];
- };
-
-</PRE>
-<HR>
-</P>
-
-<H3>int snd_pcm_record_format( void *handle, snd_pcm_format_t *format ) </H3>
-
-<P>Sets up format, rate (in Hz) and number of channels for used for recording
-in the specified direction. Function returns zero if successful, otherwise
-it returns an error code.
-<HR>
-<PRE>
- struct snd_pcm_format {
- unsigned int format; /* SND_PCM_SFMT_XXXX */
- unsigned int rate; /* rate in Hz */
- unsigned int channels; /* channels (voices) */
- unsigned char reserved[16];
- };
-
-</PRE>
-<HR>
-</P>
-
-<H3>int snd_pcm_playback_params( void *handle, snd_pcm_playback_params_t *params ) </H3>
-
-<P>Sets various parameters for playback direction. Function returns zero if
-successful, otherwise it returns an error code.
-<HR>
-<PRE>
- struct snd_pcm_playback_params {
- int fragment_size;
- int fragments_max;
- int fragments_room;
- unsigned char reserved[16]; /* must be filled with zero */
- };
-
-</PRE>
-<HR>
-
-<DL>
-<DT><B>fragment_size</B><DD><P>Requested size of fragment. This value should be aligned for current
-format (for example to 4 if stereo 16-bit samples are used) or with the
-<I>fragment_align</I> variable from <I>snd_pcm_playback_info_t</I>
-structure. Its range can be from <I>min_fragment_size</I> to
-<I>max_fragment_size</I>.</P>
-<DT><B>fragments_max</B><DD><P>Maximum number of fragments in queue for wakeup. This number doesn't
-counts partly used fragment. If current count of filled playback fragments
-is greater than this value driver block application or return immediately
-back if nonblock mode is active.</P>
-<DT><B>fragments_room</B><DD><P>Minumum number of fragments writeable for wakeup. This value should be
-in most cases 1 which means return back to application if at least
-one fragment is free for playback. This value includes partly used fragments,
-too.</P>
-</DL>
-</P>
-
-<H3>int snd_pcm_record_params( void *handle, snd_pcm_record_params_t *params ) </H3>
-
-<P>Function sets various parameters for the recording direction. Function returns
-zero if successful, otherwise it returns an error code.
-<HR>
-<PRE>
- struct snd_pcm_record_params {
- int fragment_size;
- int fragments_min;
- unsigned char reserved[16];
- };
-
-</PRE>
-<HR>
-
-<DL>
-<DT><B>fragment_size</B><DD><P>Requested size of fragment. This value should be aligned for current
-format (for example to 4 if stereo 16-bit samples are used) or set to the
-<I>fragment_align</I> variable from <I>snd_pcm_playback_info_t</I>
-structure. Its range can be from <I>min_fragment_size</I> to
-<I>max_fragment_size</I>.</P>
-<DT><B>fragments_min</B><DD><P>Minimum filled fragments for wakeup. Driver blocks the application (if
-block mode is selected) until it isn't filled with number of fragments
-specified with this value.</P>
-</DL>
-</P>
-
-<H3>int snd_pcm_playback_status( void *handle, snd_pcm_playback_status_t *status ) </H3>
-
-<P>Fills the *status structure. Function returns zero if successful, otherwise
-it returns an error code.
-<HR>
-<PRE>
- struct snd_pcm_playback_status {
- unsigned int rate;
- int fragments;
- int fragment_size;
- int count;
- int queue;
- int underrun;
- struct timeval time;
- struct timeval stime;
- unsigned char reserved[16];
- };
-
-</PRE>
-<HR>
-
-<DL>
-<DT><B>rate</B><DD><P>Real playback rate. This value reflects hardware limitations.</P>
-<DT><B>fragments</B><DD><P>Currently allocated fragments by the driver for playback direction.</P>
-<DT><B>fragment_size</B><DD><P>Current fragment size used by driver for the playback direction.</P>
-<DT><B>count</B><DD><P>Count of bytes writeable without blocking.</P>
-<DT><B>queue</B><DD><P>Count of bytes in queue. Note: <I>(fragments * fragment_size) - queue</I>
-should not be equal to <I>count</I>.</P>
-<DT><B>underrun</B><DD><P>This value tells the application the number of underruns since the ast call
-of <I>snd_pcm_playback_status</I>.</P>
-<DT><B>time</B><DD><P>Delay till played of the first sample from next write. This value should
-be used for time synchronization. Returned value is in the same format as
-returned from the standard C function <I>gettimeofday( &time, NULL )</I>.
-This variable contains right value only if playback time mode is enabled
-(look to <I>snd_pcm_playback_time</I> function).</P>
-<DT><B>stime</B><DD><P>Time when playback was started.
-This variable contains right value only if playback time mode is enabled
-(look to <I>snd_pcm_playback_time</I> function).</P>
-</DL>
-</P>
-
-<H3>int snd_pcm_record_status( void *handle, snd_pcm_record_status_t *status ) </H3>
-
-<P>Fills the *status structure. Function returns zero if successful, otherwise
-it returns an error code.
-<HR>
-<PRE>
- struct snd_pcm_record_status {
- unsigned int rate;
- int fragments;
- int fragment_size;
- int count;
- int free;
- int overrun;
- struct timeval time;
- unsigned char reserved[16];
- };
-
-</PRE>
-<HR>
-
-<DL>
-<DT><B>rate</B><DD><P>Real record rate. This value reflects hardware limitations.</P>
-<DT><B>fragments</B><DD><P>Currently allocated fragments by driver for the record direction.</P>
-<DT><B>fragment_size</B><DD><P>Current fragment size used by driver for the record direction.</P>
-<DT><B>count</B><DD><P>Count of bytes readable without blocking.</P>
-<DT><B>free</B><DD><P>Count of bytes in buffer still free. Note: <I>(fragments * fragment_size) - free</I>
-should not be equal to <I>count</I>.</P>
-<DT><B>overrun</B><DD><P>This value tells application the count of overruns since the last call
-to <I>snd_pcm_record_status</I>.</P>
-<DT><B>time</B><DD><P>Lag since the next sample read was recorded. This value should be used for time
-synchronization. Returned value is in the same format as returned by the
-from standard C function <I>gettimeofday( &time, NULL )</I>. This
-variable contains right value only if record time mode is enabled (look to
-<I>snd_pcm_record_time</I> function).</P>
-<DT><B>stime</B><DD><P>Time when record was started. This variable contains right value only if
-record time mode is enabled (look to <I>snd_pcm_record_time</I> function).</P>
-</DL>
-</P>
-
-<H3>int snd_pcm_drain_playback( void *handle ) </H3>
-
-<P>This function drain playback buffers immediately. Function returns zero
-if successful, otherwise it returns an error code. </P>
-
-<H3>int snd_pcm_flush_playback( void *handle ) </H3>
-
-<P>This function flushes the playback buffers. It blocks the program while the
-all the waiting samples in kernel playback buffers are processed. Function
-returns zero if successful, otherwise it returns an error code.</P>
-
-<H3>int snd_pcm_flush_record( void *handle ) </H3>
-
-<P>This function flushes (destroyes) record buffers. Function returns zero
-if successful, otherwise it returns an error code. </P>
-
-<H3>int snd_pcm_playback_time( void *handle, int enable ) </H3>
-
-<P>This function enables or disables time mode for playback direction. Time mode
-allows to application better time synchronization. Function returns zero
-if successful, otherwise it returns an error code.</P>
-
-<H3>int snd_pcm_record_time( void *handle, int enable ) </H3>
-
-<P>This function enables or disables time mode for record direction. Time mode
-allows to application better time synchronization. Function returns zero
-if successful, otherwise it returns an error code.</P>
-
-<H3>ssize_t snd_pcm_write( void *handle, const void *buffer, size_t size ) </H3>
-
-<P>Writes samples to the device which must be in the proper format
-specified by the <I>snd_pcm_playback_format</I> function. Function
-returns zero or positive value if playback was successful (value represents
-count of bytes which was successfuly written to device) or an
-error value if error occured. Function should suspend process if
-block mode is active.</P>
-
-<H3>ssize_t snd_pcm_read( void *handle, void *buffer, size_t size ) </H3>
-
-<P>Function reads samples from driver. Samples are in format specified
-by <I>snd_pcm_record_format</I> function. Function returns zero
-or positive value if record was success (value represents count of bytes
-which was successfuly read from device) or negative error value if
-error occured. Function should suspend process if block mode is active.</P>
-
-
-<H2><A NAME="ss5.2">5.2 Examples</A></H2>
-
-<P>The following example shows how to play the first 512kB from the
-/tmp/test.au file with soundcard #0 and PCM device #0:</P>
-<P>
-<BLOCKQUOTE><CODE>
-<HR>
-<PRE>
-int card = 0, device = 0, err, fd, count, size, idx;
-void *handle;
-snd_pcm_format_t format;
-char *buffer;
-
-buffer = (char *)malloc( 512 * 1024 );
-if ( !buffer ) return;
-if ( (err = snd_pcm_open( &handle, card, device, SND_PCM_OPEN_PLAYBACK )) < 0 ) {
- fprintf( stderr, "open failed: %s\n", snd_strerror( err ) );
- return;
-}
-format.format = SND_PCM_SFMT_MU_LAW;
-format.rate = 8000;
-format.channels = 1;
-if ( (err = snd_pcm_playback_format( handle, &format )) < 0 ) {
- fprintf( stderr, "format setup failed: %s\n", snd_strerror( err ) );
- snd_pcm_close( handle );
- return;
-}
-fd = open( "/tmp/test.au", O_RDONLY );
-if ( fd < 0 ) {
- perror( "open file" );
- snd_pcm_close( handle );
- return;
-}
-idx = 0;
-count = read( fd, buffer, 512 * 1024 );
-if ( count <= 0 ) {
- perror( "read from file" );
- snd_pcm_close( handle );
- return;
-}
-close( fd );
-if ( !memcmp( buffer, ".snd", 4 ) ) {
- idx = (buffer[4]<<24)|(buffer[5]<<16)|(buffer[6]<<8)|(buffer[7]);
- if ( idx > 128 ) idx = 128;
- if ( idx > count ) idx = count;
-}
-size = snd_pcm_write( handle, &buffer[ idx ], count - idx );
-printf( "Bytes written %i from %i...\n", size, count - idx );
-snd_pcm_close( handle );
-free( buffer );
-</PRE>
-<HR>
-</CODE></BLOCKQUOTE>
-</P>
-
-
-<HR>
-<A HREF="soundapi-4.html">Previous</A>
-Next
-<A HREF="soundapi.html#toc5">Table of Contents</A>
-</BODY>
-</HTML>
+++ /dev/null
-
-<HTML>
-<HEAD>
-<TITLE>Advanced Linux Sound Architecture - Library API</TITLE>
-</HEAD>
-<BODY>
-Previous
-<A HREF="soundapi-1.html">Next</A>
-Table of Contents
-<HR>
-<H1>Advanced Linux Sound Architecture - Library API</H1>
-
-<H2>Jaroslav Kysela <CODE><perex@jcu.cz></CODE> with assistance from Alan Robinson</H2>v0.0.3, 25 March 1998
-<P><HR><EM>This document describes, in full detail, the Advanced Linux Sound Architecture library API.</EM><HR></P>
-<P>
-<H2><A NAME="toc1">1.</A> <A HREF="soundapi-1.html">Introduction</A></H2>
-
-<P>
-<H2><A NAME="toc2">2.</A> <A HREF="soundapi-2.html">Error Codes</A></H2>
-<UL>
-<LI><A HREF="soundapi-2.html#ss2.1">2.1 Error Codes in Detail</A>
-<LI><A HREF="soundapi-2.html#ss2.2">2.2 Functions</A>
-</UL>
-
-<P>
-<H2><A NAME="toc3">3.</A> <A HREF="soundapi-3.html">Control Interface</A></H2>
-<UL>
-<LI><A HREF="soundapi-3.html#ss3.1">3.1 Low-Level Layer</A>
-<LI><A HREF="soundapi-3.html#ss3.2">3.2 Examples</A>
-</UL>
-
-<P>
-<H2><A NAME="toc4">4.</A> <A HREF="soundapi-4.html">Mixer Interface</A></H2>
-<UL>
-<LI><A HREF="soundapi-4.html#ss4.1">4.1 Low-Level Layer</A>
-<LI><A HREF="soundapi-4.html#ss4.2">4.2 Examples</A>
-</UL>
-
-<P>
-<H2><A NAME="toc5">5.</A> <A HREF="soundapi-5.html">Digital Audio (PCM) Interface</A></H2>
-<UL>
-<LI><A HREF="soundapi-5.html#ss5.1">5.1 Low-Level Layer</A>
-<LI><A HREF="soundapi-5.html#ss5.2">5.2 Examples</A>
-</UL>
-
-
-<HR>
-Previous
-<A HREF="soundapi-1.html">Next</A>
-Table of Contents
-</BODY>
-</HTML>
+++ /dev/null
-<!doctype linuxdoc system>
-
-<!-- Advanced Linux Sound Architecture - Library API -->
-
-<article>
-
-<!-- Title information -->
-
-<title>Advanced Linux Sound Architecture - Library API
-<author>Jaroslav Kysela <tt><perex@jcu.cz></tt> with assistance from Alan Robinson
-<date>v0.0.3, 25 March 1998
-<abstract>
-This document describes, in full detail, the Advanced Linux Sound
-Architecture library API.
-</abstract>
-
-<!-- Table of contents -->
-<toc>
-
-<!-- Begin the document -->
-
-<sect>Introduction
-
-<p>
-The Advanced Linux Sound Architecture comes with a kernel API & library API.
-This document describes the library API and how it interfaces with the kernel
-API. The kernal API will probably never be documented in standalone form.
-<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 next
-major improvements in usability, making the application code simpler and
-better looking. In addition, some of the some fixes/compatibility code in,
-may be placed in the library code instead of the kernel driver.
-<p>
-For a complete list of all variables and functions in the API you should look
-at the following header files:
-<enum>
- <item>/usr/include/sys/asoundlib.h
- <item>/usr/include/linux/asound.h
- <item>/usr/include/linux/asoundid.h
-</enum>
-
-<sect>Error Codes
-
-<p>
-All functions return int (or some sort of signed value). If this value
-is negative it represents an error code. Codes up to SND_ERROR_BEGIN (500000)
-represents standard system errors. Codes equal or greather than this value
-represents sound library API errors. All error codes begin with the prefix
-<it>SND_ERROR_</it>.
-
-<sect1>Error Codes in Detail
-
-<p>
-<descrip>
-<tag>SND_ERROR_UNCOMPATIBLE_VERSION (500000)</tag>
- This error is caused if the driver uses an incompatible kernel API for this
- interface and hence the library doesn't know how this API can be used.
-</descrip>
-
-<sect1>Functions
-
-<p>
-
-<sect2>const char *snd_strerror( int errnum )
- <p>
- This functions converts error code to a string. Its functionality is the same
- as the <it>strerror</it> function from the standard C library, but this
- function returns correct strings for sound error codes, too.
-
-<sect>Control Interface
-
-<p>
-The control interfaces gives application various information about the
-currently installed sound driver in the system. The interface should be used
-to detect if another sound interface is present for selected soundcard or,
-for example, to create a list of devices (MIXER, PCM etc) from which
-the user can select.
-
-<sect1>Low-Level Layer
-
-<sect2>int snd_cards( void )
- <p>
- Returns the number of soundcards present in the system, if any. Otherwise
- it returns a negative value, which maps to an error code. This function
- will return 0 if no soundcards are detected.
-
-<sect2>unsigned int snd_cards_mask( void )
- <p>
- Returns the bitmap of soundcards present in the system, if any. Otherwise
- it returns a negative value, which maps to an error code. This function
- will return 0 if no soundcards are detected. First soundcard is represented
- with bit 0.
-
-<sect2>int snd_ctl_open( void **handle, int card )
- <p>
- Creates a new handle and opens communication with the kernel sound
- control interface for soundcard number <it>card</it> (0-N). The function
- also checks if protocol is compatible, so as to prevent the use of old
- programs with a new kernel API. Function returns zero if successful,
- otherwise an error code is returned.
-
-<sect2>int snd_ctl_close( void *handle )
- <p>
- Function frees all resources allocated with control handle and
- closes the kernel sound control interface. Function returns zero if
- successful, otherwise it returns an error code.
-
-<sect2>int snd_ctl_file_descriptor( void *handle )
- <p>
- Function returns file descriptor for the kernel sound control interface.
- This function should be used in very special cases. Function returns
- a negative error code if some error was encountered.
-
-<sect2>int snd_ctl_hw_info( void *handle, struct snd_ctl_hw_info *info )
- <p>
- Fills the info structure with data about the sound hardware referenced
- by handle. Function returns zero if successful, otherwise it returns
- an error code.
- <code>
- #define SND_CTL_GCAPS_MIDI 0x0000001 /* driver has MIDI interface */
-
- #define SND_CTL_LCAPS_SYNTH 0x0000001 /* soundcard has synthesizer */
- #define SND_CTL_LCAPS_RAWFM 0x0000002 /* soundcard has RAW FM/OPL3 */
-
- struct snd_ctl_hw_info {
- unsigned int type; /* type of card - see SND_CARD_TYPE_XXXX */
- unsigned int gcaps; /* see SND_CTL_GCAPS_XXXX */
- unsigned int lcaps; /* see SND_CTL_LCAPS_XXXX */
- unsigned int pcmdevs; /* count of PCM devices (0 to N) */
- unsigned int mixerdevs; /* count of MIXER devices (0 to N) */
- unsigned int mididevs; /* count of raw MIDI devices (0 to N) */
- char id[8]; /* ID of card (user selectable) */
- char name[80]; /* name/info text about soundcard */
- unsigned char reserved[128]; /* reserved for future use */
- };
- </code>
-
-<sect2>int snd_ctl_pcm_info( void *handle, int dev, snd_pcm_info_t *info )
- <p>
- Fills the *info structure with data about the PCM device. Function returns
- zero if successful, otherwise it returns an error code. Details about
- the snd_pcm_info_t structure are in the <bf>Digital Audio (PCM) Interface</bf>
- section. The argument <it>dev</it> selects the device number for the
- soundcard referenced by *handle. Its range is 0 to N where N is
- <it>struct snd_ctl_hw_info -> pcmdevs - 1</it>. This function will work if
- the selected PCM device is busy, too. It should be used to collect
- information about PCM devices without exclusive lock.
-
-<sect2>int snd_ctl_pcm_playback_info( void *handle, int dev, snd_pcm_playback_info_t *info )
- <p>
- Fills the *info structure with data about the PCM device and playback direction.
- Function returns zero if successful, otherwise it returns an error code.
- Details about the snd_pcm_playback_info_t structure are in the
- <bf>Digital Audio (PCM) Interface</bf> section. The argument <it>dev</it>
- selects the device number for the soundcard referenced by *handle. Its
- range is 0 to N where N is <it>struct snd_ctl_hw_info -> pcmdevs - 1</it>.
- This function will work if the selected PCM device is busy, too. It should
- be used to collect information about PCM devices without exclusive lock.
-
-<sect2>int snd_ctl_pcm_record_info( void *handle, int dev, snd_pcm_record_info_t *info )
- <p>
- Fills the *info structure with data about the PCM device and record direction.
- Function returns zero if successful, otherwise it returns an error code.
- Details about the snd_pcm_record_info_t structure are in the
- <bf>Digital Audio (PCM) Interface</bf> section. The argument <it>dev</it>
- selects the device number for the soundcard referenced by *handle. Its
- range is 0 to N where N is <it>struct snd_ctl_hw_info -> pcmdevs - 1</it>.
- This function will work if the selected PCM device is busy, too. It should
- be used to collect information about PCM devices without exclusive lock.
-
-<sect2>int snd_ctl_mixer_info( void *handle, int dev, snd_mixer_info_t *info )
- <p>
- Fills the *info structure with data about the mixer device. Returns zero
- if successful, otherwise it returns an error code. Details about the
- snd_mixer_info_t structure are in the <bf>Mixer Interface</bf> section.
- The argument <it>dev</it> specifies the device number for the appropriate
- soundcard. Its range is 0 to N where N found from
- <it>struct snd_ctl_hw_info -> mixerdevs - 1</it>.
- It should be used to collect information about mixer devices.
-
-<sect1>Examples
-
-<p>
-The following example shows how all PCM devices can be detected for the first
-soundcard (#0) in the system.
-
-<tscreen><code>
-int card = 0, err;
-void *handle;
-stuct snd_ctl_hw_info info;
-
-if ( (err = snd_ctl_open( &ero;handle, card )) < 0 ) {
- fprintf( stderr, "open failed: %s\n", snd_strerror( err ) );
- return;
-}
-if ( (err = snd_ctl_hw_info( handle, &ero;info )) < 0 ) {
- fprintf( stderr, "hw info failed: %s\n", snd_strerror( err ) );
- snd_ctl_close( handle );
- return;
-}
-printf( "Installed PCM devices for card #i: %i\n", card + 1, info.pcmdevs );
-snd_ctl_close( handle );
-</code></tscreen>
-
-<sect>Mixer Interface
-
-<p>
-The Mixer Interface allows applications to change the volume level of
-a soundcard's input/output channels in both the linear range (0-100)
-and in decibels. It also supports features like hardware mute, input
-sound source, etc.
-
-<sect1>Low-Level Layer
-
-<p>
-Mixer devices aren't opened exclusively. This allows applications to
-open a device multiple times with one or more processes.
-
-<sect2>int snd_mixer_open( void **handle, int card, int device )
- <p>
- Creates new handle and opens a connection to the kernel sound
- mixer interface for soundcard number <it>card</it> (0-N) and mixer
- device number <it>device</it>. Also checks if protocol is
- compatible to prevent use of old programs with new kernel API. Function
- returns zero if successful, otherwise it returns an error code.
-
-<sect2>int snd_mixer_close( void *handle )
- <p>
- Frees all resources allocated to the mixer handle and
- closes its connection to the kernel sound mixer interface. Function
- returns zero if successful, otherwise it returns an error code.
-
-<sect2>int snd_mixer_file_descriptor( void *handle )
- <p>
- Returns the file descriptor for the connection to the kernel sound
- mixer interface. This function should be used only in very
- special cases. Function returns a negative error code if an
- error was encountered.
- <p>
- The file descriptor should be used for the <it>select</it> synchronous
- multiplexer function for deterimeing read direction. Applications should
- call <it>snd_mixer_read</it> function if some data is waiting to be read.
- It is recomended that you do this, since it leaves place for this function
- to handle some new kernel API specifications.
-
-<sect2>int snd_mixer_channels( void *handle )
- <p>
- Returns the count of mixer channels for appropriate mixer device, otherwise
- the return value is negative, and signifies an error code. Never returns
- zero.
-
-<sect2>int snd_mixer_info( void *handle, snd_mixer_info_t *info )
- <p>
- Fills the *info structure with information about the mixer associated with
- *handle. Returns zero if successful, otherwise it returns an error code.
- <code>
- #define SND_MIXER_INFO_CAP_EXCL_RECORD 0x00000001
-
- struct snd_mixer_info {
- unsigned int type; /* type of soundcard - SND_CARD_TYPE_XXXX */
- unsigned int channels; /* count of mixer devices */
- unsigned int caps; /* some flags about this device (SND_MIXER_INFO_CAP_XXXX) */
- unsigned char id[32]; /* ID of this mixer */
- unsigned char name[80]; /* name of this device */
- char reserved[ 32 ]; /* reserved for future use */
- };
- </code>
-
-<sect2>int snd_mixer_channel( void *handle, const char *channel_id )
- <p>
- Returns the channel number (index) associated with channel_id (channel name),
- or returns an error code.
- <code>
- #define SND_MIXER_ID_MASTER "Master"
- #define SND_MIXER_ID_BASS "Bass"
- #define SND_MIXER_ID_TREBLE "Treble"
- #define SND_MIXER_ID_SYNTHESIZER "Synth"
- #define SND_MIXER_ID_SYNTHESIZER1 "Synth 1"
- #define SND_MIXER_ID_FM "FM"
- #define SND_MIXER_ID_EFFECT "Effect"
- #define SND_MIXER_ID_PCM "PCM"
- #define SND_MIXER_ID_PCM1 "PCM 1"
- #define SND_MIXER_ID_LINE "Line-In"
- #define SND_MIXER_ID_MIC "MIC"
- #define SND_MIXER_ID_CD "CD"
- #define SND_MIXER_ID_GAIN "Record-Gain"
- #define SND_MIXER_ID_IGAIN "In-Gain"
- #define SND_MIXER_ID_OGAIN "Out-Gain"
- #define SND_MIXER_ID_LOOPBACK "Loopback"
- #define SND_MIXER_ID_SPEAKER "PC Speaker"
- #define SND_MIXER_ID_AUXA "Aux A"
- #define SND_MIXER_ID_AUXB "Aux B"
- #define SND_MIXER_ID_AUXC "Aux C"
- </code>
-
-<sect2>int snd_mixer_exact_mode( void *handle, int enable )
- <p>
- Turns on or off (by default) exact mode. This mode allows to application
- set/get volume values in exact range which uses hardware. In non-exact
- mode is range always from 0 to 100 and conversion to hardware range does
- driver. Function returns zero if successful, otherwise it returns an error
- code.
-
-<sect2>int snd_mixer_channel_info( void *handle, int channel, snd_mixer_channel_info_t *info )
- <p>
- Fills the *info structure. The argument <it>channel</it> specifies channel
- (0 to N) for which is the info requested. Function returns zero if
- successful, otherwise it returns an error code.
- <code>
- #define SND_MIXER_CINFO_CAP_RECORD 0x00000001
- #define SND_MIXER_CINFO_CAP_STEREO 0x00000002
- #define SND_MIXER_CINFO_CAP_MUTE 0x00000004
- #define SND_MIXER_CINFO_CAP_HWMUTE 0x00000008 /* channel supports hardware mute */
- #define SND_MIXER_CINFO_CAP_DIGITAL 0x00000010 /* channel does digital (not analog) mixing */
- #define SND_MIXER_CINOF_CAP_INPUT 0x00000020 /* input channel */
-
- struct snd_mixer_channel_info {
- unsigned int channel; /* channel # (filled by application) */
- unsigned int parent; /* parent channel # or SND_MIXER_PARENT */
- unsigned char name[12]; /* name of this device */
- unsigned int caps; /* some flags about this device (SND_MIXER_CINFO_XXXX) */
- int min; /* min. value when exact mode (or always 0) */
- int max; /* max. value when exact mode (or always 100) */
- int min_dB; /* minimum decibel value (*100) */
- int max_dB; /* maximum decibel value (*100) */
- int step_dB; /* step decibel value (*100) */
- unsigned char reserved[16];
- };
- </code>
-
-<sect2>int snd_mixer_channel_read( void *handle, int channel, snd_mixer_channel_t *data )
- <p>
- Fills the *data structure. The argument <it>channel</it> specifies
- the channel (0 to N) for which is data requested. Function returns
- zero if successful, otherwise it returns an error code.
- <code>
- #define SND_MIXER_FLG_RECORD 0x00000001 /* channel record source flag */
- #define SND_MIXER_FLG_MUTE_LEFT 0x00010000
- #define SND_MIXER_FLG_MUTE_RIGHT 0x00020000
- #define SND_MIXER_FLG_MUTE 0x00030000
- #define SND_MIXER_FLG_DECIBEL 0x40000000
- #define SND_MIXER_FLG_FORCE 0x80000000
-
- struct snd_mixer_channel {
- unsigned int channel; /* channel # (filled by application) */
- unsigned int flags; /* some flags to read/write (SND_MIXER_FLG_XXXX) */
- int left; /* min - max when exact mode (or 0 - 100) */
- int right; /* min - max when exact mode (or 0 - 100) */
- int left_dB; /* dB * 100 */
- int right_dB; /* dB * 100 */
- unsigned char reserved[16];
- };
- </code>
- <p>
- <descrip>
- <tag>SND_MIXER_FLG_RECORD</tag>
- Record source flag.
- <tag>SND_MIXER_FLG_DECIBEL</tag>
- If this bit is set, driver set volume from dB variables <it>left_dB</it>
- and <it>right_dB</it>.
- <tag>SND_MIXER_FLG_FORCE</tag>
- Force set - this bit shouldn't be used from user space. Reserved for
- kernel.
- </descrip>
-
-<sect2>int snd_mixer_channel_write( void *handle, int channel, snd_mixer_channel_t *data )
- <p>
- Writes the *data structure to kernel. The <it>channel</it> argument
- specifies the channel (0 to N) for which is data is to be applied.
- Function returns zero if successful, otherwise it returns an error code.
- This functions is the opposite of <it>snd_mixer_channel_read</it>.
-
-<sect2>int snd_mixer_special_read( void *handle, snd_mixer_special_t *special )
- <p>
- Not documented...
-
-<sect2>int snd_mixer_special_write( void *handle, snd_mixer_special_t *special )
- <p>
- Not documented...
-
-<sect2>int snd_mixer_read( void *handle, snd_mixer_callbacks_t *callbacks )
- <p>
- This function reads and parses data from driver. Parsed actions are returned
- back to the application using the <it>callbacks</it> structure. Applications
- should not parse data from the driver in standard cases. This function
- returns immediately after all data is read from driver. Does not
- block process.
- <code>
- typedef struct snd_mixer_callbacks {
- void *private_data; /* should be used by application */
- void (*channel_was_changed)( void *private_data, int channel );
- void *reserved[15]; /* reserved for future use - must be NULL!!! */
- } snd_mixer_callbacks_t;
- </code>
-
-<sect1>Examples
-
-<p>
-The following example shows installed mixer channels for soundcard #0 and
-mixer device #0 in the system, and also sets the master volume (if present)
-to 50.
-
-<tscreen><code>
-int card = 0, device = 0, err;
-void *handle;
-snd_mixer_info_t info;
-snd_mixer_channel_t channel;
-
-if ( (err = snd_mixer_open( &ero;handle, card, device )) < 0 ) {
- fprintf( stderr, "open failed: %s\n", snd_strerror( err ) );
- return;
-}
-if ( (err = snd_mixer_info( handle, &ero;info )) < 0 ) {
- fprintf( stderr, "info failed: %s\n", snd_strerror( err ) );
- snd_mixer_close( handle );
- return;
-}
-printf( "Installed MIXER channels for card #i and device %i: %i\n",
- card + 1, device, info.channels );
-master = snd_mixer_channel( handle, SND_MIXER_ID_MASTER );
-if ( master >= 0 ) {
- if ( (err = snd_mixer_read( handle, master, &ero;channel )) < 0 ) {
- fprintf( stderr, "master read failed: %s\n", snd_strerror( err ) );
- snd_mixer_close( handle );
- return;
- }
- channel -> left = channel -> right = 50;
- if ( (err = snd_mixer_write( handle, master, &ero;channel )) < 0 ) {
- fprintf( stderr, "master write failed: %s\n", snd_strerror( err ) );
- snd_mixer_close( handle );
- return;
- }
-}
-snd_mixer_close( handle );
-</code></tscreen>
-
-<sect>Digital Audio (PCM) Interface
-
-<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 8 kHz (telephone
-quality) and 48 kHz (DAT tapes).
-<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>
-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 than 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, a 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 DAC.
-<p>
-Sample encoding limits the dynamic range of 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 * 6 dB . This means that
-8 bits sampling resolution gives dynamic range of 48 dB and 16 bit resolution
-gives 96 dB.
-<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 8 kHz/8 bits/mono but 48 kHz/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.5 Mbps 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 out of the scope of this document.
-
-<sect1>Low-Level Layer
-
-<p>
-Audio devices are opened exclusively for a selected direction. This doesn't
-allow open from more than one processes for the same audio device in the
-same direction, but does allow one open call to each playback direction and
-second open call to record direction independently. Audio devices return
-EBUSY error to applications when other applications have already opened the
-requested direction.
-<p>
-Low-Level layer supports these formats:
-<tscreen><code>
-#define SND_PCM_SFMT_MU_LAW 0
-#define SND_PCM_SFMT_A_LAW 1
-#define SND_PCM_SFMT_IMA_ADPCM 2
-#define SND_PCM_SFMT_U8 3
-#define SND_PCM_SFMT_S16_LE 4
-#define SND_PCM_SFMT_S16_BE 5
-#define SND_PCM_SFMT_S8 6
-#define SND_PCM_SFMT_U16_LE 7
-#define SND_PCM_SFMT_U16_BE 8
-#define SND_PCM_SFMT_MPEG 9
-#define SND_PCM_SFMT_GSM 10
-
-#define SND_PCM_FMT_MU_LAW (1 << SND_PCM_SFMT_MU_LAW)
-#define SND_PCM_FMT_A_LAW (1 << SND_PCM_SFMT_A_LAW)
-#define SND_PCM_FMT_IMA_ADPCM (1 << SND_PCM_SFMT_IMA_ADPCM)
-#define SND_PCM_FMT_U8 (1 << SND_PCM_SFMT_U8)
-#define SND_PCM_FMT_S16_LE (1 << SND_PCM_SFMT_S16_LE)
-#define SND_PCM_FMT_S16_BE (1 << SND_PCM_SFMT_S16_BE)
-#define SND_PCM_FMT_S8 (1 << SND_PCM_SFMT_S8)
-#define SND_PCM_FMT_U16_LE (1 << SND_PCM_SFMT_U16_LE)
-#define SND_PCM_FMT_U16_BE (1 << SND_PCM_SFMT_U16_BE)
-#define SND_PCM_FMT_MPEG (1 << SND_PCM_SFMT_MPEG)
-#define SND_PCM_FMT_GSM (1 << SND_PCM_SFMT_GSM)
-</code></tscreen>
-Constants with prefix <bf>SND_PCM_FMT_</bf> are used in info structures
-and constants with prefix <bf>SND_PCM_SFMT_</bf> are used in format structures.
-
-<sect2>int snd_pcm_open( void **handle, int card, int device, int mode )
- <p>
- Creates a new handle and opens a connection to kernel sound
- audio interface for soundcard number <it>card</it> (0-N) and audio
- device number <it>device</it>. Function also checks if protocol is
- compatible to prevent use of old programs with a new kernel API. Function
- returns zero if successful,ful otherwise it returns an error code.
- Error code -EBUSY is returned when some process ownes the selected direction.
- <p>
- Default format after opening is mono <it>mu-Law</it> at 8000Hz. This device
- can be used directly for playback of standard .au (Sparc) files.
- <p>
- The following modes should be used for the <it>mode</it> argument:
- <code>
- #define SND_PCM_OPEN_PLAYBACK (O_WRONLY)
- #define SND_PCM_OPEN_RECORD (O_RDONLY)
- #define SND_PCM_OPEN_DUPLEX (O_RDWR)
- </code>
-
-<sect2>int snd_pcm_close( void *handle )
- <p>
- Frees all resources allocated with audio handle and
- closes the connection to the kernel sound audio interface. Function
- returns zero if successful, otherwise it returns an error code.
-
-<sect2>int snd_pcm_file_descriptor( void *handle )
- <p>
- Returns the file descriptor of the connection to the kernel sound
- audio interface. Function returns an error code if an
- error was encountered.
- <p>
- The file descriptor should be used for the <it>select</it> synchronous
- multiplexer function for setting the read direction. Application should
- call <it>snd_pcm_read</it> or <it>snd_pcm_write</it> functions if some
- data is waiting for reading or a write can be performed. Calling this
- function is highly recomended, as it leaves a place for the API to things
- like data conversions, if needed.
-
-<sect2>int snd_pcm_block_mode( void *handle, int enable )
- <p>
- Sets up block (default) or nonblock mode for a handle. Block mode suspends
- execution of a program when <it>snd_pcm_read</it> or <it>snd_pcm_write</it>
- is called for the time which is needed for the actual playback or record
- over of the entire buffer. In nonblock mode, programs aren't suspended and
- the above functions returns immediately with the count of bytes which were
- read or written by the driver. When used in this way, don't try to use the
- entire buffer after the call, but instead process the number of bytes
- returned, and call the function again.
-
-<sect2>int snd_pcm_info( void *handle, snd_pcm_info_t *info )
- <p>
- Fills the *info structure with data about the PCM device selected by
- *handle. Function returns zero if successful, otherwise it returns
- an error code.
- <code>
- #define SND_PCM_INFO_CODEC 0x00000001
- #define SND_PCM_INFO_DSP SND_PCM_INFO_CODEC
- #define SND_PCM_INFO_MMAP 0x00000002 /* reserved */
- #define SND_PCM_INFO_PLAYBACK 0x00000100
- #define SND_PCM_INFO_RECORD 0x00000200
- #define SND_PCM_INFO_DUPLEX 0x00000400
- #define SND_PCM_INFO_DUPLEX_LIMIT 0x00000800 /* rate for playback & record are same */
-
- struct snd_pcm_info {
- unsigned int type; /* soundcard type */
- unsigned int flags; /* see SND_PCM_INFO_XXXX */
- unsigned char id[32]; /* ID of this PCM device */
- unsigned char name[80]; /* name of this device */
- unsigned char reserved[64]; /* reserved for future use */
- };
- </code>
- <descrip>
- <tag>SND_PCM_INFO_MMAP</tag>
- This flag is reserved and should be never used. It remains for
- compatibility with Open Sound System driver.
- <tag>SND_PCM_INFO_DUPLEX_LIMIT</tag>
- If this bit is set, rate must be same for playback and record direction.
- </descrip>
-
-<sect2>int snd_pcm_playback_info( void *handle, snd_pcm_playback_info_t *info )
- <p>
- Fills the *info structure with data about PCM playback. Function returns
- zero if successful, otherwise it returns an error code.
- <code>
- #define SND_PCM_PINFO_BATCH 0x00000001
- #define SND_PCM_PINFO_8BITONLY 0x00000002
- #define SND_PCM_PINFO_16BITONLY 0x00000004
-
- struct snd_pcm_playback_info {
- unsigned int flags; /* see SND_PCM_PINFO_XXXX */
- unsigned int formats; /* supported formats */
- unsigned int min_rate; /* min rate (in Hz) */
- unsigned int max_rate; /* max rate (in Hz) */
- unsigned int min_channels; /* min channels (probably always 1) */
- unsigned int max_channels; /* max channels */
- unsigned int buffer_size; /* playback buffer size */
- unsigned int min_fragment_size; /* min fragment size in bytes */
- unsigned int max_fragment_size; /* max fragment size in bytes */
- unsigned int fragment_align; /* align fragment value */
- unsigned char reserved[64]; /* reserved for future use */
- };
- </code>
- <descrip>
- <tag>SND_PCM_PINFO_BATCH</tag>
- Driver implements double buffering with this device. This means that
- the chip used for data processing has its own memory, and output should be
- more delayed than if a traditional codec chip is used.
- <tag>SND_PCM_PINFO_8BITONLY</tag>
- If this bit is set, the driver uses 8-bit format for 16-bit samples and
- does software conversion. This bit is set on broken SoundBlaster 16/AWE
- soundcards which can't do full 16-bit duplex. If this bit is set
- application or highter digital audio layer should do the conversion from
- 16-bit samples to 8-bit samples rather than making the driver to do it in
- the kernel.
- <tag>SND_PCM_PINFO_16BITONLY</tag>
- If this bit is set, driver uses 16-bit format for 8-bit samples and
- does software conversion. This bit is set on broken SoundBlaster 16/AWE
- soundcards which can't do full 8-bit duplex. If this bit is set the
- application or highter digital audio layer should do conversion from
- 8-bit samples to 16-bit samples rather than making the driver to do it in
- the kernel.
- </descrip>
-
-<sect2>int snd_pcm_record_info( void *handle, snd_pcm_record_info_t *info )
- <p>
- Fills the *info structure. Returns zero if successful, otherwise it returns
- an error code.
- <code>
- #define SND_PCM_RINFO_BATCH 0x00000001
- #define SND_PCM_RINFO_8BITONLY 0x00000002
- #define SND_PCM_RINFO_16BITONLY 0x00000004
-
- struct snd_pcm_record_info {
- unsigned int flags; /* see to SND_PCM_RINFO_XXXX */
- unsigned int formats; /* supported formats */
- unsigned int min_rate; /* min rate (in Hz) */
- unsigned int max_rate; /* max rate (in Hz) */
- unsigned int min_channels; /* min channels (probably always 1) */
- unsigned int max_channels; /* max channels */
- unsigned int buffer_size; /* record buffer size */
- unsigned int min_fragment_size; /* min fragment size in bytes */
- unsigned int max_fragment_size; /* max fragment size in bytes */
- unsigned int fragment_align; /* align fragment value */
- unsigned char reserved[64]; /* reserved for future... */
- };
- </code>
- <descrip>
- <tag>SND_PCM_PINFO_BATCH</tag>
- Driver implements buffering for this device. This means that
- the chip used for data processing has its own memory and output should be
- more delayed than if a traditional codec chip is used.
- <tag>SND_PCM_PINFO_8BITONLY</tag>
- If this bit is set, the device uses 8-bit format for 16-bit samples and
- does software conversion. This bit is set on broken SoundBlaster 16/AWE
- soundcards which can't do full 16-bit duplex. If this bit is set the
- application or highter digital audio layer should do conversion from
- 16-bit samples to 8-bit samples rather than making the driver to do it in
- the kernel.
- <tag>SND_PCM_PINFO_16BITONLY</tag>
- If this bit is set, the device uses a 16-bit format for 8-bit samples and
- does software conversion. This bit is set on broken SoundBlaster 16/AWE
- soundcards which can't do full 8-bit duplex. If this bit is set the
- application or highter digital audio layer should do the conversion from
- 8-bit samples to 16-bit samples rather than making the driver to do it in
- the kernel.
- </descrip>
-
-<sect2>int snd_pcm_playback_format( void *handle, snd_pcm_format_t *format )
- <p>
- Sets up format, rate (in Hz) and number of channels for playback, in the
- desired direction. Function returns zero if successful, otherwise it
- returns an error code.
- <code>
- struct snd_pcm_format {
- unsigned int format; /* SND_PCM_SFMT_XXXX */
- unsigned int rate; /* rate in Hz */
- unsigned int channels; /* channels (voices) */
- unsigned char reserved[16];
- };
- </code>
-
-<sect2>int snd_pcm_record_format( void *handle, snd_pcm_format_t *format )
- <p>
- Sets up format, rate (in Hz) and number of channels for used for recording
- in the specified direction. Function returns zero if successful, otherwise
- it returns an error code.
- <code>
- struct snd_pcm_format {
- unsigned int format; /* SND_PCM_SFMT_XXXX */
- unsigned int rate; /* rate in Hz */
- unsigned int channels; /* channels (voices) */
- unsigned char reserved[16];
- };
- </code>
-
-<sect2>int snd_pcm_playback_params( void *handle, snd_pcm_playback_params_t *params )
- <p>
- Sets various parameters for playback direction. Function returns zero if
- successful, otherwise it returns an error code.
- <code>
- struct snd_pcm_playback_params {
- int fragment_size;
- int fragments_max;
- int fragments_room;
- unsigned char reserved[16]; /* must be filled with zero */
- };
- </code>
- <descrip>
- <tag>fragment_size</tag>
- Requested size of fragment. This value should be aligned for current
- format (for example to 4 if stereo 16-bit samples are used) or with the
- <it>fragment_align</it> variable from <it>snd_pcm_playback_info_t</it>
- structure. Its range can be from <it>min_fragment_size</it> to
- <it>max_fragment_size</it>.
- <tag>fragments_max</tag>
- Maximum number of fragments in queue for wakeup. This number doesn't
- counts partly used fragment. If current count of filled playback fragments
- is greater than this value driver block application or return immediately
- back if nonblock mode is active.
- <tag>fragments_room</tag>
- Minumum number of fragments writeable for wakeup. This value should be
- in most cases 1 which means return back to application if at least
- one fragment is free for playback. This value includes partly used fragments,
- too.
- </descrip>
-
-<sect2>int snd_pcm_record_params( void *handle, snd_pcm_record_params_t *params )
- <p>
- Function sets various parameters for the recording direction. Function returns
- zero if successful, otherwise it returns an error code.
- <code>
- struct snd_pcm_record_params {
- int fragment_size;
- int fragments_min;
- unsigned char reserved[16];
- };
- </code>
- <descrip>
- <tag>fragment_size</tag>
- Requested size of fragment. This value should be aligned for current
- format (for example to 4 if stereo 16-bit samples are used) or set to the
- <it>fragment_align</it> variable from <it>snd_pcm_playback_info_t</it>
- structure. Its range can be from <it>min_fragment_size</it> to
- <it>max_fragment_size</it>.
- <tag>fragments_min</tag>
- Minimum filled fragments for wakeup. Driver blocks the application (if
- block mode is selected) until it isn't filled with number of fragments
- specified with this value.
- </descrip>
-
-<sect2>int snd_pcm_playback_status( void *handle, snd_pcm_playback_status_t *status )
- <p>
- Fills the *status structure. Function returns zero if successful, otherwise
- it returns an error code.
- <code>
- struct snd_pcm_playback_status {
- unsigned int rate;
- int fragments;
- int fragment_size;
- int count;
- int queue;
- int underrun;
- struct timeval time;
- struct timeval stime;
- unsigned char reserved[16];
- };
- </code>
- <descrip>
- <tag>rate</tag>
- Real playback rate. This value reflects hardware limitations.
- <tag>fragments</tag>
- Currently allocated fragments by the driver for playback direction.
- <tag>fragment_size</tag>
- Current fragment size used by driver for the playback direction.
- <tag>count</tag>
- Count of bytes writeable without blocking.
- <tag>queue</tag>
- Count of bytes in queue. Note: <it>(fragments * fragment_size) - queue</it>
- should not be equal to <it>count</it>.
- <tag>underrun</tag>
- This value tells the application the number of underruns since the ast call
- of <it>snd_pcm_playback_status</it>.
- <tag>time</tag>
- Delay till played of the first sample from next write. This value should
- be used for time synchronization. Returned value is in the same format as
- returned from the standard C function <it>gettimeofday( &ero;time, NULL )</it>.
- This variable contains right value only if playback time mode is enabled
- (look to <it>snd_pcm_playback_time</it> function).
- <tag>stime</tag>
- Time when playback was started.
- This variable contains right value only if playback time mode is enabled
- (look to <it>snd_pcm_playback_time</it> function).
- </descrip>
-
-<sect2>int snd_pcm_record_status( void *handle, snd_pcm_record_status_t *status )
- <p>
- Fills the *status structure. Function returns zero if successful, otherwise
- it returns an error code.
- <code>
- struct snd_pcm_record_status {
- unsigned int rate;
- int fragments;
- int fragment_size;
- int count;
- int free;
- int overrun;
- struct timeval time;
- unsigned char reserved[16];
- };
- </code>
- <descrip>
- <tag>rate</tag>
- Real record rate. This value reflects hardware limitations.
- <tag>fragments</tag>
- Currently allocated fragments by driver for the record direction.
- <tag>fragment_size</tag>
- Current fragment size used by driver for the record direction.
- <tag>count</tag>
- Count of bytes readable without blocking.
- <tag>free</tag>
- Count of bytes in buffer still free. Note: <it>(fragments * fragment_size) - free</it>
- should not be equal to <it>count</it>.
- <tag>overrun</tag>
- This value tells application the count of overruns since the last call
- to <it>snd_pcm_record_status</it>.
- <tag>time</tag>
- Lag since the next sample read was recorded. This value should be used for time
- synchronization. Returned value is in the same format as returned by the
- from standard C function <it>gettimeofday( &ero;time, NULL )</it>. This
- variable contains right value only if record time mode is enabled (look to
- <it>snd_pcm_record_time</it> function).
- <tag>stime</tag>
- Time when record was started. This variable contains right value only if
- record time mode is enabled (look to <it>snd_pcm_record_time</it> function).
- </descrip>
-
-<sect2>int snd_pcm_drain_playback( void *handle )
- <p>
- This function drain playback buffers immediately. Function returns zero
- if successful, otherwise it returns an error code.
-
-<sect2>int snd_pcm_flush_playback( void *handle )
- <p>
- This function flushes the playback buffers. It blocks the program while the
- all the waiting samples in kernel playback buffers are processed. Function
- returns zero if successful, otherwise it returns an error code.
-
-<sect2>int snd_pcm_flush_record( void *handle )
- <p>
- This function flushes (destroyes) record buffers. Function returns zero
- if successful, otherwise it returns an error code.
-
-<sect2>int snd_pcm_playback_time( void *handle, int enable )
- <p>
- This function enables or disables time mode for playback direction. Time mode
- allows to application better time synchronization. Function returns zero
- if successful, otherwise it returns an error code.
-
-<sect2>int snd_pcm_record_time( void *handle, int enable )
- <p>
- This function enables or disables time mode for record direction. Time mode
- allows to application better time synchronization. Function returns zero
- if successful, otherwise it returns an error code.
-
-<sect2>ssize_t snd_pcm_write( void *handle, const void *buffer, size_t size )
- <p>
- Writes samples to the device which must be in the proper format
- specified by the <it>snd_pcm_playback_format</it> function. Function
- returns zero or positive value if playback was successful (value represents
- count of bytes which was successfuly written to device) or an
- error value if error occured. Function should suspend process if
- block mode is active.
-
-<sect2>ssize_t snd_pcm_read( void *handle, void *buffer, size_t size )
- <p>
- Function reads samples from driver. Samples are in format specified
- by <it>snd_pcm_record_format</it> function. Function returns zero
- or positive value if record was success (value represents count of bytes
- which was successfuly read from device) or negative error value if
- error occured. Function should suspend process if block mode is active.
-
-<sect1>Examples
-
-<p>
-The following example shows how to play the first 512kB from the
-/tmp/test.au file with soundcard #0 and PCM device #0:
-
-<tscreen><code>
-int card = 0, device = 0, err, fd, count, size, idx;
-void *handle;
-snd_pcm_format_t format;
-char *buffer;
-
-buffer = (char *)malloc( 512 * 1024 );
-if ( !buffer ) return;
-if ( (err = snd_pcm_open( &ero;handle, card, device, SND_PCM_OPEN_PLAYBACK )) < 0 ) {
- fprintf( stderr, "open failed: %s\n", snd_strerror( err ) );
- return;
-}
-format.format = SND_PCM_SFMT_MU_LAW;
-format.rate = 8000;
-format.channels = 1;
-if ( (err = snd_pcm_playback_format( handle, &ero;format )) < 0 ) {
- fprintf( stderr, "format setup failed: %s\n", snd_strerror( err ) );
- snd_pcm_close( handle );
- return;
-}
-fd = open( "/tmp/test.au", O_RDONLY );
-if ( fd < 0 ) {
- perror( "open file" );
- snd_pcm_close( handle );
- return;
-}
-idx = 0;
-count = read( fd, buffer, 512 * 1024 );
-if ( count <= 0 ) {
- perror( "read from file" );
- snd_pcm_close( handle );
- return;
-}
-close( fd );
-if ( !memcmp( buffer, ".snd", 4 ) ) {
- idx = (buffer[4]<<24)|(buffer[5]<<16)|(buffer[6]<<8)|(buffer[7]);
- if ( idx > 128 ) idx = 128;
- if ( idx > count ) idx = count;
-}
-size = snd_pcm_write( handle, &ero;buffer[ idx ], count - idx );
-printf( "Bytes written %i from %i...\n", size, count - idx );
-snd_pcm_close( handle );
-free( buffer );
-</code></tscreen>
-
-</article>
+++ /dev/null
- Advanced Linux Sound Architecture - Library API
- Jaroslav Kysela <perex@jcu.cz> with assistance from Alan
- Robinson
- v0.0.3, 25 March 1998
-
- This document describes, in full detail, the Advanced Linux Sound
- Architecture library API.
- ______________________________________________________________________
-
- Table of Contents:
-
- 1. Introduction
-
- 2. Error Codes
-
- 2.1. Error Codes in Detail
-
- 2.2. Functions
-
- 2.2.1. const char *snd_strerror( int errnum )
-
- 3. Control Interface
-
- 3.1. Low-Level Layer
-
- 3.1.1. int snd_cards( void )
-
- 3.1.2. unsigned int snd_cards_mask( void )
-
- 3.1.3. int snd_ctl_open( void **handle, int card )
-
- 3.1.4. int snd_ctl_close( void *handle )
-
- 3.1.5. int snd_ctl_file_descriptor( void *handle )
-
- 3.1.6. int snd_ctl_hw_info( void *handle, struct snd_ctl_hw_info
- *info )
-
- 3.1.7. int snd_ctl_pcm_info( void *handle, int dev, snd_pcm_info_t
- *info )
-
- 3.1.8. int snd_ctl_pcm_playback_info( void *handle, int dev,
- snd_pcm_playback_info_t *info )
-
- 3.1.9. int snd_ctl_pcm_record_info( void *handle, int dev,
- snd_pcm_record_info_t *info )
-
- 3.1.10. int snd_ctl_mixer_info( void *handle, int dev,
- snd_mixer_info_t *info )
-
- 3.2. Examples
-
- 4. Mixer Interface
-
- 4.1. Low-Level Layer
-
- 4.1.1. int snd_mixer_open( void **handle, int card, int device )
-
- 4.1.2. int snd_mixer_close( void *handle )
-
- 4.1.3. int snd_mixer_file_descriptor( void *handle )
-
- 4.1.4. int snd_mixer_channels( void *handle )
-
- 4.1.5. int snd_mixer_info( void *handle, snd_mixer_info_t *info )
-
- 4.1.6. int snd_mixer_channel( void *handle, const char *channel_id )
-
- 4.1.7. int snd_mixer_exact_mode( void *handle, int enable )
-
- 4.1.8. int snd_mixer_channel_info( void *handle, int channel,
- snd_mixer_channel_info_t *info )
-
- 4.1.9. int snd_mixer_channel_read( void *handle, int channel,
- snd_mixer_channel_t *data )
-
- 4.1.10. int snd_mixer_channel_write( void *handle, int channel,
- snd_mixer_channel_t *data )
-
- 4.1.11. int snd_mixer_special_read( void *handle, snd_mixer_special_t
- *special )
-
- 4.1.12. int snd_mixer_special_write( void *handle, snd_mixer_special_t
- *special )
-
- 4.1.13. int snd_mixer_read( void *handle, snd_mixer_callbacks_t
- *callbacks )
-
- 4.2. Examples
-
- 5. Digital Audio (PCM) Interface
-
- 5.1. Low-Level Layer
-
- 5.1.1. int snd_pcm_open( void **handle, int card, int device, int
- mode )
-
- 5.1.2. int snd_pcm_close( void *handle )
-
- 5.1.3. int snd_pcm_file_descriptor( void *handle )
-
- 5.1.4. int snd_pcm_block_mode( void *handle, int enable )
-
- 5.1.5. int snd_pcm_info( void *handle, snd_pcm_info_t *info )
-
- 5.1.6. int snd_pcm_playback_info( void *handle,
- snd_pcm_playback_info_t *info )
-
- 5.1.7. int snd_pcm_record_info( void *handle, snd_pcm_record_info_t
- *info )
-
- 5.1.8. int snd_pcm_playback_format( void *handle, snd_pcm_format_t
- *format )
-
- 5.1.9. int snd_pcm_record_format( void *handle, snd_pcm_format_t
- *format )
-
- 5.1.10. int snd_pcm_playback_params( void *handle,
- snd_pcm_playback_params_t *params )
-
- 5.1.11. int snd_pcm_record_params( void *handle,
- snd_pcm_record_params_t *params )
-
- 5.1.12. int snd_pcm_playback_status( void *handle,
- snd_pcm_playback_status_t *status )
-
- 5.1.13. int snd_pcm_record_status( void *handle,
- snd_pcm_record_status_t *status )
-
- 5.1.14. int snd_pcm_drain_playback( void *handle )
-
- 5.1.15. int snd_pcm_flush_playback( void *handle )
-
- 5.1.16. int snd_pcm_flush_record( void *handle )
-
- 5.1.17. int snd_pcm_playback_time( void *handle, int enable )
-
- 5.1.18. int snd_pcm_record_time( void *handle, int enable )
-
- 5.1.19. ssize_t snd_pcm_write( void *handle, const void *buffer,
- size_t size )
-
- 5.1.20. ssize_t snd_pcm_read( void *handle, void *buffer, size_t size
- )
-
- 5.2. Examples
- ______________________________________________________________________
-
- 1\b1.\b. I\bIn\bnt\btr\bro\bod\bdu\buc\bct\bti\bio\bon\bn
-
- The Advanced Linux Sound Architecture comes with a kernel API &
- library API. This document describes the library API and how it
- interfaces with the kernel API. The kernal API will probably never be
- documented in standalone form.
-
- Application programmers should use the library API rather than kernel
- API. The Library offers 100% of the functionally of the kernel API,
- but add next major improvements in usability, making the application
- code simpler and better looking. In addition, some of the some
- fixes/compatibility code in, may be placed in the library code instead
- of the kernel driver.
-
- For a complete list of all variables and functions in the API you
- should look at the following header files:
-
- 1. /usr/include/sys/asoundlib.h
-
- 2. /usr/include/linux/asound.h
-
- 3. /usr/include/linux/asoundid.h
-
- 2\b2.\b. E\bEr\brr\bro\bor\br C\bCo\bod\bde\bes\bs
-
- All functions return int (or some sort of signed value). If this value
- is negative it represents an error code. Codes up to SND_ERROR_BEGIN
- (500000) represents standard system errors. Codes equal or greather
- than this value represents sound library API errors. All error codes
- begin with the prefix _\bS_\bN_\bD_\b__\bE_\bR_\bR_\bO_\bR_\b_.
-
- 2\b2.\b.1\b1.\b. E\bEr\brr\bro\bor\br C\bCo\bod\bde\bes\bs i\bin\bn D\bDe\bet\bta\bai\bil\bl
-
- S\bSN\bND\bD_\b_E\bER\bRR\bRO\bOR\bR_\b_U\bUN\bNC\bCO\bOM\bMP\bPA\bAT\bTI\bIB\bBL\bLE\bE_\b_V\bVE\bER\bRS\bSI\bIO\bON\bN (\b(5\b50\b00\b00\b00\b00\b0)\b)
- This error is caused if the driver uses an incompatible kernel
- API for this interface and hence the library doesn't know how
- this API can be used.
-
- 2\b2.\b.2\b2.\b. F\bFu\bun\bnc\bct\bti\bio\bon\bns\bs
-
- 2\b2.\b.2\b2.\b.1\b1.\b.
-
- c\bco\bon\bns\bst\bt c\bch\bha\bar\br *\b*s\bsn\bnd\bd_\b_s\bst\btr\bre\ber\brr\bro\bor\br(\b( i\bin\bnt\bt e\ber\brr\brn\bnu\bum\bm )\b)
-
- This functions converts error code to a string. Its functionality is
- the same as the _\bs_\bt_\br_\be_\br_\br_\bo_\br function from the standard C library, but
- this function returns correct strings for sound error codes, too.
-
- 3\b3.\b. C\bCo\bon\bnt\btr\bro\bol\bl I\bIn\bnt\bte\ber\brf\bfa\bac\bce\be
-
- The control interfaces gives application various information about the
- currently installed sound driver in the system. The interface should
- be used to detect if another sound interface is present for selected
- soundcard or, for example, to create a list of devices (MIXER, PCM
- etc) from which the user can select.
-
- 3\b3.\b.1\b1.\b. L\bLo\bow\bw-\b-L\bLe\bev\bve\bel\bl L\bLa\bay\bye\ber\br
-
- 3\b3.\b.1\b1.\b.1\b1.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_c\bca\bar\brd\bds\bs(\b( v\bvo\boi\bid\bd )\b)
-
- Returns the number of soundcards present in the system, if any.
- Otherwise it returns a negative value, which maps to an error code.
- This function will return 0 if no soundcards are detected.
-
- 3\b3.\b.1\b1.\b.2\b2.\b.
-
- u\bun\bns\bsi\big\bgn\bne\bed\bd i\bin\bnt\bt s\bsn\bnd\bd_\b_c\bca\bar\brd\bds\bs_\b_m\bma\bas\bsk\bk(\b( v\bvo\boi\bid\bd )\b)
-
- Returns the bitmap of soundcards present in the system, if any.
- Otherwise it returns a negative value, which maps to an error code.
- This function will return 0 if no soundcards are detected. First
- soundcard is represented with bit 0.
-
- 3\b3.\b.1\b1.\b.3\b3.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_c\bct\btl\bl_\b_o\bop\bpe\ben\bn(\b( v\bvo\boi\bid\bd *\b**\b*h\bha\ban\bnd\bdl\ble\be,\b, i\bin\bnt\bt c\bca\bar\brd\bd )\b)
-
- Creates a new handle and opens communication with the kernel sound
- control interface for soundcard number _\bc_\ba_\br_\bd (0-N). The function also
- checks if protocol is compatible, so as to prevent the use of old
- programs with a new kernel API. Function returns zero if successful,
- otherwise an error code is returned.
-
- 3\b3.\b.1\b1.\b.4\b4.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_c\bct\btl\bl_\b_c\bcl\blo\bos\bse\be(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be )\b)
-
- Function frees all resources allocated with control handle and closes
- the kernel sound control interface. Function returns zero if
- successful, otherwise it returns an error code.
-
- 3\b3.\b.1\b1.\b.5\b5.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_c\bct\btl\bl_\b_f\bfi\bil\ble\be_\b_d\bde\bes\bsc\bcr\bri\bip\bpt\bto\bor\br(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be )\b)
-
- Function returns file descriptor for the kernel sound control
- interface. This function should be used in very special cases.
- Function returns a negative error code if some error was encountered.
- 3\b3.\b.1\b1.\b.6\b6.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_c\bct\btl\bl_\b_h\bhw\bw_\b_i\bin\bnf\bfo\bo(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, s\bst\btr\bru\buc\bct\bt s\bsn\bnd\bd_\b_c\bct\btl\bl_\b_h\bhw\bw_\b_i\bin\bnf\bfo\bo *\b*i\bin\bnf\bfo\bo )\b)
-
- Fills the info structure with data about the sound hardware referenced
- by handle. Function returns zero if successful, otherwise it returns
- an error code.
-
- ______________________________________________________________________
- #define SND_CTL_GCAPS_MIDI 0x0000001 /* driver has MIDI interface */
-
- #define SND_CTL_LCAPS_SYNTH 0x0000001 /* soundcard has synthesizer */
- #define SND_CTL_LCAPS_RAWFM 0x0000002 /* soundcard has RAW FM/OPL3 */
-
- struct snd_ctl_hw_info {
- unsigned int type; /* type of card - see SND_CARD_TYPE_XXXX */
- unsigned int gcaps; /* see SND_CTL_GCAPS_XXXX */
- unsigned int lcaps; /* see SND_CTL_LCAPS_XXXX */
- unsigned int pcmdevs; /* count of PCM devices (0 to N) */
- unsigned int mixerdevs; /* count of MIXER devices (0 to N) */
- unsigned int mididevs; /* count of raw MIDI devices (0 to N) */
- char id[8]; /* ID of card (user selectable) */
- char name[80]; /* name/info text about soundcard */
- unsigned char reserved[128]; /* reserved for future use */
- };
-
- ______________________________________________________________________
-
- 3\b3.\b.1\b1.\b.7\b7.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_c\bct\btl\bl_\b_p\bpc\bcm\bm_\b_i\bin\bnf\bfo\bo(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, i\bin\bnt\bt d\bde\bev\bv,\b, s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_i\bin\bnf\bfo\bo_\b_t\bt *\b*i\bin\bnf\bfo\bo )\b)
-
- Fills the *info structure with data about the PCM device. Function
- returns zero if successful, otherwise it returns an error code.
- Details about the snd_pcm_info_t structure are in the D\bDi\big\bgi\bit\bta\bal\bl A\bAu\bud\bdi\bio\bo
- (\b(P\bPC\bCM\bM)\b) I\bIn\bnt\bte\ber\brf\bfa\bac\bce\be section. The argument _\bd_\be_\bv selects the device number
- for the soundcard referenced by *handle. Its range is 0 to N where N
- is _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bn_\bd_\b__\bc_\bt_\bl_\b__\bh_\bw_\b__\bi_\bn_\bf_\bo _\b-_\b> _\bp_\bc_\bm_\bd_\be_\bv_\bs _\b- _\b1. This function will work if
- the selected PCM device is busy, too. It should be used to collect
- information about PCM devices without exclusive lock.
-
- 3\b3.\b.1\b1.\b.8\b8.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_c\bct\btl\bl_\b_p\bpc\bcm\bm_\b_p\bpl\bla\bay\byb\bba\bac\bck\bk_\b_i\bin\bnf\bfo\bo(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, i\bin\bnt\bt d\bde\bev\bv,\b, s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_p\bpl\bla\bay\by-\b-
- b\bba\bac\bck\bk_\b_i\bin\bnf\bfo\bo_\b_t\bt *\b*i\bin\bnf\bfo\bo )\b)
-
- Fills the *info structure with data about the PCM device and playback
- direction. Function returns zero if successful, otherwise it returns
- an error code. Details about the snd_pcm_playback_info_t structure
- are in the D\bDi\big\bgi\bit\bta\bal\bl A\bAu\bud\bdi\bio\bo (\b(P\bPC\bCM\bM)\b) I\bIn\bnt\bte\ber\brf\bfa\bac\bce\be section. The argument _\bd_\be_\bv
- selects the device number for the soundcard referenced by *handle. Its
- range is 0 to N where N is _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bn_\bd_\b__\bc_\bt_\bl_\b__\bh_\bw_\b__\bi_\bn_\bf_\bo _\b-_\b> _\bp_\bc_\bm_\bd_\be_\bv_\bs _\b- _\b1.
- This function will work if the selected PCM device is busy, too. It
- should be used to collect information about PCM devices without
- exclusive lock.
-
- 3\b3.\b.1\b1.\b.9\b9.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_c\bct\btl\bl_\b_p\bpc\bcm\bm_\b_r\bre\bec\bco\bor\brd\bd_\b_i\bin\bnf\bfo\bo(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, i\bin\bnt\bt d\bde\bev\bv,\b,
- s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_r\bre\bec\bco\bor\brd\bd_\b_i\bin\bnf\bfo\bo_\b_t\bt *\b*i\bin\bnf\bfo\bo )\b)
-
- Fills the *info structure with data about the PCM device and record
- direction. Function returns zero if successful, otherwise it returns
- an error code. Details about the snd_pcm_record_info_t structure are
- in the D\bDi\big\bgi\bit\bta\bal\bl A\bAu\bud\bdi\bio\bo (\b(P\bPC\bCM\bM)\b) I\bIn\bnt\bte\ber\brf\bfa\bac\bce\be section. The argument _\bd_\be_\bv selects
- the device number for the soundcard referenced by *handle. Its range
- is 0 to N where N is _\bs_\bt_\br_\bu_\bc_\bt _\bs_\bn_\bd_\b__\bc_\bt_\bl_\b__\bh_\bw_\b__\bi_\bn_\bf_\bo _\b-_\b> _\bp_\bc_\bm_\bd_\be_\bv_\bs _\b- _\b1. This
- function will work if the selected PCM device is busy, too. It should
- be used to collect information about PCM devices without exclusive
- lock.
-
- 3\b3.\b.1\b1.\b.1\b10\b0.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_c\bct\btl\bl_\b_m\bmi\bix\bxe\ber\br_\b_i\bin\bnf\bfo\bo(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, i\bin\bnt\bt d\bde\bev\bv,\b, s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_i\bin\bnf\bfo\bo_\b_t\bt *\b*i\bin\bnf\bfo\bo
- )\b)
-
- Fills the *info structure with data about the mixer device. Returns
- zero if successful, otherwise it returns an error code. Details about
- the snd_mixer_info_t structure are in the M\bMi\bix\bxe\ber\br I\bIn\bnt\bte\ber\brf\bfa\bac\bce\be section.
- The argument _\bd_\be_\bv specifies the device number for the appropriate
- soundcard. Its range is 0 to N where N found from _\bs_\bt_\br_\bu_\bc_\bt
- _\bs_\bn_\bd_\b__\bc_\bt_\bl_\b__\bh_\bw_\b__\bi_\bn_\bf_\bo _\b-_\b> _\bm_\bi_\bx_\be_\br_\bd_\be_\bv_\bs _\b- _\b1. It should be used to collect
- information about mixer devices.
-
- 3\b3.\b.2\b2.\b. E\bEx\bxa\bam\bmp\bpl\ble\bes\bs
-
- The following example shows how all PCM devices can be detected for
- the first soundcard (#0) in the system.
-
- ______________________________________________________________________
- int card = 0, err;
- void *handle;
- stuct snd_ctl_hw_info info;
-
- if ( (err = snd_ctl_open( &handle, card )) < 0 ) {
- fprintf( stderr, "open failed: %s\n", snd_strerror( err ) );
- return;
- }
- if ( (err = snd_ctl_hw_info( handle, &info )) < 0 ) {
- fprintf( stderr, "hw info failed: %s\n", snd_strerror( err ) );
- snd_ctl_close( handle );
- return;
- }
- printf( "Installed PCM devices for card #i: %i\n", card + 1, info.pcmdevs );
- snd_ctl_close( handle );
- ______________________________________________________________________
-
- 4\b4.\b. M\bMi\bix\bxe\ber\br I\bIn\bnt\bte\ber\brf\bfa\bac\bce\be
-
- The Mixer Interface allows applications to change the volume level of
- a soundcard's input/output channels in both the linear range (0-100)
- and in decibels. It also supports features like hardware mute, input
- sound source, etc.
-
- 4\b4.\b.1\b1.\b. L\bLo\bow\bw-\b-L\bLe\bev\bve\bel\bl L\bLa\bay\bye\ber\br
-
- Mixer devices aren't opened exclusively. This allows applications to
- open a device multiple times with one or more processes.
- 4\b4.\b.1\b1.\b.1\b1.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_o\bop\bpe\ben\bn(\b( v\bvo\boi\bid\bd *\b**\b*h\bha\ban\bnd\bdl\ble\be,\b, i\bin\bnt\bt c\bca\bar\brd\bd,\b, i\bin\bnt\bt d\bde\bev\bvi\bic\bce\be )\b)
-
- Creates new handle and opens a connection to the kernel sound mixer
- interface for soundcard number _\bc_\ba_\br_\bd (0-N) and mixer device number
- _\bd_\be_\bv_\bi_\bc_\be. Also checks if protocol is compatible to prevent use of old
- programs with new kernel API. Function returns zero if successful,
- otherwise it returns an error code.
-
- 4\b4.\b.1\b1.\b.2\b2.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_c\bcl\blo\bos\bse\be(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be )\b)
-
- Frees all resources allocated to the mixer handle and closes its
- connection to the kernel sound mixer interface. Function returns zero
- if successful, otherwise it returns an error code.
-
- 4\b4.\b.1\b1.\b.3\b3.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_f\bfi\bil\ble\be_\b_d\bde\bes\bsc\bcr\bri\bip\bpt\bto\bor\br(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be )\b)
-
- Returns the file descriptor for the connection to the kernel sound
- mixer interface. This function should be used only in very special
- cases. Function returns a negative error code if an error was
- encountered.
-
- The file descriptor should be used for the _\bs_\be_\bl_\be_\bc_\bt synchronous
- multiplexer function for deterimeing read direction. Applications
- should call _\bs_\bn_\bd_\b__\bm_\bi_\bx_\be_\br_\b__\br_\be_\ba_\bd function if some data is waiting to be
- read. It is recomended that you do this, since it leaves place for
- this function to handle some new kernel API specifications.
-
- 4\b4.\b.1\b1.\b.4\b4.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_c\bch\bha\ban\bnn\bne\bel\bls\bs(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be )\b)
-
- Returns the count of mixer channels for appropriate mixer device,
- otherwise the return value is negative, and signifies an error code.
- Never returns zero.
-
- 4\b4.\b.1\b1.\b.5\b5.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_i\bin\bnf\bfo\bo(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_i\bin\bnf\bfo\bo_\b_t\bt *\b*i\bin\bnf\bfo\bo )\b)
-
- Fills the *info structure with information about the mixer associated
- with *handle. Returns zero if successful, otherwise it returns an
- error code.
-
- ______________________________________________________________________
- #define SND_MIXER_INFO_CAP_EXCL_RECORD 0x00000001
-
- struct snd_mixer_info {
- unsigned int type; /* type of soundcard - SND_CARD_TYPE_XXXX */
- unsigned int channels; /* count of mixer devices */
- unsigned int caps; /* some flags about this device (SND_MIXER_INFO_CAP_XXXX) */
- unsigned char id[32]; /* ID of this mixer */
- unsigned char name[80]; /* name of this device */
- char reserved[ 32 ]; /* reserved for future use */
- };
-
- ______________________________________________________________________
-
- 4\b4.\b.1\b1.\b.6\b6.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_c\bch\bha\ban\bnn\bne\bel\bl(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, c\bco\bon\bns\bst\bt c\bch\bha\bar\br *\b*c\bch\bha\ban\bnn\bne\bel\bl_\b_i\bid\bd )\b)
-
- Returns the channel number (index) associated with channel_id (channel
- name), or returns an error code.
-
- ______________________________________________________________________
- #define SND_MIXER_ID_MASTER "Master"
- #define SND_MIXER_ID_BASS "Bass"
- #define SND_MIXER_ID_TREBLE "Treble"
- #define SND_MIXER_ID_SYNTHESIZER "Synth"
- #define SND_MIXER_ID_SYNTHESIZER1 "Synth 1"
- #define SND_MIXER_ID_FM "FM"
- #define SND_MIXER_ID_EFFECT "Effect"
- #define SND_MIXER_ID_PCM "PCM"
- #define SND_MIXER_ID_PCM1 "PCM 1"
- #define SND_MIXER_ID_LINE "Line-In"
- #define SND_MIXER_ID_MIC "MIC"
- #define SND_MIXER_ID_CD "CD"
- #define SND_MIXER_ID_GAIN "Record-Gain"
- #define SND_MIXER_ID_IGAIN "In-Gain"
- #define SND_MIXER_ID_OGAIN "Out-Gain"
- #define SND_MIXER_ID_LOOPBACK "Loopback"
- #define SND_MIXER_ID_SPEAKER "PC Speaker"
- #define SND_MIXER_ID_AUXA "Aux A"
- #define SND_MIXER_ID_AUXB "Aux B"
- #define SND_MIXER_ID_AUXC "Aux C"
-
- ______________________________________________________________________
-
- 4\b4.\b.1\b1.\b.7\b7.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_e\bex\bxa\bac\bct\bt_\b_m\bmo\bod\bde\be(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, i\bin\bnt\bt e\ben\bna\bab\bbl\ble\be )\b)
-
- Turns on or off (by default) exact mode. This mode allows to
- application set/get volume values in exact range which uses hardware.
- In non-exact mode is range always from 0 to 100 and conversion to
- hardware range does driver. Function returns zero if successful,
- otherwise it returns an error code.
-
- 4\b4.\b.1\b1.\b.8\b8.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_c\bch\bha\ban\bnn\bne\bel\bl_\b_i\bin\bnf\bfo\bo(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, i\bin\bnt\bt c\bch\bha\ban\bnn\bne\bel\bl,\b, s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_c\bch\bha\ban\bn-\b-
- n\bne\bel\bl_\b_i\bin\bnf\bfo\bo_\b_t\bt *\b*i\bin\bnf\bfo\bo )\b)
- Fills the *info structure. The argument _\bc_\bh_\ba_\bn_\bn_\be_\bl specifies channel (0
- to N) for which is the info requested. Function returns zero if
- successful, otherwise it returns an error code.
-
- ______________________________________________________________________
- #define SND_MIXER_CINFO_CAP_RECORD 0x00000001
- #define SND_MIXER_CINFO_CAP_STEREO 0x00000002
- #define SND_MIXER_CINFO_CAP_MUTE 0x00000004
- #define SND_MIXER_CINFO_CAP_HWMUTE 0x00000008 /* channel supports hardware mute */
- #define SND_MIXER_CINFO_CAP_DIGITAL 0x00000010 /* channel does digital (not analog) mixing */
- #define SND_MIXER_CINOF_CAP_INPUT 0x00000020 /* input channel */
-
- struct snd_mixer_channel_info {
- unsigned int channel; /* channel # (filled by application) */
- unsigned int parent; /* parent channel # or SND_MIXER_PARENT */
- unsigned char name[12]; /* name of this device */
- unsigned int caps; /* some flags about this device (SND_MIXER_CINFO_XXXX) */
- int min; /* min. value when exact mode (or always 0) */
- int max; /* max. value when exact mode (or always 100) */
- int min_dB; /* minimum decibel value (*100) */
- int max_dB; /* maximum decibel value (*100) */
- int step_dB; /* step decibel value (*100) */
- unsigned char reserved[16];
- };
-
- ______________________________________________________________________
-
- 4\b4.\b.1\b1.\b.9\b9.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_c\bch\bha\ban\bnn\bne\bel\bl_\b_r\bre\bea\bad\bd(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, i\bin\bnt\bt c\bch\bha\ban\bnn\bne\bel\bl,\b, s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_c\bch\bha\ban\bn-\b-
- n\bne\bel\bl_\b_t\bt *\b*d\bda\bat\bta\ba )\b)
-
- Fills the *data structure. The argument _\bc_\bh_\ba_\bn_\bn_\be_\bl specifies the channel
- (0 to N) for which is data requested. Function returns zero if
- successful, otherwise it returns an error code.
-
- ______________________________________________________________________
- #define SND_MIXER_FLG_RECORD 0x00000001 /* channel record source flag */
- #define SND_MIXER_FLG_MUTE_LEFT 0x00010000
- #define SND_MIXER_FLG_MUTE_RIGHT 0x00020000
- #define SND_MIXER_FLG_MUTE 0x00030000
- #define SND_MIXER_FLG_DECIBEL 0x40000000
- #define SND_MIXER_FLG_FORCE 0x80000000
-
- struct snd_mixer_channel {
- unsigned int channel; /* channel # (filled by application) */
- unsigned int flags; /* some flags to read/write (SND_MIXER_FLG_XXXX) */
- int left; /* min - max when exact mode (or 0 - 100) */
- int right; /* min - max when exact mode (or 0 - 100) */
- int left_dB; /* dB * 100 */
- int right_dB; /* dB * 100 */
- unsigned char reserved[16];
- };
-
- ______________________________________________________________________
-
- S\bSN\bND\bD_\b_M\bMI\bIX\bXE\bER\bR_\b_F\bFL\bLG\bG_\b_R\bRE\bEC\bCO\bOR\bRD\bD
- Record source flag.
-
- S\bSN\bND\bD_\b_M\bMI\bIX\bXE\bER\bR_\b_F\bFL\bLG\bG_\b_D\bDE\bEC\bCI\bIB\bBE\bEL\bL
- If this bit is set, driver set volume from dB variables _\bl_\be_\bf_\bt_\b__\bd_\bB
- and _\br_\bi_\bg_\bh_\bt_\b__\bd_\bB.
-
- S\bSN\bND\bD_\b_M\bMI\bIX\bXE\bER\bR_\b_F\bFL\bLG\bG_\b_F\bFO\bOR\bRC\bCE\bE
- Force set - this bit shouldn't be used from user space. Reserved
- for kernel.
-
- 4\b4.\b.1\b1.\b.1\b10\b0.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_c\bch\bha\ban\bnn\bne\bel\bl_\b_w\bwr\bri\bit\bte\be(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, i\bin\bnt\bt c\bch\bha\ban\bnn\bne\bel\bl,\b,
- s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_c\bch\bha\ban\bnn\bne\bel\bl_\b_t\bt *\b*d\bda\bat\bta\ba )\b)
-
- Writes the *data structure to kernel. The _\bc_\bh_\ba_\bn_\bn_\be_\bl argument specifies
- the channel (0 to N) for which is data is to be applied. Function
- returns zero if successful, otherwise it returns an error code. This
- functions is the opposite of _\bs_\bn_\bd_\b__\bm_\bi_\bx_\be_\br_\b__\bc_\bh_\ba_\bn_\bn_\be_\bl_\b__\br_\be_\ba_\bd.
-
- 4\b4.\b.1\b1.\b.1\b11\b1.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_s\bsp\bpe\bec\bci\bia\bal\bl_\b_r\bre\bea\bad\bd(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_s\bsp\bpe\bec\bci\bia\bal\bl_\b_t\bt *\b*s\bsp\bpe\bec\bci\bia\bal\bl
- )\b)
-
- Not documented...
-
- 4\b4.\b.1\b1.\b.1\b12\b2.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_s\bsp\bpe\bec\bci\bia\bal\bl_\b_w\bwr\bri\bit\bte\be(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_s\bsp\bpe\bec\bci\bia\bal\bl_\b_t\bt *\b*s\bsp\bpe\be-\b-
- c\bci\bia\bal\bl )\b)
-
- Not documented...
-
- 4\b4.\b.1\b1.\b.1\b13\b3.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_r\bre\bea\bad\bd(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, s\bsn\bnd\bd_\b_m\bmi\bix\bxe\ber\br_\b_c\bca\bal\bll\blb\bba\bac\bck\bks\bs_\b_t\bt *\b*c\bca\bal\bll\blb\bba\bac\bck\bks\bs )\b)
-
- This function reads and parses data from driver. Parsed actions are
- returned back to the application using the _\bc_\ba_\bl_\bl_\bb_\ba_\bc_\bk_\bs structure.
- Applications should not parse data from the driver in standard cases.
- This function returns immediately after all data is read from driver.
- Does not block process.
-
- ______________________________________________________________________
- typedef struct snd_mixer_callbacks {
- void *private_data; /* should be used by application */
- void (*channel_was_changed)( void *private_data, int channel );
- void *reserved[15]; /* reserved for future use - must be NULL!!! */
- } snd_mixer_callbacks_t;
-
- ______________________________________________________________________
-
- 4\b4.\b.2\b2.\b. E\bEx\bxa\bam\bmp\bpl\ble\bes\bs
-
- The following example shows installed mixer channels for soundcard #0
- and mixer device #0 in the system, and also sets the master volume (if
- present) to 50.
-
- ______________________________________________________________________
- int card = 0, device = 0, err;
- void *handle;
- snd_mixer_info_t info;
- snd_mixer_channel_t channel;
-
- if ( (err = snd_mixer_open( &handle, card, device )) < 0 ) {
- fprintf( stderr, "open failed: %s\n", snd_strerror( err ) );
- return;
- }
- if ( (err = snd_mixer_info( handle, &info )) < 0 ) {
- fprintf( stderr, "info failed: %s\n", snd_strerror( err ) );
- snd_mixer_close( handle );
- return;
- }
- printf( "Installed MIXER channels for card #i and device %i: %i\n",
- card + 1, device, info.channels );
- master = snd_mixer_channel( handle, SND_MIXER_ID_MASTER );
- if ( master >= 0 ) {
- if ( (err = snd_mixer_read( handle, master, &channel )) < 0 ) {
- fprintf( stderr, "master read failed: %s\n", snd_strerror( err ) );
- snd_mixer_close( handle );
- return;
- }
- channel -> left = channel -> right = 50;
- if ( (err = snd_mixer_write( handle, master, &channel )) < 0 ) {
- fprintf( stderr, "master write failed: %s\n", snd_strerror( err ) );
- snd_mixer_close( handle );
- return;
- }
- }
- snd_mixer_close( handle );
- ______________________________________________________________________
-
- 5\b5.\b. D\bDi\big\bgi\bit\bta\bal\bl A\bAu\bud\bdi\bio\bo (\b(P\bPC\bCM\bM)\b) I\bIn\bnt\bte\ber\brf\bfa\bac\bce\be
-
- 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 8 kHz (telephone quality) and
- 48 kHz (DAT tapes).
-
- 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).
-
- 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 than 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, a 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 DAC.
-
- Sample encoding limits the dynamic range of 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 * 6 dB . This means that 8 bits sampling resolution
- gives dynamic range of 48 dB and 16 bit resolution gives 96 dB.
-
- 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 8 kHz/8 bits/mono but 48 kHz/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.5 Mbps 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 out of the scope of this
- document.
-
- 5\b5.\b.1\b1.\b. L\bLo\bow\bw-\b-L\bLe\bev\bve\bel\bl L\bLa\bay\bye\ber\br
-
- Audio devices are opened exclusively for a selected direction. This
- doesn't allow open from more than one processes for the same audio
- device in the same direction, but does allow one open call to each
- playback direction and second open call to record direction
- independently. Audio devices return EBUSY error to applications when
- other applications have already opened the requested direction.
-
- Low-Level layer supports these formats:
-
- ______________________________________________________________________
- #define SND_PCM_SFMT_MU_LAW 0
- #define SND_PCM_SFMT_A_LAW 1
- #define SND_PCM_SFMT_IMA_ADPCM 2
- #define SND_PCM_SFMT_U8 3
- #define SND_PCM_SFMT_S16_LE 4
- #define SND_PCM_SFMT_S16_BE 5
- #define SND_PCM_SFMT_S8 6
- #define SND_PCM_SFMT_U16_LE 7
- #define SND_PCM_SFMT_U16_BE 8
- #define SND_PCM_SFMT_MPEG 9
- #define SND_PCM_SFMT_GSM 10
-
- #define SND_PCM_FMT_MU_LAW (1 << SND_PCM_SFMT_MU_LAW)
- #define SND_PCM_FMT_A_LAW (1 << SND_PCM_SFMT_A_LAW)
- #define SND_PCM_FMT_IMA_ADPCM (1 << SND_PCM_SFMT_IMA_ADPCM)
- #define SND_PCM_FMT_U8 (1 << SND_PCM_SFMT_U8)
- #define SND_PCM_FMT_S16_LE (1 << SND_PCM_SFMT_S16_LE)
- #define SND_PCM_FMT_S16_BE (1 << SND_PCM_SFMT_S16_BE)
- #define SND_PCM_FMT_S8 (1 << SND_PCM_SFMT_S8)
- #define SND_PCM_FMT_U16_LE (1 << SND_PCM_SFMT_U16_LE)
- #define SND_PCM_FMT_U16_BE (1 << SND_PCM_SFMT_U16_BE)
- #define SND_PCM_FMT_MPEG (1 << SND_PCM_SFMT_MPEG)
- #define SND_PCM_FMT_GSM (1 << SND_PCM_SFMT_GSM)
- ______________________________________________________________________
-
- Constants with prefix S\bSN\bND\bD_\b_P\bPC\bCM\bM_\b_F\bFM\bMT\bT_\b_ are used in info structures and
- constants with prefix S\bSN\bND\bD_\b_P\bPC\bCM\bM_\b_S\bSF\bFM\bMT\bT_\b_ are used in format structures.
- 5\b5.\b.1\b1.\b.1\b1.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_o\bop\bpe\ben\bn(\b( v\bvo\boi\bid\bd *\b**\b*h\bha\ban\bnd\bdl\ble\be,\b, i\bin\bnt\bt c\bca\bar\brd\bd,\b, i\bin\bnt\bt d\bde\bev\bvi\bic\bce\be,\b, i\bin\bnt\bt m\bmo\bod\bde\be )\b)
-
- Creates a new handle and opens a connection to kernel sound audio
- interface for soundcard number _\bc_\ba_\br_\bd (0-N) and audio device number
- _\bd_\be_\bv_\bi_\bc_\be. Function also checks if protocol is compatible to prevent use
- of old programs with a new kernel API. Function returns zero if
- successful,ful otherwise it returns an error code. Error code -EBUSY
- is returned when some process ownes the selected direction.
-
- Default format after opening is mono _\bm_\bu_\b-_\bL_\ba_\bw at 8000Hz. This device can
- be used directly for playback of standard .au (Sparc) files.
-
- The following modes should be used for the _\bm_\bo_\bd_\be argument:
-
- ______________________________________________________________________
- #define SND_PCM_OPEN_PLAYBACK (O_WRONLY)
- #define SND_PCM_OPEN_RECORD (O_RDONLY)
- #define SND_PCM_OPEN_DUPLEX (O_RDWR)
-
- ______________________________________________________________________
-
- 5\b5.\b.1\b1.\b.2\b2.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_c\bcl\blo\bos\bse\be(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be )\b)
-
- Frees all resources allocated with audio handle and closes the
- connection to the kernel sound audio interface. Function returns zero
- if successful, otherwise it returns an error code.
-
- 5\b5.\b.1\b1.\b.3\b3.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_f\bfi\bil\ble\be_\b_d\bde\bes\bsc\bcr\bri\bip\bpt\bto\bor\br(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be )\b)
-
- Returns the file descriptor of the connection to the kernel sound
- audio interface. Function returns an error code if an error was
- encountered.
-
- The file descriptor should be used for the _\bs_\be_\bl_\be_\bc_\bt synchronous
- multiplexer function for setting the read direction. Application
- should call _\bs_\bn_\bd_\b__\bp_\bc_\bm_\b__\br_\be_\ba_\bd or _\bs_\bn_\bd_\b__\bp_\bc_\bm_\b__\bw_\br_\bi_\bt_\be functions if some data is
- waiting for reading or a write can be performed. Calling this function
- is highly recomended, as it leaves a place for the API to things like
- data conversions, if needed.
-
- 5\b5.\b.1\b1.\b.4\b4.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_b\bbl\blo\boc\bck\bk_\b_m\bmo\bod\bde\be(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, i\bin\bnt\bt e\ben\bna\bab\bbl\ble\be )\b)
-
- Sets up block (default) or nonblock mode for a handle. Block mode
- suspends execution of a program when _\bs_\bn_\bd_\b__\bp_\bc_\bm_\b__\br_\be_\ba_\bd or _\bs_\bn_\bd_\b__\bp_\bc_\bm_\b__\bw_\br_\bi_\bt_\be is
- called for the time which is needed for the actual playback or record
- over of the entire buffer. In nonblock mode, programs aren't suspended
- and the above functions returns immediately with the count of bytes
- which were read or written by the driver. When used in this way, don't
- try to use the entire buffer after the call, but instead process the
- number of bytes returned, and call the function again.
-
- 5\b5.\b.1\b1.\b.5\b5.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_i\bin\bnf\bfo\bo(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_i\bin\bnf\bfo\bo_\b_t\bt *\b*i\bin\bnf\bfo\bo )\b)
-
- Fills the *info structure with data about the PCM device selected by
- *handle. Function returns zero if successful, otherwise it returns an
- error code.
-
- ______________________________________________________________________
- #define SND_PCM_INFO_CODEC 0x00000001
- #define SND_PCM_INFO_DSP SND_PCM_INFO_CODEC
- #define SND_PCM_INFO_MMAP 0x00000002 /* reserved */
- #define SND_PCM_INFO_PLAYBACK 0x00000100
- #define SND_PCM_INFO_RECORD 0x00000200
- #define SND_PCM_INFO_DUPLEX 0x00000400
- #define SND_PCM_INFO_DUPLEX_LIMIT 0x00000800 /* rate for playback & record are same */
-
- struct snd_pcm_info {
- unsigned int type; /* soundcard type */
- unsigned int flags; /* see SND_PCM_INFO_XXXX */
- unsigned char id[32]; /* ID of this PCM device */
- unsigned char name[80]; /* name of this device */
- unsigned char reserved[64]; /* reserved for future use */
- };
-
- ______________________________________________________________________
-
- S\bSN\bND\bD_\b_P\bPC\bCM\bM_\b_I\bIN\bNF\bFO\bO_\b_M\bMM\bMA\bAP\bP
- This flag is reserved and should be never used. It remains for
- compatibility with Open Sound System driver.
-
- S\bSN\bND\bD_\b_P\bPC\bCM\bM_\b_I\bIN\bNF\bFO\bO_\b_D\bDU\bUP\bPL\bLE\bEX\bX_\b_L\bLI\bIM\bMI\bIT\bT
- If this bit is set, rate must be same for playback and record
- direction.
-
- 5\b5.\b.1\b1.\b.6\b6.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_p\bpl\bla\bay\byb\bba\bac\bck\bk_\b_i\bin\bnf\bfo\bo(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_p\bpl\bla\bay\byb\bba\bac\bck\bk_\b_i\bin\bnf\bfo\bo_\b_t\bt *\b*i\bin\bnf\bfo\bo
- )\b)
-
- Fills the *info structure with data about PCM playback. Function
- returns zero if successful, otherwise it returns an error code.
-
- ______________________________________________________________________
- #define SND_PCM_PINFO_BATCH 0x00000001
- #define SND_PCM_PINFO_8BITONLY 0x00000002
- #define SND_PCM_PINFO_16BITONLY 0x00000004
-
- struct snd_pcm_playback_info {
- unsigned int flags; /* see SND_PCM_PINFO_XXXX */
- unsigned int formats; /* supported formats */
- unsigned int min_rate; /* min rate (in Hz) */
- unsigned int max_rate; /* max rate (in Hz) */
- unsigned int min_channels; /* min channels (probably always 1) */
- unsigned int max_channels; /* max channels */
- unsigned int buffer_size; /* playback buffer size */
- unsigned int min_fragment_size; /* min fragment size in bytes */
- unsigned int max_fragment_size; /* max fragment size in bytes */
- unsigned int fragment_align; /* align fragment value */
- unsigned char reserved[64]; /* reserved for future use */
- };
-
- ______________________________________________________________________
-
- S\bSN\bND\bD_\b_P\bPC\bCM\bM_\b_P\bPI\bIN\bNF\bFO\bO_\b_B\bBA\bAT\bTC\bCH\bH
- Driver implements double buffering with this device. This means
- that the chip used for data processing has its own memory, and
- output should be more delayed than if a traditional codec chip
- is used.
-
- S\bSN\bND\bD_\b_P\bPC\bCM\bM_\b_P\bPI\bIN\bNF\bFO\bO_\b_8\b8B\bBI\bIT\bTO\bON\bNL\bLY\bY
- If this bit is set, the driver uses 8-bit format for 16-bit
- samples and does software conversion. This bit is set on broken
- SoundBlaster 16/AWE soundcards which can't do full 16-bit
- duplex. If this bit is set application or highter digital audio
- layer should do the conversion from 16-bit samples to 8-bit
- samples rather than making the driver to do it in the kernel.
-
- S\bSN\bND\bD_\b_P\bPC\bCM\bM_\b_P\bPI\bIN\bNF\bFO\bO_\b_1\b16\b6B\bBI\bIT\bTO\bON\bNL\bLY\bY
- If this bit is set, driver uses 16-bit format for 8-bit samples
- and does software conversion. This bit is set on broken
- SoundBlaster 16/AWE soundcards which can't do full 8-bit duplex.
- If this bit is set the application or highter digital audio
- layer should do conversion from 8-bit samples to 16-bit samples
- rather than making the driver to do it in the kernel.
-
- 5\b5.\b.1\b1.\b.7\b7.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_r\bre\bec\bco\bor\brd\bd_\b_i\bin\bnf\bfo\bo(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_r\bre\bec\bco\bor\brd\bd_\b_i\bin\bnf\bfo\bo_\b_t\bt *\b*i\bin\bnf\bfo\bo )\b)
-
- Fills the *info structure. Returns zero if successful, otherwise it
- returns an error code.
-
- ______________________________________________________________________
- #define SND_PCM_RINFO_BATCH 0x00000001
- #define SND_PCM_RINFO_8BITONLY 0x00000002
- #define SND_PCM_RINFO_16BITONLY 0x00000004
-
- struct snd_pcm_record_info {
- unsigned int flags; /* see to SND_PCM_RINFO_XXXX */
- unsigned int formats; /* supported formats */
- unsigned int min_rate; /* min rate (in Hz) */
- unsigned int max_rate; /* max rate (in Hz) */
- unsigned int min_channels; /* min channels (probably always 1) */
- unsigned int max_channels; /* max channels */
- unsigned int buffer_size; /* record buffer size */
- unsigned int min_fragment_size; /* min fragment size in bytes */
- unsigned int max_fragment_size; /* max fragment size in bytes */
- unsigned int fragment_align; /* align fragment value */
- unsigned char reserved[64]; /* reserved for future... */
- };
-
- ______________________________________________________________________
-
- S\bSN\bND\bD_\b_P\bPC\bCM\bM_\b_P\bPI\bIN\bNF\bFO\bO_\b_B\bBA\bAT\bTC\bCH\bH
- Driver implements buffering for this device. This means that the
- chip used for data processing has its own memory and output
- should be more delayed than if a traditional codec chip is used.
-
- S\bSN\bND\bD_\b_P\bPC\bCM\bM_\b_P\bPI\bIN\bNF\bFO\bO_\b_8\b8B\bBI\bIT\bTO\bON\bNL\bLY\bY
- If this bit is set, the device uses 8-bit format for 16-bit
- samples and does software conversion. This bit is set on broken
- SoundBlaster 16/AWE soundcards which can't do full 16-bit
- duplex. If this bit is set the application or highter digital
- audio layer should do conversion from 16-bit samples to 8-bit
- samples rather than making the driver to do it in the kernel.
-
- S\bSN\bND\bD_\b_P\bPC\bCM\bM_\b_P\bPI\bIN\bNF\bFO\bO_\b_1\b16\b6B\bBI\bIT\bTO\bON\bNL\bLY\bY
- If this bit is set, the device uses a 16-bit format for 8-bit
- samples and does software conversion. This bit is set on broken
- SoundBlaster 16/AWE soundcards which can't do full 8-bit duplex.
- If this bit is set the application or highter digital audio
- layer should do the conversion from 8-bit samples to 16-bit
- samples rather than making the driver to do it in the kernel.
-
- 5\b5.\b.1\b1.\b.8\b8.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_p\bpl\bla\bay\byb\bba\bac\bck\bk_\b_f\bfo\bor\brm\bma\bat\bt(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_f\bfo\bor\brm\bma\bat\bt_\b_t\bt *\b*f\bfo\bor\brm\bma\bat\bt )\b)
-
- Sets up format, rate (in Hz) and number of channels for playback, in
- the desired direction. Function returns zero if successful, otherwise
- it returns an error code.
-
- ______________________________________________________________________
- struct snd_pcm_format {
- unsigned int format; /* SND_PCM_SFMT_XXXX */
- unsigned int rate; /* rate in Hz */
- unsigned int channels; /* channels (voices) */
- unsigned char reserved[16];
- };
-
- ______________________________________________________________________
-
- 5\b5.\b.1\b1.\b.9\b9.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_r\bre\bec\bco\bor\brd\bd_\b_f\bfo\bor\brm\bma\bat\bt(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_f\bfo\bor\brm\bma\bat\bt_\b_t\bt *\b*f\bfo\bor\brm\bma\bat\bt )\b)
-
- Sets up format, rate (in Hz) and number of channels for used for
- recording in the specified direction. Function returns zero if
- successful, otherwise it returns an error code.
-
- ______________________________________________________________________
- struct snd_pcm_format {
- unsigned int format; /* SND_PCM_SFMT_XXXX */
- unsigned int rate; /* rate in Hz */
- unsigned int channels; /* channels (voices) */
- unsigned char reserved[16];
- };
-
- ______________________________________________________________________
-
- 5\b5.\b.1\b1.\b.1\b10\b0.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_p\bpl\bla\bay\byb\bba\bac\bck\bk_\b_p\bpa\bar\bra\bam\bms\bs(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_p\bpl\bla\bay\byb\bba\bac\bck\bk_\b_p\bpa\bar\bra\bam\bms\bs_\b_t\bt
- *\b*p\bpa\bar\bra\bam\bms\bs )\b)
-
- Sets various parameters for playback direction. Function returns zero
- if successful, otherwise it returns an error code.
-
- ______________________________________________________________________
- struct snd_pcm_playback_params {
- int fragment_size;
- int fragments_max;
- int fragments_room;
- unsigned char reserved[16]; /* must be filled with zero */
- };
-
- ______________________________________________________________________
-
- f\bfr\bra\bag\bgm\bme\ben\bnt\bt_\b_s\bsi\biz\bze\be
- Requested size of fragment. This value should be aligned for
- current format (for example to 4 if stereo 16-bit samples are
- used) or with the _\bf_\br_\ba_\bg_\bm_\be_\bn_\bt_\b__\ba_\bl_\bi_\bg_\bn variable from
- _\bs_\bn_\bd_\b__\bp_\bc_\bm_\b__\bp_\bl_\ba_\by_\bb_\ba_\bc_\bk_\b__\bi_\bn_\bf_\bo_\b__\bt structure. Its range can be from
- _\bm_\bi_\bn_\b__\bf_\br_\ba_\bg_\bm_\be_\bn_\bt_\b__\bs_\bi_\bz_\be to _\bm_\ba_\bx_\b__\bf_\br_\ba_\bg_\bm_\be_\bn_\bt_\b__\bs_\bi_\bz_\be.
-
- f\bfr\bra\bag\bgm\bme\ben\bnt\bts\bs_\b_m\bma\bax\bx
- Maximum number of fragments in queue for wakeup. This number
- doesn't counts partly used fragment. If current count of filled
- playback fragments is greater than this value driver block
- application or return immediately back if nonblock mode is
- active.
-
- f\bfr\bra\bag\bgm\bme\ben\bnt\bts\bs_\b_r\bro\boo\bom\bm
- Minumum number of fragments writeable for wakeup. This value
- should be in most cases 1 which means return back to application
- if at least one fragment is free for playback. This value
- includes partly used fragments, too.
-
- 5\b5.\b.1\b1.\b.1\b11\b1.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_r\bre\bec\bco\bor\brd\bd_\b_p\bpa\bar\bra\bam\bms\bs(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_r\bre\bec\bco\bor\brd\bd_\b_p\bpa\bar\bra\bam\bms\bs_\b_t\bt
- *\b*p\bpa\bar\bra\bam\bms\bs )\b)
- Function sets various parameters for the recording direction. Function
- returns zero if successful, otherwise it returns an error code.
-
- ______________________________________________________________________
- struct snd_pcm_record_params {
- int fragment_size;
- int fragments_min;
- unsigned char reserved[16];
- };
-
- ______________________________________________________________________
-
- f\bfr\bra\bag\bgm\bme\ben\bnt\bt_\b_s\bsi\biz\bze\be
- Requested size of fragment. This value should be aligned for
- current format (for example to 4 if stereo 16-bit samples are
- used) or set to the _\bf_\br_\ba_\bg_\bm_\be_\bn_\bt_\b__\ba_\bl_\bi_\bg_\bn variable from
- _\bs_\bn_\bd_\b__\bp_\bc_\bm_\b__\bp_\bl_\ba_\by_\bb_\ba_\bc_\bk_\b__\bi_\bn_\bf_\bo_\b__\bt structure. Its range can be from
- _\bm_\bi_\bn_\b__\bf_\br_\ba_\bg_\bm_\be_\bn_\bt_\b__\bs_\bi_\bz_\be to _\bm_\ba_\bx_\b__\bf_\br_\ba_\bg_\bm_\be_\bn_\bt_\b__\bs_\bi_\bz_\be.
-
- f\bfr\bra\bag\bgm\bme\ben\bnt\bts\bs_\b_m\bmi\bin\bn
- Minimum filled fragments for wakeup. Driver blocks the
- application (if block mode is selected) until it isn't filled
- with number of fragments specified with this value.
-
- 5\b5.\b.1\b1.\b.1\b12\b2.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_p\bpl\bla\bay\byb\bba\bac\bck\bk_\b_s\bst\bta\bat\btu\bus\bs(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_p\bpl\bla\bay\byb\bba\bac\bck\bk_\b_s\bst\bta\bat\btu\bus\bs_\b_t\bt
- *\b*s\bst\bta\bat\btu\bus\bs )\b)
-
- Fills the *status structure. Function returns zero if successful,
- otherwise it returns an error code.
-
- ______________________________________________________________________
- struct snd_pcm_playback_status {
- unsigned int rate;
- int fragments;
- int fragment_size;
- int count;
- int queue;
- int underrun;
- struct timeval time;
- struct timeval stime;
- unsigned char reserved[16];
- };
-
- ______________________________________________________________________
-
- r\bra\bat\bte\be
- Real playback rate. This value reflects hardware limitations.
-
- f\bfr\bra\bag\bgm\bme\ben\bnt\bts\bs
- Currently allocated fragments by the driver for playback
- direction.
-
- f\bfr\bra\bag\bgm\bme\ben\bnt\bt_\b_s\bsi\biz\bze\be
- Current fragment size used by driver for the playback direction.
-
- c\bco\bou\bun\bnt\bt
- Count of bytes writeable without blocking.
-
- q\bqu\bue\beu\bue\be
- Count of bytes in queue. Note: _\b(_\bf_\br_\ba_\bg_\bm_\be_\bn_\bt_\bs _\b* _\bf_\br_\ba_\bg_\bm_\be_\bn_\bt_\b__\bs_\bi_\bz_\be_\b) _\b-
- _\bq_\bu_\be_\bu_\be should not be equal to _\bc_\bo_\bu_\bn_\bt.
-
- u\bun\bnd\bde\ber\brr\bru\bun\bn
- This value tells the application the number of underruns since
- the ast call of _\bs_\bn_\bd_\b__\bp_\bc_\bm_\b__\bp_\bl_\ba_\by_\bb_\ba_\bc_\bk_\b__\bs_\bt_\ba_\bt_\bu_\bs.
-
- t\bti\bim\bme\be
- Delay till played of the first sample from next write. This
- value should be used for time synchronization. Returned value is
- in the same format as returned from the standard C function
- _\bg_\be_\bt_\bt_\bi_\bm_\be_\bo_\bf_\bd_\ba_\by_\b( _\b&_\bt_\bi_\bm_\be_\b, _\bN_\bU_\bL_\bL _\b). This variable contains right value
- only if playback time mode is enabled (look to
- _\bs_\bn_\bd_\b__\bp_\bc_\bm_\b__\bp_\bl_\ba_\by_\bb_\ba_\bc_\bk_\b__\bt_\bi_\bm_\be function).
-
- s\bst\bti\bim\bme\be
- Time when playback was started. This variable contains right
- value only if playback time mode is enabled (look to
- _\bs_\bn_\bd_\b__\bp_\bc_\bm_\b__\bp_\bl_\ba_\by_\bb_\ba_\bc_\bk_\b__\bt_\bi_\bm_\be function).
-
- 5\b5.\b.1\b1.\b.1\b13\b3.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_r\bre\bec\bco\bor\brd\bd_\b_s\bst\bta\bat\btu\bus\bs(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_r\bre\bec\bco\bor\brd\bd_\b_s\bst\bta\bat\btu\bus\bs_\b_t\bt *\b*s\bst\bta\ba-\b-
- t\btu\bus\bs )\b)
-
- Fills the *status structure. Function returns zero if successful,
- otherwise it returns an error code.
-
- ______________________________________________________________________
- struct snd_pcm_record_status {
- unsigned int rate;
- int fragments;
- int fragment_size;
- int count;
- int free;
- int overrun;
- struct timeval time;
- unsigned char reserved[16];
- };
-
- ______________________________________________________________________
-
- r\bra\bat\bte\be
- Real record rate. This value reflects hardware limitations.
-
- f\bfr\bra\bag\bgm\bme\ben\bnt\bts\bs
- Currently allocated fragments by driver for the record
- direction.
-
- f\bfr\bra\bag\bgm\bme\ben\bnt\bt_\b_s\bsi\biz\bze\be
- Current fragment size used by driver for the record direction.
-
- c\bco\bou\bun\bnt\bt
- Count of bytes readable without blocking.
-
- f\bfr\bre\bee\be
- Count of bytes in buffer still free. Note: _\b(_\bf_\br_\ba_\bg_\bm_\be_\bn_\bt_\bs _\b*
- _\bf_\br_\ba_\bg_\bm_\be_\bn_\bt_\b__\bs_\bi_\bz_\be_\b) _\b- _\bf_\br_\be_\be should not be equal to _\bc_\bo_\bu_\bn_\bt.
-
- o\bov\bve\ber\brr\bru\bun\bn
- This value tells application the count of overruns since the
- last call to _\bs_\bn_\bd_\b__\bp_\bc_\bm_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bs_\bt_\ba_\bt_\bu_\bs.
- t\bti\bim\bme\be
- Lag since the next sample read was recorded. This value should
- be used for time synchronization. Returned value is in the same
- format as returned by the from standard C function _\bg_\be_\bt_\bt_\bi_\bm_\be_\bo_\bf_\bd_\ba_\by_\b(
- _\b&_\bt_\bi_\bm_\be_\b, _\bN_\bU_\bL_\bL _\b). This variable contains right value only if record
- time mode is enabled (look to _\bs_\bn_\bd_\b__\bp_\bc_\bm_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bt_\bi_\bm_\be function).
-
- s\bst\bti\bim\bme\be
- Time when record was started. This variable contains right value
- only if record time mode is enabled (look to _\bs_\bn_\bd_\b__\bp_\bc_\bm_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bt_\bi_\bm_\be
- function).
-
- 5\b5.\b.1\b1.\b.1\b14\b4.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_d\bdr\bra\bai\bin\bn_\b_p\bpl\bla\bay\byb\bba\bac\bck\bk(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be )\b)
-
- This function drain playback buffers immediately. Function returns
- zero if successful, otherwise it returns an error code.
-
- 5\b5.\b.1\b1.\b.1\b15\b5.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_f\bfl\blu\bus\bsh\bh_\b_p\bpl\bla\bay\byb\bba\bac\bck\bk(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be )\b)
-
- This function flushes the playback buffers. It blocks the program
- while the all the waiting samples in kernel playback buffers are
- processed. Function returns zero if successful, otherwise it returns
- an error code.
-
- 5\b5.\b.1\b1.\b.1\b16\b6.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_f\bfl\blu\bus\bsh\bh_\b_r\bre\bec\bco\bor\brd\bd(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be )\b)
-
- This function flushes (destroyes) record buffers. Function returns
- zero if successful, otherwise it returns an error code.
-
- 5\b5.\b.1\b1.\b.1\b17\b7.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_p\bpl\bla\bay\byb\bba\bac\bck\bk_\b_t\bti\bim\bme\be(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, i\bin\bnt\bt e\ben\bna\bab\bbl\ble\be )\b)
-
- This function enables or disables time mode for playback direction.
- Time mode allows to application better time synchronization. Function
- returns zero if successful, otherwise it returns an error code.
-
- 5\b5.\b.1\b1.\b.1\b18\b8.\b.
-
- i\bin\bnt\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_r\bre\bec\bco\bor\brd\bd_\b_t\bti\bim\bme\be(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, i\bin\bnt\bt e\ben\bna\bab\bbl\ble\be )\b)
-
- This function enables or disables time mode for record direction. Time
- mode allows to application better time synchronization. Function
- returns zero if successful, otherwise it returns an error code.
-
- 5\b5.\b.1\b1.\b.1\b19\b9.\b.
-
- s\bss\bsi\biz\bze\be_\b_t\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_w\bwr\bri\bit\bte\be(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, c\bco\bon\bns\bst\bt v\bvo\boi\bid\bd *\b*b\bbu\buf\bff\bfe\ber\br,\b, s\bsi\biz\bze\be_\b_t\bt s\bsi\biz\bze\be )\b)
-
- Writes samples to the device which must be in the proper format
- specified by the _\bs_\bn_\bd_\b__\bp_\bc_\bm_\b__\bp_\bl_\ba_\by_\bb_\ba_\bc_\bk_\b__\bf_\bo_\br_\bm_\ba_\bt function. Function returns
- zero or positive value if playback was successful (value represents
- count of bytes which was successfuly written to device) or an error
- value if error occured. Function should suspend process if block mode
- is active.
-
- 5\b5.\b.1\b1.\b.2\b20\b0.\b.
-
- s\bss\bsi\biz\bze\be_\b_t\bt s\bsn\bnd\bd_\b_p\bpc\bcm\bm_\b_r\bre\bea\bad\bd(\b( v\bvo\boi\bid\bd *\b*h\bha\ban\bnd\bdl\ble\be,\b, v\bvo\boi\bid\bd *\b*b\bbu\buf\bff\bfe\ber\br,\b, s\bsi\biz\bze\be_\b_t\bt s\bsi\biz\bze\be )\b)
-
- Function reads samples from driver. Samples are in format specified by
- _\bs_\bn_\bd_\b__\bp_\bc_\bm_\b__\br_\be_\bc_\bo_\br_\bd_\b__\bf_\bo_\br_\bm_\ba_\bt function. Function returns zero or positive
- value if record was success (value represents count of bytes which was
- successfuly read from device) or negative error value if error
- occured. Function should suspend process if block mode is active.
-
- 5\b5.\b.2\b2.\b. E\bEx\bxa\bam\bmp\bpl\ble\bes\bs
-
- The following example shows how to play the first 512kB from the
- /tmp/test.au file with soundcard #0 and PCM device #0:
-
- ______________________________________________________________________
- int card = 0, device = 0, err, fd, count, size, idx;
- void *handle;
- snd_pcm_format_t format;
- char *buffer;
-
- buffer = (char *)malloc( 512 * 1024 );
- if ( !buffer ) return;
- if ( (err = snd_pcm_open( &handle, card, device, SND_PCM_OPEN_PLAYBACK )) < 0 ) {
- fprintf( stderr, "open failed: %s\n", snd_strerror( err ) );
- return;
- }
- format.format = SND_PCM_SFMT_MU_LAW;
- format.rate = 8000;
- format.channels = 1;
- if ( (err = snd_pcm_playback_format( handle, &format )) < 0 ) {
- fprintf( stderr, "format setup failed: %s\n", snd_strerror( err ) );
- snd_pcm_close( handle );
- return;
- }
- fd = open( "/tmp/test.au", O_RDONLY );
- if ( fd < 0 ) {
- perror( "open file" );
- snd_pcm_close( handle );
- return;
- }
- idx = 0;
- count = read( fd, buffer, 512 * 1024 );
- if ( count <= 0 ) {
- perror( "read from file" );
- snd_pcm_close( handle );
- return;
- }
- close( fd );
- if ( !memcmp( buffer, ".snd", 4 ) ) {
- idx = (buffer[4]<<24)|(buffer[5]<<16)|(buffer[6]<<8)|(buffer[7]);
- if ( idx > 128 ) idx = 128;
- if ( idx > count ) idx = count;
- }
- size = snd_pcm_write( handle, &buffer[ idx ], count - idx );
- printf( "Bytes written %i from %i...\n", size, count - idx );
- snd_pcm_close( handle );
- free( buffer );
- ______________________________________________________________________
-
git://git.alsa-project.org / alsa-lib.git / commitdiff
