1 #ifndef foochannelmaphfoo
2 #define foochannelmaphfoo
7 This file is part of PulseAudio.
9 Copyright 2005-2006 Lennart Poettering
10 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
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.
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.
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
28 #include <pulse/sample.h>
29 #include <pulse/cdecl.h>
30 #include <pulse/gccmacro.h>
32 /** \page channelmap Channel Maps
34 * \section overv_sec Overview
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.
40 * \section init_sec Initialisation
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.
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:
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
55 * \section conv_sec Convenience Functions
57 * The library contains a number of convenience functions for dealing with
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
67 * Constants and routines for channel mapping handling */
71 /** A list of channel labels */
72 typedef enum pa_channel_position {
73 PA_CHANNEL_POSITION_INVALID = -1,
74 PA_CHANNEL_POSITION_MONO = 0,
76 PA_CHANNEL_POSITION_LEFT,
77 PA_CHANNEL_POSITION_RIGHT,
78 PA_CHANNEL_POSITION_CENTER,
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,
84 PA_CHANNEL_POSITION_REAR_CENTER,
85 PA_CHANNEL_POSITION_REAR_LEFT,
86 PA_CHANNEL_POSITION_REAR_RIGHT,
88 PA_CHANNEL_POSITION_LFE,
89 PA_CHANNEL_POSITION_SUBWOOFER = PA_CHANNEL_POSITION_LFE,
91 PA_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER,
92 PA_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER,
94 PA_CHANNEL_POSITION_SIDE_LEFT,
95 PA_CHANNEL_POSITION_SIDE_RIGHT,
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,
130 PA_CHANNEL_POSITION_TOP_CENTER,
132 PA_CHANNEL_POSITION_TOP_FRONT_LEFT,
133 PA_CHANNEL_POSITION_TOP_FRONT_RIGHT,
134 PA_CHANNEL_POSITION_TOP_FRONT_CENTER,
136 PA_CHANNEL_POSITION_TOP_REAR_LEFT,
137 PA_CHANNEL_POSITION_TOP_REAR_RIGHT,
138 PA_CHANNEL_POSITION_TOP_REAR_CENTER,
140 PA_CHANNEL_POSITION_MAX
141 } pa_channel_position_t;
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 */
151 PA_CHANNEL_MAP_DEFAULT = PA_CHANNEL_MAP_AIFF /**< The default channel map */
152 } pa_channel_map_def_t;
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 */
162 /** Initialize the specified channel map and return a pointer to it */
163 pa_channel_map* pa_channel_map_init(pa_channel_map *m);
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);
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);
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);
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;
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);
181 /** The maximum length of strings returned by pa_channel_map_snprint() */
182 #define PA_CHANNEL_MAP_SNPRINT_MAX 336
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);
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);
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;
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;