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>
30 /** \page channelmap Channel Maps
32 * \section overv_sec Overview
34 * Channel maps provide a way to associate channels in a stream with a
35 * specific speaker position. This relieves applications of having to
36 * make sure their channel order is identical to the final output.
38 * \section init_sec Initialisation
40 * A channel map consists of an array of \ref pa_channel_position values,
41 * one for each channel. This array is stored together with a channel count
42 * in a pa_channel_map structure.
44 * Before filling the structure, the application must initialise it using
45 * pa_channel_map_init(). There are also a number of convenience functions
46 * for standard channel mappings:
48 * \li pa_channel_map_init_mono() - Create a channel map with only mono audio.
49 * \li pa_channel_map_init_stereo() - Create a standard stereo mapping.
50 * \li pa_channel_map_init_auto() - Create a standard channel map for up to
53 * \section conv_sec Convenience Functions
55 * The library contains a number of convenience functions for dealing with
58 * \li pa_channel_map_valid() - Tests if a channel map is valid.
59 * \li pa_channel_map_equal() - Tests if two channel maps are identical.
60 * \li pa_channel_map_snprint() - Creates a textual description of a channel
65 * Constants and routines for channel mapping handling */
69 /** A list of channel labels */
70 typedef enum pa_channel_position
{
71 PA_CHANNEL_POSITION_INVALID
= -1,
72 PA_CHANNEL_POSITION_MONO
= 0,
74 PA_CHANNEL_POSITION_LEFT
,
75 PA_CHANNEL_POSITION_RIGHT
,
76 PA_CHANNEL_POSITION_CENTER
,
78 PA_CHANNEL_POSITION_FRONT_LEFT
= PA_CHANNEL_POSITION_LEFT
,
79 PA_CHANNEL_POSITION_FRONT_RIGHT
= PA_CHANNEL_POSITION_RIGHT
,
80 PA_CHANNEL_POSITION_FRONT_CENTER
= PA_CHANNEL_POSITION_CENTER
,
82 PA_CHANNEL_POSITION_REAR_CENTER
,
83 PA_CHANNEL_POSITION_REAR_LEFT
,
84 PA_CHANNEL_POSITION_REAR_RIGHT
,
86 PA_CHANNEL_POSITION_LFE
,
87 PA_CHANNEL_POSITION_SUBWOOFER
= PA_CHANNEL_POSITION_LFE
,
89 PA_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER
,
90 PA_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER
,
92 PA_CHANNEL_POSITION_SIDE_LEFT
,
93 PA_CHANNEL_POSITION_SIDE_RIGHT
,
95 PA_CHANNEL_POSITION_AUX0
,
96 PA_CHANNEL_POSITION_AUX1
,
97 PA_CHANNEL_POSITION_AUX2
,
98 PA_CHANNEL_POSITION_AUX3
,
99 PA_CHANNEL_POSITION_AUX4
,
100 PA_CHANNEL_POSITION_AUX5
,
101 PA_CHANNEL_POSITION_AUX6
,
102 PA_CHANNEL_POSITION_AUX7
,
103 PA_CHANNEL_POSITION_AUX8
,
104 PA_CHANNEL_POSITION_AUX9
,
105 PA_CHANNEL_POSITION_AUX10
,
106 PA_CHANNEL_POSITION_AUX11
,
107 PA_CHANNEL_POSITION_AUX12
,
108 PA_CHANNEL_POSITION_AUX13
,
109 PA_CHANNEL_POSITION_AUX14
,
110 PA_CHANNEL_POSITION_AUX15
,
111 PA_CHANNEL_POSITION_AUX16
,
112 PA_CHANNEL_POSITION_AUX17
,
113 PA_CHANNEL_POSITION_AUX18
,
114 PA_CHANNEL_POSITION_AUX19
,
115 PA_CHANNEL_POSITION_AUX20
,
116 PA_CHANNEL_POSITION_AUX21
,
117 PA_CHANNEL_POSITION_AUX22
,
118 PA_CHANNEL_POSITION_AUX23
,
119 PA_CHANNEL_POSITION_AUX24
,
120 PA_CHANNEL_POSITION_AUX25
,
121 PA_CHANNEL_POSITION_AUX26
,
122 PA_CHANNEL_POSITION_AUX27
,
123 PA_CHANNEL_POSITION_AUX28
,
124 PA_CHANNEL_POSITION_AUX29
,
125 PA_CHANNEL_POSITION_AUX30
,
126 PA_CHANNEL_POSITION_AUX31
,
128 PA_CHANNEL_POSITION_TOP_CENTER
,
130 PA_CHANNEL_POSITION_TOP_FRONT_LEFT
,
131 PA_CHANNEL_POSITION_TOP_FRONT_RIGHT
,
132 PA_CHANNEL_POSITION_TOP_FRONT_CENTER
,
134 PA_CHANNEL_POSITION_TOP_REAR_LEFT
,
135 PA_CHANNEL_POSITION_TOP_REAR_RIGHT
,
136 PA_CHANNEL_POSITION_TOP_REAR_CENTER
,
138 PA_CHANNEL_POSITION_MAX
139 } pa_channel_position_t
;
141 /** A list of channel mapping definitions for pa_channel_map_init_auto() */
142 typedef enum pa_channel_map_def
{
143 PA_CHANNEL_MAP_AIFF
, /**< The mapping from RFC3551, which is based on AIFF-C */
144 PA_CHANNEL_MAP_ALSA
, /**< The default mapping used by ALSA */
145 PA_CHANNEL_MAP_AUX
, /**< Only aux channels */
146 PA_CHANNEL_MAP_WAVEEX
, /**< Microsoft's WAVEFORMATEXTENSIBLE mapping */
147 PA_CHANNEL_MAP_OSS
, /**< The default channel mapping used by OSS as defined in the OSS 4.0 API specs */
149 PA_CHANNEL_MAP_DEFAULT
= PA_CHANNEL_MAP_AIFF
/**< The default channel map */
150 } pa_channel_map_def_t
;
152 /** A channel map which can be used to attach labels to specific
153 * channels of a stream. These values are relevant for conversion and
154 * mixing of streams */
155 typedef struct pa_channel_map
{
156 uint8_t channels
; /**< Number of channels */
157 pa_channel_position_t map
[PA_CHANNELS_MAX
]; /**< Channel labels */
160 /** Initialize the specified channel map and return a pointer to it */
161 pa_channel_map
* pa_channel_map_init(pa_channel_map
*m
);
163 /** Initialize the specified channel map for monoaural audio and return a pointer to it */
164 pa_channel_map
* pa_channel_map_init_mono(pa_channel_map
*m
);
166 /** Initialize the specified channel map for stereophonic audio and return a pointer to it */
167 pa_channel_map
* pa_channel_map_init_stereo(pa_channel_map
*m
);
169 /** Initialize the specified channel map for the specified number
170 * of channels using default labels and return a pointer to it. */
171 pa_channel_map
* pa_channel_map_init_auto(pa_channel_map
*m
, unsigned channels
, pa_channel_map_def_t def
);
173 /** Return a text label for the specified channel position */
174 const char* pa_channel_position_to_string(pa_channel_position_t pos
) PA_GCC_PURE
;
176 /** Return a human readable text label for the specified channel position. \since 0.9.7 */
177 const char* pa_channel_position_to_pretty_string(pa_channel_position_t pos
);
179 /** The maximum length of strings returned by pa_channel_map_snprint() */
180 #define PA_CHANNEL_MAP_SNPRINT_MAX 336
182 /** Make a humand readable string from the specified channel map */
183 char* pa_channel_map_snprint(char *s
, size_t l
, const pa_channel_map
*map
);
185 /** Parse a channel position list into a channel map structure. */
186 pa_channel_map
*pa_channel_map_parse(pa_channel_map
*map
, const char *s
);
188 /** Compare two channel maps. Return 1 if both match. */
189 int pa_channel_map_equal(const pa_channel_map
*a
, const pa_channel_map
*b
) PA_GCC_PURE
;
191 /** Return non-zero of the specified channel map is considered valid */
192 int pa_channel_map_valid(const pa_channel_map
*map
) PA_GCC_PURE
;