1 #ifndef foochannelmaphfoo 2 #define foochannelmaphfoo 3 4 /* $Id: channelmap.h 1971 2007-10-28 19:13:50Z lennart $ */ 5 6 /*** 7 This file is part of PulseAudio. 8 9 Copyright 2005-2006 Lennart Poettering 10 Copyright 2006 Pierre Ossman <ossman (at) 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 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 up to 52 * six channels. 53 * 54 * \section conv_sec Convenience Functions 55 * 56 * The library contains a number of convenience functions for dealing with 57 * channel maps: 58 * 59 * \li pa_channel_map_valid() - Tests if a channel map is valid. 60 * \li pa_channel_map_equal() - Tests if two channel maps are identical. 61 * \li pa_channel_map_snprint() - Creates a textual description of a channel 62 * map. 63 */ 64 65 /** \file 66 * Constants and routines for channel mapping handling */ 67 68 PA_C_DECL_BEGIN 69 70 /** A list of channel labels */ 71 typedef enum pa_channel_position { 72 PA_CHANNEL_POSITION_INVALID = -1, 73 PA_CHANNEL_POSITION_MONO = 0, 74 75 PA_CHANNEL_POSITION_LEFT, 76 PA_CHANNEL_POSITION_RIGHT, 77 PA_CHANNEL_POSITION_CENTER, 78 79 PA_CHANNEL_POSITION_FRONT_LEFT = PA_CHANNEL_POSITION_LEFT, 80 PA_CHANNEL_POSITION_FRONT_RIGHT = PA_CHANNEL_POSITION_RIGHT, 81 PA_CHANNEL_POSITION_FRONT_CENTER = PA_CHANNEL_POSITION_CENTER, 82 83 PA_CHANNEL_POSITION_REAR_CENTER, 84 PA_CHANNEL_POSITION_REAR_LEFT, 85 PA_CHANNEL_POSITION_REAR_RIGHT, 86 87 PA_CHANNEL_POSITION_LFE, 88 PA_CHANNEL_POSITION_SUBWOOFER = PA_CHANNEL_POSITION_LFE, 89 90 PA_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER, 91 PA_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER, 92 93 PA_CHANNEL_POSITION_SIDE_LEFT, 94 PA_CHANNEL_POSITION_SIDE_RIGHT, 95 96 PA_CHANNEL_POSITION_AUX0, 97 PA_CHANNEL_POSITION_AUX1, 98 PA_CHANNEL_POSITION_AUX2, 99 PA_CHANNEL_POSITION_AUX3, 100 PA_CHANNEL_POSITION_AUX4, 101 PA_CHANNEL_POSITION_AUX5, 102 PA_CHANNEL_POSITION_AUX6, 103 PA_CHANNEL_POSITION_AUX7, 104 PA_CHANNEL_POSITION_AUX8, 105 PA_CHANNEL_POSITION_AUX9, 106 PA_CHANNEL_POSITION_AUX10, 107 PA_CHANNEL_POSITION_AUX11, 108 PA_CHANNEL_POSITION_AUX12, 109 PA_CHANNEL_POSITION_AUX13, 110 PA_CHANNEL_POSITION_AUX14, 111 PA_CHANNEL_POSITION_AUX15, 112 PA_CHANNEL_POSITION_AUX16, 113 PA_CHANNEL_POSITION_AUX17, 114 PA_CHANNEL_POSITION_AUX18, 115 PA_CHANNEL_POSITION_AUX19, 116 PA_CHANNEL_POSITION_AUX20, 117 PA_CHANNEL_POSITION_AUX21, 118 PA_CHANNEL_POSITION_AUX22, 119 PA_CHANNEL_POSITION_AUX23, 120 PA_CHANNEL_POSITION_AUX24, 121 PA_CHANNEL_POSITION_AUX25, 122 PA_CHANNEL_POSITION_AUX26, 123 PA_CHANNEL_POSITION_AUX27, 124 PA_CHANNEL_POSITION_AUX28, 125 PA_CHANNEL_POSITION_AUX29, 126 PA_CHANNEL_POSITION_AUX30, 127 PA_CHANNEL_POSITION_AUX31, 128 129 PA_CHANNEL_POSITION_TOP_CENTER, 130 131 PA_CHANNEL_POSITION_TOP_FRONT_LEFT, 132 PA_CHANNEL_POSITION_TOP_FRONT_RIGHT, 133 PA_CHANNEL_POSITION_TOP_FRONT_CENTER, 134 135 PA_CHANNEL_POSITION_TOP_REAR_LEFT, 136 PA_CHANNEL_POSITION_TOP_REAR_RIGHT, 137 PA_CHANNEL_POSITION_TOP_REAR_CENTER, 138 139 PA_CHANNEL_POSITION_MAX 140 } pa_channel_position_t; 141 142 /** A list of channel mapping definitions for pa_channel_map_init_auto() */ 143 typedef enum pa_channel_map_def { 144 PA_CHANNEL_MAP_AIFF, /**< The mapping from RFC3551, which is based on AIFF-C */ 145 PA_CHANNEL_MAP_ALSA, /**< The default mapping used by ALSA */ 146 PA_CHANNEL_MAP_AUX, /**< Only aux channels */ 147 PA_CHANNEL_MAP_WAVEEX, /**< Microsoft's WAVEFORMATEXTENSIBLE mapping */ 148 PA_CHANNEL_MAP_OSS, /**< The default channel mapping used by OSS as defined in the OSS 4.0 API specs */ 149 150 PA_CHANNEL_MAP_DEFAULT = PA_CHANNEL_MAP_AIFF /**< The default channel map */ 151 } pa_channel_map_def_t; 152 153 /** A channel map which can be used to attach labels to specific 154 * channels of a stream. These values are relevant for conversion and 155 * mixing of streams */ 156 typedef struct pa_channel_map { 157 uint8_t channels; /**< Number of channels */ 158 pa_channel_position_t map[PA_CHANNELS_MAX]; /**< Channel labels */ 159 } pa_channel_map; 160 161 /** Initialize the specified channel map and return a pointer to it */ 162 pa_channel_map* pa_channel_map_init(pa_channel_map *m); 163 164 /** Initialize the specified channel map for monoaural audio and return a pointer to it */ 165 pa_channel_map* pa_channel_map_init_mono(pa_channel_map *m); 166 167 /** Initialize the specified channel map for stereophonic audio and return a pointer to it */ 168 pa_channel_map* pa_channel_map_init_stereo(pa_channel_map *m); 169 170 /** Initialize the specified channel map for the specified number 171 * of channels using default labels and return a pointer to it. */ 172 pa_channel_map* pa_channel_map_init_auto(pa_channel_map *m, unsigned channels, pa_channel_map_def_t def); 173 174 /** Return a text label for the specified channel position */ 175 const char* pa_channel_position_to_string(pa_channel_position_t pos) PA_GCC_PURE; 176 177 /** Return a human readable text label for the specified channel position. \since 0.9.7 */ 178 const char* pa_channel_position_to_pretty_string(pa_channel_position_t pos); 179 180 /** The maximum length of strings returned by pa_channel_map_snprint() */ 181 #define PA_CHANNEL_MAP_SNPRINT_MAX 336 182 183 /** Make a humand readable string from the specified channel map */ 184 char* pa_channel_map_snprint(char *s, size_t l, const pa_channel_map *map); 185 186 /** Parse a channel position list into a channel map structure. \since 0.8.1 */ 187 pa_channel_map *pa_channel_map_parse(pa_channel_map *map, const char *s); 188 189 /** Compare two channel maps. Return 1 if both match. */ 190 int pa_channel_map_equal(const pa_channel_map *a, const pa_channel_map *b) PA_GCC_PURE; 191 192 /** Return non-zero of the specified channel map is considered valid */ 193 int pa_channel_map_valid(const pa_channel_map *map) PA_GCC_PURE; 194 195 PA_C_DECL_END 196 197 #endif 198
