src/pulse/channelmap.h

   1 #ifndef foochannelmaphfoo
   2 #define foochannelmaphfoo
   3
   4 /***
   5   This file is part of PulseAudio.
   6
   7   Copyright 2005-2006 Lennart Poettering
   8   Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
   9
  10   PulseAudio is free software; you can redistribute it and/or modify
  11   it under the terms of the GNU Lesser General Public License as published
  12   by the Free Software Foundation; either version 2 of the License,
  13   or (at your option) any later version.
  14
  15   PulseAudio is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with PulseAudio; if not, write to the Free Software
  22   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  23   USA.
  24 ***/
  25
  26 #include <pulse/sample.h>
  27 #include <pulse/cdecl.h>
  28 #include <pulse/gccmacro.h>
  29 #include <pulse/version.h>
  30
  31 /** \page channelmap Channel Maps
  32  *
  33  * \section overv_sec Overview
  34  *
  35  * Channel maps provide a way to associate channels in a stream with a
  36  * specific speaker position. This relieves applications of having to
  37  * make sure their channel order is identical to the final output.
  38  *
  39  * \section init_sec Initialisation
  40  *
  41  * A channel map consists of an array of \ref pa_channel_position values,
  42  * one for each channel. This array is stored together with a channel count
  43  * in a pa_channel_map structure.
  44  *
  45  * Before filling the structure, the application must initialise it using
  46  * pa_channel_map_init(). There are also a number of convenience functions
  47  * for standard channel mappings:
  48  *
  49  * \li pa_channel_map_init_mono() - Create a channel map with only mono audio.
  50  * \li pa_channel_map_init_stereo() - Create a standard stereo mapping.
  51  * \li pa_channel_map_init_auto() - Create a standard channel map for a specific number of channels
  52  * \li pa_channel_map_init_extend() - Similar to
  53  * pa_channel_map_init_auto() but synthesize a channel map if noone
  54  * predefined one is known for the specified number of channels.
  55  *
  56  * \section conv_sec Convenience Functions
  57  *
  58  * The library contains a number of convenience functions for dealing with
  59  * channel maps:
  60  *
  61  * \li pa_channel_map_valid() - Tests if a channel map is valid.
  62  * \li pa_channel_map_equal() - Tests if two channel maps are identical.
  63  * \li pa_channel_map_snprint() - Creates a textual description of a channel
  64  *                                map.
  65  */
  66
  67 /** \file
  68  * Constants and routines for channel mapping handling */
  69
  70 PA_C_DECL_BEGIN
  71
  72 /** A list of channel labels */
  73 typedef enum pa_channel_position {
  74     PA_CHANNEL_POSITION_INVALID = -1,
  75     PA_CHANNEL_POSITION_MONO = 0,
  76
  77     PA_CHANNEL_POSITION_LEFT,
  78     PA_CHANNEL_POSITION_RIGHT,
  79     PA_CHANNEL_POSITION_CENTER,
  80
  81     PA_CHANNEL_POSITION_FRONT_LEFT = PA_CHANNEL_POSITION_LEFT,
  82     PA_CHANNEL_POSITION_FRONT_RIGHT = PA_CHANNEL_POSITION_RIGHT,
  83     PA_CHANNEL_POSITION_FRONT_CENTER = PA_CHANNEL_POSITION_CENTER,
  84
  85     PA_CHANNEL_POSITION_REAR_CENTER,
  86     PA_CHANNEL_POSITION_REAR_LEFT,
  87     PA_CHANNEL_POSITION_REAR_RIGHT,
  88
  89     PA_CHANNEL_POSITION_LFE,
  90     PA_CHANNEL_POSITION_SUBWOOFER = PA_CHANNEL_POSITION_LFE,
  91
  92     PA_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER,
  93     PA_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER,
  94
  95     PA_CHANNEL_POSITION_SIDE_LEFT,
  96     PA_CHANNEL_POSITION_SIDE_RIGHT,
  97
  98     PA_CHANNEL_POSITION_AUX0,
  99     PA_CHANNEL_POSITION_AUX1,
 100     PA_CHANNEL_POSITION_AUX2,
 101     PA_CHANNEL_POSITION_AUX3,
 102     PA_CHANNEL_POSITION_AUX4,
 103     PA_CHANNEL_POSITION_AUX5,
 104     PA_CHANNEL_POSITION_AUX6,
 105     PA_CHANNEL_POSITION_AUX7,
 106     PA_CHANNEL_POSITION_AUX8,
 107     PA_CHANNEL_POSITION_AUX9,
 108     PA_CHANNEL_POSITION_AUX10,
 109     PA_CHANNEL_POSITION_AUX11,
 110     PA_CHANNEL_POSITION_AUX12,
 111     PA_CHANNEL_POSITION_AUX13,
 112     PA_CHANNEL_POSITION_AUX14,
 113     PA_CHANNEL_POSITION_AUX15,
 114     PA_CHANNEL_POSITION_AUX16,
 115     PA_CHANNEL_POSITION_AUX17,
 116     PA_CHANNEL_POSITION_AUX18,
 117     PA_CHANNEL_POSITION_AUX19,
 118     PA_CHANNEL_POSITION_AUX20,
 119     PA_CHANNEL_POSITION_AUX21,
 120     PA_CHANNEL_POSITION_AUX22,
 121     PA_CHANNEL_POSITION_AUX23,
 122     PA_CHANNEL_POSITION_AUX24,
 123     PA_CHANNEL_POSITION_AUX25,
 124     PA_CHANNEL_POSITION_AUX26,
 125     PA_CHANNEL_POSITION_AUX27,
 126     PA_CHANNEL_POSITION_AUX28,
 127     PA_CHANNEL_POSITION_AUX29,
 128     PA_CHANNEL_POSITION_AUX30,
 129     PA_CHANNEL_POSITION_AUX31,
 130
 131     PA_CHANNEL_POSITION_TOP_CENTER,
 132
 133     PA_CHANNEL_POSITION_TOP_FRONT_LEFT,
 134     PA_CHANNEL_POSITION_TOP_FRONT_RIGHT,
 135     PA_CHANNEL_POSITION_TOP_FRONT_CENTER,
 136
 137     PA_CHANNEL_POSITION_TOP_REAR_LEFT,
 138     PA_CHANNEL_POSITION_TOP_REAR_RIGHT,
 139     PA_CHANNEL_POSITION_TOP_REAR_CENTER,
 140
 141     PA_CHANNEL_POSITION_MAX
 142 } pa_channel_position_t;
 143
 144 /** \cond fulldocs */
 145 #define PA_CHANNEL_POSITION_INVALID PA_CHANNEL_POSITION_INVALID
 146 #define PA_CHANNEL_POSITION_MONO PA_CHANNEL_POSITION_MONO
 147 #define PA_CHANNEL_POSITION_LEFT PA_CHANNEL_POSITION_LEFT
 148 #define PA_CHANNEL_POSITION_RIGHT PA_CHANNEL_POSITION_RIGHT
 149 #define PA_CHANNEL_POSITION_CENTER PA_CHANNEL_POSITION_CENTER
 150 #define PA_CHANNEL_POSITION_FRONT_LEFT PA_CHANNEL_POSITION_FRONT_LEFT
 151 #define PA_CHANNEL_POSITION_FRONT_RIGHT PA_CHANNEL_POSITION_FRONT_RIGHT
 152 #define PA_CHANNEL_POSITION_FRONT_CENTER PA_CHANNEL_POSITION_FRONT_CENTER
 153 #define PA_CHANNEL_POSITION_REAR_CENTER PA_CHANNEL_POSITION_REAR_CENTER
 154 #define PA_CHANNEL_POSITION_REAR_LEFT PA_CHANNEL_POSITION_REAR_LEFT
 155 #define PA_CHANNEL_POSITION_REAR_RIGHT PA_CHANNEL_POSITION_REAR_RIGHT
 156 #define PA_CHANNEL_POSITION_LFE PA_CHANNEL_POSITION_LFE
 157 #define PA_CHANNEL_POSITION_SUBWOOFER PA_CHANNEL_POSITION_SUBWOOFER
 158 #define PA_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER PA_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER
 159 #define PA_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER PA_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER
 160 #define PA_CHANNEL_POSITION_SIDE_LEFT PA_CHANNEL_POSITION_SIDE_LEFT
 161 #define PA_CHANNEL_POSITION_SIDE_RIGHT PA_CHANNEL_POSITION_SIDE_RIGHT
 162 #define PA_CHANNEL_POSITION_AUX0 PA_CHANNEL_POSITION_AUX0
 163 #define PA_CHANNEL_POSITION_AUX1 PA_CHANNEL_POSITION_AUX1
 164 #define PA_CHANNEL_POSITION_AUX2 PA_CHANNEL_POSITION_AUX2
 165 #define PA_CHANNEL_POSITION_AUX3 PA_CHANNEL_POSITION_AUX3
 166 #define PA_CHANNEL_POSITION_AUX4 PA_CHANNEL_POSITION_AUX4
 167 #define PA_CHANNEL_POSITION_AUX5 PA_CHANNEL_POSITION_AUX5
 168 #define PA_CHANNEL_POSITION_AUX6 PA_CHANNEL_POSITION_AUX6
 169 #define PA_CHANNEL_POSITION_AUX7 PA_CHANNEL_POSITION_AUX7
 170 #define PA_CHANNEL_POSITION_AUX8 PA_CHANNEL_POSITION_AUX8
 171 #define PA_CHANNEL_POSITION_AUX9 PA_CHANNEL_POSITION_AUX9
 172 #define PA_CHANNEL_POSITION_AUX10 PA_CHANNEL_POSITION_AUX10
 173 #define PA_CHANNEL_POSITION_AUX11 PA_CHANNEL_POSITION_AUX11
 174 #define PA_CHANNEL_POSITION_AUX12 PA_CHANNEL_POSITION_AUX12
 175 #define PA_CHANNEL_POSITION_AUX13 PA_CHANNEL_POSITION_AUX13
 176 #define PA_CHANNEL_POSITION_AUX14 PA_CHANNEL_POSITION_AUX14
 177 #define PA_CHANNEL_POSITION_AUX15 PA_CHANNEL_POSITION_AUX15
 178 #define PA_CHANNEL_POSITION_AUX16 PA_CHANNEL_POSITION_AUX16
 179 #define PA_CHANNEL_POSITION_AUX17 PA_CHANNEL_POSITION_AUX17
 180 #define PA_CHANNEL_POSITION_AUX18 PA_CHANNEL_POSITION_AUX18
 181 #define PA_CHANNEL_POSITION_AUX19 PA_CHANNEL_POSITION_AUX19
 182 #define PA_CHANNEL_POSITION_AUX20 PA_CHANNEL_POSITION_AUX20
 183 #define PA_CHANNEL_POSITION_AUX21 PA_CHANNEL_POSITION_AUX21
 184 #define PA_CHANNEL_POSITION_AUX22 PA_CHANNEL_POSITION_AUX22
 185 #define PA_CHANNEL_POSITION_AUX23 PA_CHANNEL_POSITION_AUX23
 186 #define PA_CHANNEL_POSITION_AUX24 PA_CHANNEL_POSITION_AUX24
 187 #define PA_CHANNEL_POSITION_AUX25 PA_CHANNEL_POSITION_AUX25
 188 #define PA_CHANNEL_POSITION_AUX26 PA_CHANNEL_POSITION_AUX26
 189 #define PA_CHANNEL_POSITION_AUX27 PA_CHANNEL_POSITION_AUX27
 190 #define PA_CHANNEL_POSITION_AUX28 PA_CHANNEL_POSITION_AUX28
 191 #define PA_CHANNEL_POSITION_AUX29 PA_CHANNEL_POSITION_AUX29
 192 #define PA_CHANNEL_POSITION_AUX30 PA_CHANNEL_POSITION_AUX30
 193 #define PA_CHANNEL_POSITION_AUX31 PA_CHANNEL_POSITION_AUX31
 194 #define PA_CHANNEL_POSITION_TOP_CENTER PA_CHANNEL_POSITION_TOP_CENTER
 195 #define PA_CHANNEL_POSITION_TOP_FRONT_LEFT PA_CHANNEL_POSITION_TOP_FRONT_LEFT
 196 #define PA_CHANNEL_POSITION_TOP_FRONT_RIGHT PA_CHANNEL_POSITION_TOP_FRONT_RIGHT
 197 #define PA_CHANNEL_POSITION_TOP_FRONT_CENTER PA_CHANNEL_POSITION_TOP_FRONT_CENTER
 198 #define PA_CHANNEL_POSITION_TOP_REAR_LEFT PA_CHANNEL_POSITION_TOP_REAR_LEFT
 199 #define PA_CHANNEL_POSITION_TOP_REAR_RIGHT PA_CHANNEL_POSITION_TOP_REAR_RIGHT
 200 #define PA_CHANNEL_POSITION_TOP_REAR_CENTER PA_CHANNEL_POSITION_TOP_REAR_CENTER
 201 #define PA_CHANNEL_POSITION_MAX PA_CHANNEL_POSITION_MAX
 202 /** \endcond */
 203
 204 /** A list of channel mapping definitions for pa_channel_map_init_auto() */
 205 typedef enum pa_channel_map_def {
 206     PA_CHANNEL_MAP_AIFF,
 207     /**< The mapping from RFC3551, which is based on AIFF-C */
 208
 209     PA_CHANNEL_MAP_ALSA,
 210     /**< The default mapping used by ALSA */
 211
 212     PA_CHANNEL_MAP_AUX,
 213     /**< Only aux channels */
 214
 215     PA_CHANNEL_MAP_WAVEEX,
 216     /**< Microsoft's WAVEFORMATEXTENSIBLE mapping */
 217
 218     PA_CHANNEL_MAP_OSS,
 219     /**< The default channel mapping used by OSS as defined in the OSS 4.0 API specs */
 220
 221     /**< Upper limit of valid channel mapping definitions */
 222     PA_CHANNEL_MAP_DEF_MAX,
 223
 224     PA_CHANNEL_MAP_DEFAULT = PA_CHANNEL_MAP_AIFF
 225     /**< The default channel map */
 226 } pa_channel_map_def_t;
 227
 228 /** \cond fulldocs */
 229 #define PA_CHANNEL_MAP_AIFF PA_CHANNEL_MAP_AIFF
 230 #define PA_CHANNEL_MAP_ALSA PA_CHANNEL_MAP_ALSA
 231 #define PA_CHANNEL_MAP_AUX PA_CHANNEL_MAP_AUX
 232 #define PA_CHANNEL_MAP_WAVEEX PA_CHANNEL_MAP_WAVEEX
 233 #define PA_CHANNEL_MAP_OSS PA_CHANNEL_MAP_OSS
 234 #define PA_CHANNEL_MAP_DEF_MAX PA_CHANNEL_MAP_DEF_MAX
 235 #define PA_CHANNEL_MAP_DEFAULT PA_CHANNEL_MAP_DEFAULT
 236 /** \endcond */
 237
 238 /** A channel map which can be used to attach labels to specific
 239  * channels of a stream. These values are relevant for conversion and
 240  * mixing of streams */
 241 typedef struct pa_channel_map {
 242     uint8_t channels;
 243     /**< Number of channels */
 244
 245     pa_channel_position_t map[PA_CHANNELS_MAX];
 246     /**< Channel labels */
 247 } pa_channel_map;
 248
 249 /** Initialize the specified channel map and return a pointer to
 250  * it. The channel map will have a defined state but
 251  * pa_channel_map_valid() will fail for it. */
 252 pa_channel_map* pa_channel_map_init(pa_channel_map *m);
 253
 254 /** Initialize the specified channel map for monoaural audio and return a pointer to it */
 255 pa_channel_map* pa_channel_map_init_mono(pa_channel_map *m);
 256
 257 /** Initialize the specified channel map for stereophonic audio and return a pointer to it */
 258 pa_channel_map* pa_channel_map_init_stereo(pa_channel_map *m);
 259
 260 /** Initialize the specified channel map for the specified number of
 261  * channels using default labels and return a pointer to it. This call
 262  * will fail (return NULL) if there is no default channel map known for this
 263  * specific number of channels and mapping. */
 264 pa_channel_map* pa_channel_map_init_auto(pa_channel_map *m, unsigned channels, pa_channel_map_def_t def);
 265
 266 /** Similar to pa_channel_map_init_auto() but instead of failing if no
 267  * default mapping is known with the specified parameters it will
 268  * synthesize a mapping based on a known mapping with fewer channels
 269  * and fill up the rest with AUX0...AUX31 channels  \since 0.9.11 */
 270 pa_channel_map* pa_channel_map_init_extend(pa_channel_map *m, unsigned channels, pa_channel_map_def_t def);
 271
 272 /** Return a text label for the specified channel position */
 273 const char* pa_channel_position_to_string(pa_channel_position_t pos) PA_GCC_PURE;
 274
 275 /** Return a human readable text label for the specified channel position. \since 0.9.7 */
 276 const char* pa_channel_position_to_pretty_string(pa_channel_position_t pos);
 277
 278 /** The maximum length of strings returned by
 279  * pa_channel_map_snprint(). Please note that this value can change
 280  * with any release without warning and without being considered API
 281  * or ABI breakage. You should not use this definition anywhere where
 282  * it might become part of an ABI. */
 283 #define PA_CHANNEL_MAP_SNPRINT_MAX 336
 284
 285 /** Make a humand readable string from the specified channel map */
 286 char* pa_channel_map_snprint(char *s, size_t l, const pa_channel_map *map);
 287
 288 /** Parse a channel position list or well-known mapping name into a
 289  * channel map structure. This turns the output of
 290  * pa_channel_map_snprint() and pa_channel_map_to_name() back into a
 291  * pa_channel_map */
 292 pa_channel_map *pa_channel_map_parse(pa_channel_map *map, const char *s);
 293
 294 /** Compare two channel maps. Return 1 if both match. */
 295 int pa_channel_map_equal(const pa_channel_map *a, const pa_channel_map *b) PA_GCC_PURE;
 296
 297 /** Return non-zero if the specified channel map is considered valid */
 298 int pa_channel_map_valid(const pa_channel_map *map) PA_GCC_PURE;
 299
 300 /** Return non-zero if the specified channel map is compatible with
 301  * the specified sample spec. \since 0.9.12 */
 302 int pa_channel_map_compatible(const pa_channel_map *map, const pa_sample_spec *ss) PA_GCC_PURE;
 303
 304 /** Returns non-zero if every channel defined in b is also defined in a. \since 0.9.15 */
 305 int pa_channel_map_superset(const pa_channel_map *a, const pa_channel_map *b) PA_GCC_PURE;
 306
 307 /** Returns non-zero if it makes sense to apply a volume 'balance'
 308  * with this mapping, i.e. if there are left/right channels
 309  * available. \since 0.9.15 */
 310 int pa_channel_map_can_balance(const pa_channel_map *map) PA_GCC_PURE;
 311
 312 /** Returns non-zero if it makes sense to apply a volume 'fade'
 313  * (i.e. 'balance' between front and rear) with this mapping, i.e. if
 314  * there are front/rear channels available. \since 0.9.15 */
 315 int pa_channel_map_can_fade(const pa_channel_map *map) PA_GCC_PURE;
 316
 317 /** Tries to find a well-known channel mapping name for this channel
 318  * mapping. I.e. "stereo", "surround-71" and so on. If the channel
 319  * mapping is unknown NULL will be returned. This name can be parsed
 320  * with pa_channel_map_parse() \since 0.9.15 */
 321 const char* pa_channel_map_to_name(const pa_channel_map *map) PA_GCC_PURE;
 322
 323 /** Tries to find a human readable text label for this channel
 324 mapping. I.e. "Stereo", "Surround 7.1" and so on. If the channel
 325 mapping is unknown NULL will be returned. \since 0.9.15 */
 326 const char* pa_channel_map_to_pretty_name(const pa_channel_map *map) PA_GCC_PURE;
 327
 328 PA_C_DECL_END
 329
 330 #endif