doxygen: Documentation improvements

[pulseaudio] / src / pulse / channelmap.h

diff --git a/src/pulse/channelmap.h b/src/pulse/channelmap.h
index 2aaead01325e0e1a2dc42daeaafcfff42ebfa7c9..d1d5c8b3255bc3e3a6ae9f27a90596b98e1d1025 100644 (file)
--- a/src/pulse/channelmap.h
+++ b/src/pulse/channelmap.h
@@ -74,9 +74,9 @@ typedef enum pa_channel_position {
     PA_CHANNEL_POSITION_INVALID = -1,
     PA_CHANNEL_POSITION_MONO = 0,
 
-    PA_CHANNEL_POSITION_FRONT_LEFT,               /* Apple calls this 'Left' */
-    PA_CHANNEL_POSITION_FRONT_RIGHT,              /* Apple calls this 'Right' */
-    PA_CHANNEL_POSITION_FRONT_CENTER,             /* Apple calls this 'Center' */
+    PA_CHANNEL_POSITION_FRONT_LEFT,               /* Apple, Dolby call this 'Left' */
+    PA_CHANNEL_POSITION_FRONT_RIGHT,              /* Apple, Dolby call this 'Right' */
+    PA_CHANNEL_POSITION_FRONT_CENTER,             /* Apple, Dolby call this 'Center' */
 
 /** \cond fulldocs */
     PA_CHANNEL_POSITION_LEFT = PA_CHANNEL_POSITION_FRONT_LEFT,
@@ -84,20 +84,20 @@ typedef enum pa_channel_position {
     PA_CHANNEL_POSITION_CENTER = PA_CHANNEL_POSITION_FRONT_CENTER,
 /** \endcond */
 
-    PA_CHANNEL_POSITION_REAR_CENTER,              /* Microsoft calls this 'Back Center', Apple calls this 'Center Surround' */
-    PA_CHANNEL_POSITION_REAR_LEFT,                /* Microsoft calls this 'Back Left', Apple calls this 'Left Surround' */
-    PA_CHANNEL_POSITION_REAR_RIGHT,               /* Microsoft calls this 'Back Right', Apple calls this 'Right Surround' */
+    PA_CHANNEL_POSITION_REAR_CENTER,              /* Microsoft calls this 'Back Center', Apple calls this 'Center Surround', Dolby calls this 'Surround Rear Center' */
+    PA_CHANNEL_POSITION_REAR_LEFT,                /* Microsoft calls this 'Back Left', Apple calls this 'Left Surround' (!), Dolby calls this 'Surround Rear Left'  */
+    PA_CHANNEL_POSITION_REAR_RIGHT,               /* Microsoft calls this 'Back Right', Apple calls this 'Right Surround' (!), Dolby calls this 'Surround Rear Right'  */
 
     PA_CHANNEL_POSITION_LFE,                      /* Microsoft calls this 'Low Frequency', Apple calls this 'LFEScreen' */
 /** \cond fulldocs */
     PA_CHANNEL_POSITION_SUBWOOFER = PA_CHANNEL_POSITION_LFE,
 /** \endcond */
 
-    PA_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER,     /* Apple calls this 'Left Center' */
-    PA_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER,    /* Apple calls this 'Right Center */
+    PA_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER,     /* Apple, Dolby call this 'Left Center' */
+    PA_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER,    /* Apple, Dolby call this 'Right Center */
 
-    PA_CHANNEL_POSITION_SIDE_LEFT,                /* Apple calls this 'Left Surround Direct' */
-    PA_CHANNEL_POSITION_SIDE_RIGHT,               /* Apple calls this 'Right Surround Direct' */
+    PA_CHANNEL_POSITION_SIDE_LEFT,                /* Apple calls this 'Left Surround Direct', Dolby calls this 'Surround Left' (!) */
+    PA_CHANNEL_POSITION_SIDE_RIGHT,               /* Apple calls this 'Right Surround Direct', Dolby calls this 'Surround Right' (!) */
 
     PA_CHANNEL_POSITION_AUX0,
     PA_CHANNEL_POSITION_AUX1,
@@ -209,24 +209,34 @@ typedef enum pa_channel_position {
 typedef uint64_t pa_channel_position_mask_t;
 
 /** Makes a bit mask from a channel position. \since 0.9.16 */
-#define PA_CHANNEL_POSITION_MASK(f) ((pa_channel_position_mask_t) (1 << (f)))
+#define PA_CHANNEL_POSITION_MASK(f) ((pa_channel_position_mask_t) (1ULL << (f)))
 
 /** A list of channel mapping definitions for pa_channel_map_init_auto() */
 typedef enum pa_channel_map_def {
     PA_CHANNEL_MAP_AIFF,
     /**< The mapping from RFC3551, which is based on AIFF-C */
 
+/** \cond fulldocs */
     PA_CHANNEL_MAP_ALSA,
-    /**< The default mapping used by ALSA */
+    /**< The default mapping used by ALSA. This mapping is probably
+     * not too useful since ALSA's default channel mapping depends on
+     * the device string used. */
+/** \endcond */
 
     PA_CHANNEL_MAP_AUX,
     /**< Only aux channels */
 
     PA_CHANNEL_MAP_WAVEEX,
-    /**< Microsoft's WAVEFORMATEXTENSIBLE mapping */
+    /**< Microsoft's WAVEFORMATEXTENSIBLE mapping. This mapping works
+     * as if all LSBs of dwChannelMask are set.  */
 
+/** \cond fulldocs */
     PA_CHANNEL_MAP_OSS,
-    /**< The default channel mapping used by OSS as defined in the OSS 4.0 API specs */
+    /**< The default channel mapping used by OSS as defined in the OSS
+     * 4.0 API specs. This mapping is probably not too useful since
+     * the OSS API has changed in this respect and no longer knows a
+     * default channel mapping based on the number of channels. */
+/** \endcond */
 
     /**< Upper limit of valid channel mapping definitions */
     PA_CHANNEL_MAP_DEF_MAX,
@@ -282,6 +292,9 @@ pa_channel_map* pa_channel_map_init_extend(pa_channel_map *m, unsigned channels,
 /** Return a text label for the specified channel position */
 const char* pa_channel_position_to_string(pa_channel_position_t pos) PA_GCC_PURE;
 
+/** The inverse of pa_channel_position_to_string(). \since 0.9.16 */
+pa_channel_position_t pa_channel_position_from_string(const char *s) 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);