1 #ifndef foochannelmaphfoo
2 #define foochannelmaphfoo
5 This file is part of PulseAudio.
7 Copyright 2005-2006 Lennart Poettering
8 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
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.
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.
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
26 #include <pulse/sample.h>
27 #include <pulse/cdecl.h>
28 #include <pulse/gccmacro.h>
29 #include <pulse/version.h>
31 /** \page channelmap Channel Maps
33 * \section overv_sec Overview
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.
39 * \section init_sec Initialisation
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.
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:
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.
56 * \section conv_sec Convenience Functions
58 * The library contains a number of convenience functions for dealing with
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
68 * Constants and routines for channel mapping handling */
72 /** A list of channel labels */
73 typedef enum pa_channel_position
{
74 PA_CHANNEL_POSITION_INVALID
= -1,
75 PA_CHANNEL_POSITION_MONO
= 0,
77 PA_CHANNEL_POSITION_LEFT
,
78 PA_CHANNEL_POSITION_RIGHT
,
79 PA_CHANNEL_POSITION_CENTER
,
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
,
85 PA_CHANNEL_POSITION_REAR_CENTER
,
86 PA_CHANNEL_POSITION_REAR_LEFT
,
87 PA_CHANNEL_POSITION_REAR_RIGHT
,
89 PA_CHANNEL_POSITION_LFE
,
90 PA_CHANNEL_POSITION_SUBWOOFER
= PA_CHANNEL_POSITION_LFE
,
92 PA_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER
,
93 PA_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER
,
95 PA_CHANNEL_POSITION_SIDE_LEFT
,
96 PA_CHANNEL_POSITION_SIDE_RIGHT
,
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
,
131 PA_CHANNEL_POSITION_TOP_CENTER
,
133 PA_CHANNEL_POSITION_TOP_FRONT_LEFT
,
134 PA_CHANNEL_POSITION_TOP_FRONT_RIGHT
,
135 PA_CHANNEL_POSITION_TOP_FRONT_CENTER
,
137 PA_CHANNEL_POSITION_TOP_REAR_LEFT
,
138 PA_CHANNEL_POSITION_TOP_REAR_RIGHT
,
139 PA_CHANNEL_POSITION_TOP_REAR_CENTER
,
141 PA_CHANNEL_POSITION_MAX
142 } pa_channel_position_t
;
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
204 /** A list of channel mapping definitions for pa_channel_map_init_auto() */
205 typedef enum pa_channel_map_def
{
207 /**< The mapping from RFC3551, which is based on AIFF-C */
210 /**< The default mapping used by ALSA */
213 /**< Only aux channels */
215 PA_CHANNEL_MAP_WAVEEX
,
216 /**< Microsoft's WAVEFORMATEXTENSIBLE mapping */
219 /**< The default channel mapping used by OSS as defined in the OSS 4.0 API specs */
221 /**< Upper limit of valid channel mapping definitions */
222 PA_CHANNEL_MAP_DEF_MAX
,
224 PA_CHANNEL_MAP_DEFAULT
= PA_CHANNEL_MAP_AIFF
225 /**< The default channel map */
226 } pa_channel_map_def_t
;
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
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
{
243 /**< Number of channels */
245 pa_channel_position_t map
[PA_CHANNELS_MAX
];
246 /**< Channel labels */
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
);
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
);
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
);
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
);
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
);
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
;
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
);
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
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
);
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
292 pa_channel_map
*pa_channel_map_parse(pa_channel_map
*map
, const char *s
);
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
;
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
;
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
;
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
;
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
;
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
;
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
;
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
;