src/pulse/channelmap.h

   1 #ifndef foochannelmaphfoo
   2 #define foochannelmaphfoo
   3
   4 /* $Id$ */
   5
   6 /***
   7   This file is part of PulseAudio.
   8
   9   Copyright 2005-2006 Lennart Poettering
  10   Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
  11
  12   PulseAudio is free software; you can redistribute it and/or modify
  13   it under the terms of the GNU Lesser General Public License as published
  14   by the Free Software Foundation; either version 2 of the License,
  15   or (at your option) any later version.
  16
  17   PulseAudio is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with PulseAudio; if not, write to the Free Software
  24   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  25   USA.
  26 ***/
  27
  28 #include <pulse/sample.h>
  29 #include <pulse/cdecl.h>
  30 #include <pulse/gccmacro.h>
  31
  32 /** \page channelmap Channel Maps
  33  *
  34  * \section overv_sec Overview
  35  *
  36  * Channel maps provide a way to associate channels in a stream with a
  37  * specific speaker position. This relieves applications of having to
  38  * make sure their channel order is identical to the final output.
  39  *
  40  * \section init_sec Initialisation
  41  *
  42  * A channel map consists of an array of \ref pa_channel_position values,
  43  * one for each channel. This array is stored together with a channel count
  44  * in a pa_channel_map structure.
  45  *
  46  * Before filling the structure, the application must initialise it using
  47  * pa_channel_map_init(). There are also a number of convenience functions
  48  * for standard channel mappings:
  49  *
  50  * \li pa_channel_map_init_mono() - Create a channel map with only mono audio.
  51  * \li pa_channel_map_init_stereo() - Create a standard stereo mapping.
  52  * \li pa_channel_map_init_auto() - Create a standard channel map for up to
  53  *                                  six channels.
  54  *
  55  * \section conv_sec Convenience Functions
  56  *
  57  * The library contains a number of convenience functions for dealing with
  58  * channel maps:
  59  *
  60  * \li pa_channel_map_valid() - Tests if a channel map is valid.
  61  * \li pa_channel_map_equal() - Tests if two channel maps are identical.
  62  * \li pa_channel_map_snprint() - Creates a textual description of a channel
  63  *                                map.
  64  */
  65
  66 /** \file
  67  * Constants and routines for channel mapping handling */
  68
  69 PA_C_DECL_BEGIN
  70
  71 /** A list of channel labels */
  72 typedef enum pa_channel_position {
  73     PA_CHANNEL_POSITION_INVALID = -1,
  74     PA_CHANNEL_POSITION_MONO = 0,
  75
  76     PA_CHANNEL_POSITION_LEFT,
  77     PA_CHANNEL_POSITION_RIGHT,
  78     PA_CHANNEL_POSITION_CENTER,
  79
  80     PA_CHANNEL_POSITION_FRONT_LEFT = PA_CHANNEL_POSITION_LEFT,
  81     PA_CHANNEL_POSITION_FRONT_RIGHT = PA_CHANNEL_POSITION_RIGHT,
  82     PA_CHANNEL_POSITION_FRONT_CENTER = PA_CHANNEL_POSITION_CENTER,
  83
  84     PA_CHANNEL_POSITION_REAR_CENTER,
  85     PA_CHANNEL_POSITION_REAR_LEFT,
  86     PA_CHANNEL_POSITION_REAR_RIGHT,
  87
  88     PA_CHANNEL_POSITION_LFE,
  89     PA_CHANNEL_POSITION_SUBWOOFER = PA_CHANNEL_POSITION_LFE,
  90
  91     PA_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER,
  92     PA_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER,
  93
  94     PA_CHANNEL_POSITION_SIDE_LEFT,
  95     PA_CHANNEL_POSITION_SIDE_RIGHT,
  96
  97     PA_CHANNEL_POSITION_AUX0,
  98     PA_CHANNEL_POSITION_AUX1,
  99     PA_CHANNEL_POSITION_AUX2,
 100     PA_CHANNEL_POSITION_AUX3,
 101     PA_CHANNEL_POSITION_AUX4,
 102     PA_CHANNEL_POSITION_AUX5,
 103     PA_CHANNEL_POSITION_AUX6,
 104     PA_CHANNEL_POSITION_AUX7,
 105     PA_CHANNEL_POSITION_AUX8,
 106     PA_CHANNEL_POSITION_AUX9,
 107     PA_CHANNEL_POSITION_AUX10,
 108     PA_CHANNEL_POSITION_AUX11,
 109     PA_CHANNEL_POSITION_AUX12,
 110     PA_CHANNEL_POSITION_AUX13,
 111     PA_CHANNEL_POSITION_AUX14,
 112     PA_CHANNEL_POSITION_AUX15,
 113     PA_CHANNEL_POSITION_AUX16,
 114     PA_CHANNEL_POSITION_AUX17,
 115     PA_CHANNEL_POSITION_AUX18,
 116     PA_CHANNEL_POSITION_AUX19,
 117     PA_CHANNEL_POSITION_AUX20,
 118     PA_CHANNEL_POSITION_AUX21,
 119     PA_CHANNEL_POSITION_AUX22,
 120     PA_CHANNEL_POSITION_AUX23,
 121     PA_CHANNEL_POSITION_AUX24,
 122     PA_CHANNEL_POSITION_AUX25,
 123     PA_CHANNEL_POSITION_AUX26,
 124     PA_CHANNEL_POSITION_AUX27,
 125     PA_CHANNEL_POSITION_AUX28,
 126     PA_CHANNEL_POSITION_AUX29,
 127     PA_CHANNEL_POSITION_AUX30,
 128     PA_CHANNEL_POSITION_AUX31,
 129
 130     PA_CHANNEL_POSITION_TOP_CENTER,
 131
 132     PA_CHANNEL_POSITION_TOP_FRONT_LEFT,
 133     PA_CHANNEL_POSITION_TOP_FRONT_RIGHT,
 134     PA_CHANNEL_POSITION_TOP_FRONT_CENTER,
 135
 136     PA_CHANNEL_POSITION_TOP_REAR_LEFT,
 137     PA_CHANNEL_POSITION_TOP_REAR_RIGHT,
 138     PA_CHANNEL_POSITION_TOP_REAR_CENTER,
 139
 140     PA_CHANNEL_POSITION_MAX
 141 } pa_channel_position_t;
 142
 143 /** A list of channel mapping definitions for pa_channel_map_init_auto() */
 144 typedef enum pa_channel_map_def {
 145     PA_CHANNEL_MAP_AIFF,   /**< The mapping from RFC3551, which is based on AIFF-C */
 146     PA_CHANNEL_MAP_ALSA,   /**< The default mapping used by ALSA */
 147     PA_CHANNEL_MAP_AUX,    /**< Only aux channels */
 148     PA_CHANNEL_MAP_WAVEEX, /**< Microsoft's WAVEFORMATEXTENSIBLE mapping */
 149     PA_CHANNEL_MAP_OSS,    /**< The default channel mapping used by OSS as defined in the OSS 4.0 API specs */
 150
 151     PA_CHANNEL_MAP_DEFAULT = PA_CHANNEL_MAP_AIFF /**< The default channel map */
 152 } pa_channel_map_def_t;
 153
 154 /** A channel map which can be used to attach labels to specific
 155  * channels of a stream. These values are relevant for conversion and
 156  * mixing of streams */
 157 typedef struct pa_channel_map {
 158     uint8_t channels; /**< Number of channels */
 159     pa_channel_position_t map[PA_CHANNELS_MAX]; /**< Channel labels */
 160 } pa_channel_map;
 161
 162 /** Initialize the specified channel map and return a pointer to it */
 163 pa_channel_map* pa_channel_map_init(pa_channel_map *m);
 164
 165 /** Initialize the specified channel map for monoaural audio and return a pointer to it */
 166 pa_channel_map* pa_channel_map_init_mono(pa_channel_map *m);
 167
 168 /** Initialize the specified channel map for stereophonic audio and return a pointer to it */
 169 pa_channel_map* pa_channel_map_init_stereo(pa_channel_map *m);
 170
 171 /** Initialize the specified channel map for the specified number
 172  * of channels using default labels and return a pointer to it. */
 173 pa_channel_map* pa_channel_map_init_auto(pa_channel_map *m, unsigned channels, pa_channel_map_def_t def);
 174
 175 /** Return a text label for the specified channel position */
 176 const char* pa_channel_position_to_string(pa_channel_position_t pos) PA_GCC_PURE;
 177
 178 /** Return a human readable text label for the specified channel position. \since 0.9.7 */
 179 const char* pa_channel_position_to_pretty_string(pa_channel_position_t pos);
 180
 181 /** The maximum length of strings returned by pa_channel_map_snprint() */
 182 #define PA_CHANNEL_MAP_SNPRINT_MAX 336
 183
 184 /** Make a humand readable string from the specified channel map */
 185 char* pa_channel_map_snprint(char *s, size_t l, const pa_channel_map *map);
 186
 187 /** Parse a channel position list into a channel map structure. */
 188 pa_channel_map *pa_channel_map_parse(pa_channel_map *map, const char *s);
 189
 190 /** Compare two channel maps. Return 1 if both match. */
 191 int pa_channel_map_equal(const pa_channel_map *a, const pa_channel_map *b) PA_GCC_PURE;
 192
 193 /** Return non-zero of the specified channel map is considered valid */
 194 int pa_channel_map_valid(const pa_channel_map *map) PA_GCC_PURE;
 195
 196 PA_C_DECL_END
 197
 198 #endif