All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH 2/2] Improve hw_params documentation
@ 2011-11-16 19:56 Andrew Eikum
  2011-11-16 21:20 ` Clemens Ladisch
  0 siblings, 1 reply; 11+ messages in thread
From: Andrew Eikum @ 2011-11-16 19:56 UTC (permalink / raw)
  To: alsa-devel

[-- Attachment #1: Type: text/plain, Size: 126 bytes --]

---
 include/pcm.h |   14 +++++++++++++-
 src/pcm/pcm.c |   10 +++++++++-
 2 files changed, 22 insertions(+), 2 deletions(-)


[-- Attachment #2: 0002-Improve-hw_params-documentation.patch --]
[-- Type: text/x-patch, Size: 2696 bytes --]

diff --git a/include/pcm.h b/include/pcm.h
index be355a9..961c6a0 100644
--- a/include/pcm.h
+++ b/include/pcm.h
@@ -44,8 +44,20 @@ 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.
+ *
+ *  No validation is done by the various snd_pcm_hw_params_set* functions.
+ *  Instead, #snd_pcm_hw_params will return an error code if the requested
+ *  set of parameters can't be resolved to a single valid configuration. */
 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 dc91f79..ea1afdc 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)
 {

[-- Attachment #3: Type: text/plain, Size: 0 bytes --]



^ permalink raw reply related	[flat|nested] 11+ messages in thread

end of thread, other threads:[~2011-11-22 23:57 UTC | newest]

Thread overview: 11+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2011-11-16 19:56 [PATCH 2/2] Improve hw_params documentation Andrew Eikum
2011-11-16 21:20 ` Clemens Ladisch
2011-11-16 21:31   ` Andrew Eikum
2011-11-16 22:08     ` Clemens Ladisch
2011-11-17 14:02       ` Andrew Eikum
2011-11-21 22:31         ` Raymond Yau
2011-11-22 13:41           ` Andrew Eikum
2011-11-22 23:57             ` Raymond Yau
2011-11-17  0:45     ` Raymond Yau
2011-11-17 13:27       ` Clemens Ladisch
2011-11-19  1:28         ` Raymond Yau

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.