From 43956de710b4ea3187dab52963e69ec7ea97b62d Mon Sep 17 00:00:00 2001 From: Andrew Eikum Date: Thu, 19 Jan 2012 12:36:39 +0100 Subject: [PATCH] Improve hw_params documentation Signed-off-by: Takashi Iwai --- include/pcm.h | 17 ++++++++++++++++- src/pcm/pcm.c | 10 +++++++++- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/include/pcm.h b/include/pcm.h index be355a91..49975570 100644 --- a/include/pcm.h +++ b/include/pcm.h @@ -44,8 +44,23 @@ extern "C" { /** PCM generic info container */ typedef struct _snd_pcm_info snd_pcm_info_t; -/** PCM hardware configuration space container */ + +/** PCM hardware configuration space container + * + * snd_pcm_hw_params_t is an opaque structure which contains a set of possible + * PCM hardware configurations. For example, a given instance might include a + * range of buffer sizes, a range of period sizes, and a set of several sample + * formats. Some subset of all possible combinations these sets may be valid, + * but not necessarily any combination will be valid. + * + * When a parameter is set or restricted using a snd_pcm_hw_params_set* + * function, all of the other ranges will be updated to exclude as many + * impossible configurations as possible. Attempting to set a parameter + * outside of its acceptable range will result in the function failing + * and an error code being returned. + */ typedef struct _snd_pcm_hw_params snd_pcm_hw_params_t; + /** PCM software configuration container */ typedef struct _snd_pcm_sw_params snd_pcm_sw_params_t; /** PCM status container */ diff --git a/src/pcm/pcm.c b/src/pcm/pcm.c index dc91f79f..ea1afdcb 100644 --- a/src/pcm/pcm.c +++ b/src/pcm/pcm.c @@ -809,7 +809,9 @@ int snd_pcm_hw_params_current(snd_pcm_t *pcm, snd_pcm_hw_params_t *params) * * The configuration is chosen fixing single parameters in this order: * first access, first format, first subformat, min channels, min rate, - * min period time, max buffer size, min tick time + * min period time, max buffer size, min tick time. If no mutually + * compatible set of parameters can be chosen, a negative error code + * will be returned. * * After this call, #snd_pcm_prepare() is called automatically and * the stream is brought to \c #SND_PCM_STATE_PREPARED state. @@ -817,6 +819,9 @@ int snd_pcm_hw_params_current(snd_pcm_t *pcm, snd_pcm_hw_params_t *params) * The hardware parameters cannot be changed when the stream is * running (active). The software parameters can be changed * at any time. + * + * The configuration space will be updated to reflect the chosen + * parameters. */ int snd_pcm_hw_params(snd_pcm_t *pcm, snd_pcm_hw_params_t *params) { @@ -3183,6 +3188,9 @@ int snd_pcm_hw_params_get_fifo_size(const snd_pcm_hw_params_t *params) * \brief Fill params with a full configuration space for a PCM * \param pcm PCM handle * \param params Configuration space + * + * The configuration space will be filled with all possible ranges + * for the PCM device. */ int snd_pcm_hw_params_any(snd_pcm_t *pcm, snd_pcm_hw_params_t *params) { -- 2.47.1