File 0025-PCM-A-few-doxygen-fixes-for-chmap-stuff.patch of Package alsa
From 63f6f4a6103e55d242440488999e648beb5e4e4d Mon Sep 17 00:00:00 2001
From: Takashi Iwai <tiwai@suse.de>
Date: Thu, 13 Sep 2012 08:38:59 +0200
Subject: [PATCH 25/30] PCM: A few doxygen fixes for chmap stuff
Signed-off-by: Takashi Iwai <tiwai@suse.de>
---
include/pcm.h | 18 +++++++++++-------
src/pcm/pcm.c | 43 +++++++++++++++++++++++++++++++++++++++++++
2 files changed, 54 insertions(+), 7 deletions(-)
--- a/include/pcm.h
+++ b/include/pcm.h
@@ -519,20 +519,24 @@ enum snd_pcm_chmap_position {
SND_CHMAP_LAST = SND_CHMAP_TRC, /** last entry */
};
-#define SND_CHMAP_POSITION_MASK 0xffff /** bitmask for channel position */
-#define SND_CHMAP_PHASE_INVERSE (0x01 << 16) /* the channel is phase inverted */
-#define SND_CHMAP_DRIVER_SPEC (0x02 << 16) /* non-standard channel value */
+/** bitmask for channel position */
+#define SND_CHMAP_POSITION_MASK 0xffff
+
+/** bit flag indicating the channel is phase inverted */
+#define SND_CHMAP_PHASE_INVERSE (0x01 << 16)
+/** bit flag indicating the non-standard channel value */
+#define SND_CHMAP_DRIVER_SPEC (0x02 << 16)
/** the channel map header */
typedef struct snd_pcm_chmap {
- unsigned int channels;
- unsigned int pos[0];
+ unsigned int channels; /** number of channels */
+ unsigned int pos[0]; /** channel position array */
} snd_pcm_chmap_t;
/** the header of array items returned from snd_pcm_query_chmaps() */
typedef struct snd_pcm_chmap_query {
- enum snd_pcm_chmap_type type;
- snd_pcm_chmap_t map;
+ enum snd_pcm_chmap_type type; /** channel map type */
+ snd_pcm_chmap_t map; /** available channel map */
} snd_pcm_chmap_query_t;
--- a/src/pcm/pcm.c
+++ b/src/pcm/pcm.c
@@ -7310,6 +7310,9 @@ OBSOLETE1(snd_pcm_sw_params_get_silence_
* which contains the channel map. A channel map is represented by an
* integer array, beginning with the channel map type, followed by the
* number of channels, and the position of each channel.
+ *
+ * Note: the caller is requested to release the returned value via
+ * snd_pcm_free_chmaps().
*/
snd_pcm_chmap_query_t **snd_pcm_query_chmaps(snd_pcm_t *pcm)
{
@@ -7336,6 +7339,8 @@ void snd_pcm_free_chmaps(snd_pcm_chmap_q
* \!brief Get the current channel map
* \param pcm PCM instance
* \return the current channel map, or NULL if error
+ *
+ * Note: the caller is requested to release the returned value via free()
*/
snd_pcm_chmap_t *snd_pcm_get_chmap(snd_pcm_t *pcm)
{
@@ -7359,12 +7364,19 @@ int snd_pcm_set_chmap(snd_pcm_t *pcm, co
/*
*/
+#ifndef DOC_HIDDEN
#define _NAME(n) [SND_CHMAP_TYPE_##n] = #n
static const char *chmap_type_names[SND_CHMAP_TYPE_LAST + 1] = {
_NAME(NONE), _NAME(FIXED), _NAME(VAR), _NAME(PAIRED),
};
#undef _NAME
+#endif
+/**
+ * \!brief Get a name string for a channel map type as query results
+ * \param val Channel position
+ * \return The string corresponding to the given type, or NULL
+ */
const char *snd_pcm_chmap_type_name(enum snd_pcm_chmap_type val)
{
if (val <= SND_CHMAP_TYPE_LAST)
@@ -7373,6 +7385,7 @@ const char *snd_pcm_chmap_type_name(enum
return NULL;
}
+#ifndef DOC_HIDDEN
#define _NAME(n) [SND_CHMAP_##n] = #n
static const char *chmap_names[SND_CHMAP_LAST + 1] = {
_NAME(UNKNOWN), _NAME(NA), _NAME(MONO),
@@ -7387,7 +7400,13 @@ static const char *chmap_names[SND_CHMAP
_NAME(TRL), _NAME(TRR), _NAME(TRC),
};
#undef _NAME
+#endif
+/**
+ * \!brief Get a name string for a standard channel map position
+ * \param val Channel position
+ * \return The string corresponding to the given position, or NULL
+ */
const char *snd_pcm_chmap_name(enum snd_pcm_chmap_position val)
{
if (val <= SND_CHMAP_LAST)
@@ -7427,6 +7446,11 @@ static const char *chmap_long_names[SND_
[SND_CHMAP_TRC] = "Top Rear Center",
};
+/**
+ * \!brief Get a longer name string for a standard channel map position
+ * \param val Channel position
+ * \return The string corresponding to the given position, or NULL
+ */
const char *snd_pcm_chmap_long_name(enum snd_pcm_chmap_position val)
{
if (val <= SND_CHMAP_LAST)
@@ -7435,6 +7459,13 @@ const char *snd_pcm_chmap_long_name(enum
return NULL;
}
+/**
+ * \!brief Print the channels in chmap on the buffer
+ * \param map The channel map to print
+ * \param maxlen The maximal length to write (including NUL letter)
+ * \param buf The buffer to write
+ * \return The actual string length or a negative error code
+ */
int snd_pcm_chmap_print(const snd_pcm_chmap_t *map, size_t maxlen, char *buf)
{
unsigned int i, len = 0;
@@ -7508,11 +7539,23 @@ static int str_to_chmap(const char *str,
return val;
}
+/**
+ * \!brief Convert from string to channel position
+ * \param str The string to parse
+ * \return The channel position value or -1 as an error
+ */
unsigned int snd_pcm_chmap_from_string(const char *str)
{
return str_to_chmap(str, strlen(str));
}
+/**
+ * \!brief Convert from string to channel map
+ * \param str The string to parse
+ * \return The channel map
+ *
+ * Note: the caller is requested to release the returned value via free()
+ */
snd_pcm_chmap_t *snd_pcm_chmap_parse_string(const char *str)
{
int i, ch = 0;
