prepare doxygen docs for 0.9.11

[pulseaudio] / src / pulse / channelmap.h

diff --git a/src/pulse/channelmap.h b/src/pulse/channelmap.h
index 203802510fb218420c8ac69eb1f734f1486068f5..7c32b8684a4ccb81b93c56b957e44781dcb2c0b2 100644 (file)
--- a/src/pulse/channelmap.h
+++ b/src/pulse/channelmap.h
@@ -1,11 +1,12 @@
 #ifndef foochannelmaphfoo
 #define foochannelmaphfoo
 
-/* $Id$ */
-
 /***
   This file is part of PulseAudio.
 
+  Copyright 2005-2006 Lennart Poettering
+  Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
+
   PulseAudio is free software; you can redistribute it and/or modify
   it under the terms of the GNU Lesser General Public License as published
   by the Free Software Foundation; either version 2 of the License,
@@ -24,6 +25,7 @@
 
 #include <pulse/sample.h>
 #include <pulse/cdecl.h>
+#include <pulse/gccmacro.h>
 
 /** \page channelmap Channel Maps
  *
@@ -45,8 +47,10 @@
  *
  * \li pa_channel_map_init_mono() - Create a channel map with only mono audio.
  * \li pa_channel_map_init_stereo() - Create a standard stereo mapping.
- * \li pa_channel_map_init_auto() - Create a standard channel map for up to
- *                                  six channels.
+ * \li pa_channel_map_init_auto() - Create a standard channel map for a specific number of channels
+ * \li pa_channel_map_init_extend() - Similar to
+ * pa_channel_map_init_auto() but synthesize a channel map if noone
+ * predefined one is known for the specified number of channels.
  *
  * \section conv_sec Convenience Functions
  *
@@ -164,12 +168,23 @@ pa_channel_map* pa_channel_map_init_mono(pa_channel_map *m);
 /** Initialize the specified channel map for stereophonic audio and return a pointer to it */
 pa_channel_map* pa_channel_map_init_stereo(pa_channel_map *m);
 
-/** Initialize the specified channel map for the specified number
- * of channels using default labels and return a pointer to it. */
+/** Initialize the specified channel map for the specified number of
+ * channels using default labels and return a pointer to it. This call
+ * will fail (return NULL) if there is no default channel map known for this
+ * specific number of channels and mapping. */
 pa_channel_map* pa_channel_map_init_auto(pa_channel_map *m, unsigned channels, pa_channel_map_def_t def);
 
+/** Similar to pa_channel_map_init_auto() but instead of failing if no
+ * default mapping is known with the specified parameters it will
+ * synthesize a mapping based on a known mapping with fewer channels
+ * and fill up the rest with AUX0...AUX31 channels  \since 0.9.11 */
+pa_channel_map* pa_channel_map_init_extend(pa_channel_map *m, unsigned channels, pa_channel_map_def_t def);
+
 /** Return a text label for the specified channel position */
-const char* pa_channel_position_to_string(pa_channel_position_t pos);
+const char* pa_channel_position_to_string(pa_channel_position_t pos) PA_GCC_PURE;
+
+/** Return a human readable text label for the specified channel position. \since 0.9.7 */
+const char* pa_channel_position_to_pretty_string(pa_channel_position_t pos);
 
 /** The maximum length of strings returned by pa_channel_map_snprint() */
 #define PA_CHANNEL_MAP_SNPRINT_MAX 336
@@ -177,14 +192,14 @@ const char* pa_channel_position_to_string(pa_channel_position_t pos);
 /** Make a humand readable string from the specified channel map */
 char* pa_channel_map_snprint(char *s, size_t l, const pa_channel_map *map);
 
-/** Parse a channel position list into a channel map structure. \since 0.8.1 */
+/** Parse a channel position list into a channel map structure. */
 pa_channel_map *pa_channel_map_parse(pa_channel_map *map, const char *s);
 
 /** Compare two channel maps. Return 1 if both match. */
-int pa_channel_map_equal(const pa_channel_map *a, const pa_channel_map *b);
+int pa_channel_map_equal(const pa_channel_map *a, const pa_channel_map *b) PA_GCC_PURE;
 
 /** Return non-zero of the specified channel map is considered valid */
-int pa_channel_map_valid(const pa_channel_map *map);
+int pa_channel_map_valid(const pa_channel_map *map) PA_GCC_PURE;
 
 PA_C_DECL_END