code.delx.au - pulseaudio/blob - 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.1 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