/** 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 */
*
* 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.
* 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)
{
* \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)
{