From: Jaroslav Kysela Date: Tue, 22 Jan 2002 14:27:25 +0000 (+0000) Subject: Added description of shm, null and rate plugins X-Git-Tag: v1.0.3~495 X-Git-Url: https://git.alsa-project.org/?a=commitdiff_plain;h=2cc79806a2b0a90a5bf911319777b5b690fec53b;p=alsa-lib.git Added description of shm, null and rate plugins --- diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg index 68f7f851..beefe036 100644 --- a/doc/doxygen.cfg +++ b/doc/doxygen.cfg @@ -38,6 +38,8 @@ INPUT = index.doxygen \ ../src/pcm/pcm_mmap.c \ ../src/pcm/pcm_plugin.c \ ../src/pcm/pcm_hw.c \ + ../src/pcm/pcm_shm.c \ + ../src/pcm/pcm_null.c \ ../src/pcm/pcm_copy.c \ ../src/pcm/pcm_linear.c \ ../src/pcm/pcm_lfloat.c \ @@ -45,6 +47,7 @@ INPUT = index.doxygen \ ../src/pcm/pcm_alaw.c \ ../src/pcm/pcm_adpcm.c \ ../src/pcm/pcm_route.c \ + ../src/pcm/pcm_rate.c \ ../src/pcm/pcm_plug.c \ ../src/pcm/pcm_file.c \ ../src/pcm/pcm_multi.c \ diff --git a/src/pcm/pcm_hw.c b/src/pcm/pcm_hw.c index 17396e66..5669f5f7 100644 --- a/src/pcm/pcm_hw.c +++ b/src/pcm/pcm_hw.c @@ -827,7 +827,7 @@ int snd_pcm_hw_open(snd_pcm_t **pcmp, const char *name, This plugin communicates directly with the ALSA kernel driver. It is a raw communication without any conversions. The emulation of mmap access can be -optionally enabled, but expect a worse latency in the case. +optionally enabled, but expect worse latency in the case. \code pcm.name { diff --git a/src/pcm/pcm_ladspa.c b/src/pcm/pcm_ladspa.c index 03ca654c..6e15ea3b 100644 --- a/src/pcm/pcm_ladspa.c +++ b/src/pcm/pcm_ladspa.c @@ -1185,6 +1185,11 @@ This plugin allows to apply a set of LADPSA plugins. The input and output format is always #SND_PCM_FORMAT_FLOAT (note: this type can be either little or big-endian depending on architecture). +The policy duplicate means that there must be only one binding definition for +channel zero. This definition is automatically duplicated for all channels. + +Instances of LADSPA plugins are created dynamically. + \code pcm.name { type ladspa # ALSA<->LADSPA PCM @@ -1195,15 +1200,15 @@ pcm.name { # or pcm { } # Slave PCM definition } - path STR # Path (directory) with LADSPA plugins + [path STR] # Path (directory) with LADSPA plugins plugins | # Definition for both directions playback_plugins | # Definition for playback direction capture_plugins { # Definition for capture direction N { # Configuration for LADPSA plugin N - id INT # LADSPA plugin ID (for example 1043) - label STR # LADSPA plugin label (for example 'delay_5s') - filename STR # Full filename of .so library with LADSPA plugin code - policy STR # Policy can be 'none' or 'duplicate' + [id INT] # LADSPA plugin ID (for example 1043) + [label STR] # LADSPA plugin label (for example 'delay_5s') + [filename STR] # Full filename of .so library with LADSPA plugin code + [policy STR] # Policy can be 'none' or 'duplicate' input | output { bindings { C INT or STR # C - channel, INT - audio port index, STR - audio port name diff --git a/src/pcm/pcm_null.c b/src/pcm/pcm_null.c index f7944b14..8c96213c 100644 --- a/src/pcm/pcm_null.c +++ b/src/pcm/pcm_null.c @@ -1,3 +1,10 @@ +/** + * \file pcm/pcm_null.c + * \ingroup PCM_Plugins + * \brief PCM Null Plugin Interface + * \author Abramo Bagnara + * \date 2000-2001 + */ /* * PCM - Null plugin * Copyright (c) 2000 by Abramo Bagnara @@ -30,6 +37,7 @@ const char *_snd_module_pcm_null = ""; #endif +#ifndef DOC_HIDDEN typedef struct { snd_timestamp_t trigger_tstamp; snd_pcm_state_t state; @@ -38,6 +46,7 @@ typedef struct { snd_pcm_uframes_t hw_ptr; int poll_fd; } snd_pcm_null_t; +#endif static int snd_pcm_null_close(snd_pcm_t *pcm) { @@ -295,7 +304,7 @@ static void snd_pcm_null_dump(snd_pcm_t *pcm, snd_output_t *out) } } -snd_pcm_ops_t snd_pcm_null_ops = { +static snd_pcm_ops_t snd_pcm_null_ops = { close: snd_pcm_null_close, info: snd_pcm_null_info, hw_refine: snd_pcm_null_hw_refine, @@ -310,7 +319,7 @@ snd_pcm_ops_t snd_pcm_null_ops = { munmap: snd_pcm_null_munmap, }; -snd_pcm_fast_ops_t snd_pcm_null_fast_ops = { +static snd_pcm_fast_ops_t snd_pcm_null_fast_ops = { status: snd_pcm_null_status, state: snd_pcm_null_state, delay: snd_pcm_null_delay, @@ -330,6 +339,17 @@ snd_pcm_fast_ops_t snd_pcm_null_fast_ops = { mmap_commit: snd_pcm_null_mmap_commit, }; +/** + * \brief Creates a new null PCM + * \param pcmp Returns created PCM handle + * \param name Name of PCM + * \param stream Stream type + * \param mode Stream mode + * \retval zero on success otherwise a negative error code + * \warning Using of this function might be dangerous in the sense + * of compatibility reasons. The prototype might be freely + * changed in future. + */ int snd_pcm_null_open(snd_pcm_t **pcmp, const char *name, snd_pcm_stream_t stream, int mode) { snd_pcm_t *pcm; @@ -375,6 +395,44 @@ int snd_pcm_null_open(snd_pcm_t **pcmp, const char *name, snd_pcm_stream_t strea return 0; } +/*! \page pcm_plugins + +\section pcm_plugins_null Plugin: Null + +This plugin discards contents of a PCM stream or creates a stream with zero +samples. + +Note: This implementation uses devices /dev/null (playback, must be writeable) +and /dev/full (capture, must be readable). + +\code +pcm.name { + type null # Null PCM +} +\endcode + +\subsection pcm_plugins_null_funcref Function reference + +
    +
  • snd_pcm_null_open() +
  • _snd_pcm_null_open() +
+ +*/ + +/** + * \brief Creates a new Null PCM + * \param pcmp Returns created PCM handle + * \param name Name of PCM + * \param root Root configuration node + * \param conf Configuration node with Null PCM description + * \param stream Stream type + * \param mode Stream mode + * \retval zero on success otherwise a negative error code + * \warning Using of this function might be dangerous in the sense + * of compatibility reasons. The prototype might be freely + * changed in future. + */ int _snd_pcm_null_open(snd_pcm_t **pcmp, const char *name, snd_config_t *conf, snd_pcm_stream_t stream, int mode) @@ -392,4 +450,6 @@ int _snd_pcm_null_open(snd_pcm_t **pcmp, const char *name, } return snd_pcm_null_open(pcmp, name, stream, mode); } +#ifndef DOC_HIDDEN SND_DLSYM_BUILD_VERSION(_snd_pcm_null_open, SND_PCM_DLSYM_VERSION); +#endif diff --git a/src/pcm/pcm_rate.c b/src/pcm/pcm_rate.c index 3d817bc1..30355b4a 100644 --- a/src/pcm/pcm_rate.c +++ b/src/pcm/pcm_rate.c @@ -1,3 +1,10 @@ +/** + * \file pcm/pcm_rate.c + * \ingroup PCM_Plugins + * \brief PCM Rate Plugin Interface + * \author Abramo Bagnara + * \date 2000-2001 + */ /* * PCM - Rate conversion * Copyright (c) 2000 by Abramo Bagnara @@ -29,6 +36,8 @@ const char *_snd_module_pcm_rate = ""; #endif +#ifndef DOC_HIDDEN + #define DIV (1<<16) typedef struct { @@ -212,6 +221,8 @@ static snd_pcm_uframes_t snd_pcm_rate_shrink(const snd_pcm_channel_area_t *dst_a return src_frames1; } +#endif /* DOC_HIDDEN */ + static int snd_pcm_rate_hw_refine_cprepare(snd_pcm_t *pcm ATTRIBUTE_UNUSED, snd_pcm_hw_params_t *params) { int err; @@ -479,7 +490,7 @@ static void snd_pcm_rate_dump(snd_pcm_t *pcm, snd_output_t *out) snd_pcm_dump(rate->plug.slave, out); } -snd_pcm_ops_t snd_pcm_rate_ops = { +static snd_pcm_ops_t snd_pcm_rate_ops = { close: snd_pcm_plugin_close, info: snd_pcm_plugin_info, hw_refine: snd_pcm_rate_hw_refine, @@ -494,6 +505,20 @@ snd_pcm_ops_t snd_pcm_rate_ops = { munmap: snd_pcm_plugin_munmap, }; + +/** + * \brief Creates a new rate PCM + * \param pcmp Returns created PCM handle + * \param name Name of PCM + * \param sformat Slave format + * \param srate Slave rate + * \param slave Slave PCM handle + * \param close_slave When set, the slave PCM handle is closed with copy PCM + * \retval zero on success otherwise a negative error code + * \warning Using of this function might be dangerous in the sense + * of compatibility reasons. The prototype might be freely + * changed in future. + */ int snd_pcm_rate_open(snd_pcm_t **pcmp, const char *name, snd_pcm_format_t sformat, unsigned int srate, snd_pcm_t *slave, int close_slave) { snd_pcm_t *pcm; @@ -533,6 +558,47 @@ int snd_pcm_rate_open(snd_pcm_t **pcmp, const char *name, snd_pcm_format_t sform return 0; } +/*! \page pcm_plugins + +\section pcm_plugins_rate Plugin: Rate + +This plugin converts a stream rate. The input and output formats must be linear. + +\code +pcm.name { + type rate # Rate PCM + slave STR # Slave name + # or + slave { # Slave definition + pcm STR # Slave PCM name + # or + pcm { } # Slave PCM definition + } +} +\endcode + +\subsection pcm_plugins_rate_funcref Function reference + +
    +
  • snd_pcm_rate_open() +
  • _snd_pcm_rate_open() +
+ +*/ + +/** + * \brief Creates a new rate PCM + * \param pcmp Returns created PCM handle + * \param name Name of PCM + * \param root Root configuration node + * \param conf Configuration node with rate PCM description + * \param stream Stream type + * \param mode Stream mode + * \retval zero on success otherwise a negative error code + * \warning Using of this function might be dangerous in the sense + * of compatibility reasons. The prototype might be freely + * changed in future. + */ int _snd_pcm_rate_open(snd_pcm_t **pcmp, const char *name, snd_config_t *root, snd_config_t *conf, snd_pcm_stream_t stream, int mode) @@ -582,4 +648,6 @@ int _snd_pcm_rate_open(snd_pcm_t **pcmp, const char *name, snd_pcm_close(spcm); return err; } +#ifndef DOC_HIDDEN SND_DLSYM_BUILD_VERSION(_snd_pcm_rate_open, SND_PCM_DLSYM_VERSION); +#endif diff --git a/src/pcm/pcm_shm.c b/src/pcm/pcm_shm.c index 1c03ae2d..c2a8a923 100644 --- a/src/pcm/pcm_shm.c +++ b/src/pcm/pcm_shm.c @@ -1,5 +1,12 @@ +/** + * \file pcm/pcm_shm.c + * \ingroup PCM_Plugins + * \brief PCM Shared Memory Plugin Interface + * \author Abramo Bagnara + * \date 2000-2001 + */ /* - * PCM - SHM Client + * PCM - Shared Memory Client * Copyright (c) 2000 by Abramo Bagnara * * @@ -43,11 +50,14 @@ const char *_snd_module_pcm_shm = ""; #endif +#ifndef DOC_HIDDEN typedef struct { int socket; volatile snd_pcm_shm_ctrl_t *ctrl; } snd_pcm_shm_t; +#endif +#ifndef DOC_HIDDEN int receive_fd(int sock, void *data, size_t len, int *fd) { int ret; @@ -81,6 +91,7 @@ int receive_fd(int sock, void *data, size_t len, int *fd) *fd = *fds; return ret; } +#endif static int snd_pcm_shm_action(snd_pcm_t *pcm) { @@ -493,7 +504,7 @@ static void snd_pcm_shm_dump(snd_pcm_t *pcm, snd_output_t *out) } } -snd_pcm_ops_t snd_pcm_shm_ops = { +static snd_pcm_ops_t snd_pcm_shm_ops = { close: snd_pcm_shm_close, info: snd_pcm_shm_info, hw_refine: snd_pcm_shm_hw_refine, @@ -508,7 +519,7 @@ snd_pcm_ops_t snd_pcm_shm_ops = { munmap: snd_pcm_shm_munmap, }; -snd_pcm_fast_ops_t snd_pcm_shm_fast_ops = { +static snd_pcm_fast_ops_t snd_pcm_shm_fast_ops = { status: snd_pcm_shm_status, state: snd_pcm_shm_state, delay: snd_pcm_shm_delay, @@ -578,7 +589,22 @@ static int make_inet_socket(const char *host, int port) } #endif -int snd_pcm_shm_open(snd_pcm_t **pcmp, const char *name, const char *sockname, const char *sname, snd_pcm_stream_t stream, int mode) +/** + * \brief Creates a new shared memory PCM + * \param pcmp Returns created PCM handle + * \param name Name of PCM + * \param sockname Unix socket name + * \param sname Server name + * \param stream PCM Stream + * \param mode PCM Mode + * \retval zero on success otherwise a negative error code + * \warning Using of this function might be dangerous in the sense + * of compatibility reasons. The prototype might be freely + * changed in future. + */ +int snd_pcm_shm_open(snd_pcm_t **pcmp, const char *name, + const char *sockname, const char *sname, + snd_pcm_stream_t stream, int mode) { snd_pcm_t *pcm; snd_pcm_shm_t *shm = NULL; @@ -679,6 +705,7 @@ int snd_pcm_shm_open(snd_pcm_t **pcmp, const char *name, const char *sockname, c return result; } +#ifndef DOC_HIDDEN int is_local(struct hostent *hent) { int s; @@ -723,7 +750,45 @@ int is_local(struct hostent *hent) free(conf.ifc_buf); return i < numreqs; } +#endif + +/*! \page pcm_plugins + +\section pcm_plugins_shm Plugin: shm + +This plugin communicates with aserver via shared memory. It is a raw +communication without any conversions, but it can be expected worse +performance. +\code +pcm.name { + type shm # Shared memory PCM + server STR # Server name + pcm STR # PCM name +} +\endcode + +\subsection pcm_plugins_shm_funcref Function reference + +
    +
  • snd_pcm_shm_open() +
  • _snd_pcm_shm_open() +
+ +*/ + +/** + * \brief Creates a new shm PCM + * \param pcmp Returns created PCM handle + * \param name Name of PCM + * \param root Root configuration node + * \param conf Configuration node with hw PCM description + * \param stream PCM Stream + * \param mode PCM Mode + * \warning Using of this function might be dangerous in the sense + * of compatibility reasons. The prototype might be freely + * changed in future. + */ int _snd_pcm_shm_open(snd_pcm_t **pcmp, const char *name, snd_config_t *root, snd_config_t *conf, snd_pcm_stream_t stream, int mode) @@ -841,4 +906,6 @@ int _snd_pcm_shm_open(snd_pcm_t **pcmp, const char *name, snd_config_delete(sconfig); return err; } +#ifndef DOC_HIDDEN SND_DLSYM_BUILD_VERSION(_snd_pcm_shm_open, SND_PCM_DLSYM_VERSION); +#endif