code.delx.au - pulseaudio/blob - src/polyp/channelmap.h

   1 #ifndef foochannelmaphfoo
   2 #define foochannelmaphfoo
   3
   4 /* $Id$ */
   5
   6 /***
   7   This file is part of polypaudio.
   8
   9   polypaudio is free software; you can redistribute it and/or modify
  10   it under the terms of the GNU Lesser General Public License as published
  11   by the Free Software Foundation; either version 2 of the License,
  12   or (at your option) any later version.
  13
  14   polypaudio is distributed in the hope that it will be useful, but
  15   WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17   General Public License for more details.
  18
  19   You should have received a copy of the GNU Lesser General Public License
  20   along with polypaudio; if not, write to the Free Software
  21   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
  22   USA.
  23 ***/
  24
  25 #include <polyp/sample.h>
  26 #include <polyp/cdecl.h>
  27
  28 /** \page channelmap Channel maps
  29  *
  30  * \section overv_sec Overview
  31  *
  32  * Channel maps provide a way to associate channels in a stream with a
  33  * specific speaker position. This relieves applications of having to
  34  * make sure their channel order is identical to the final output.
  35  *
  36  * \section init_sec Initialisation
  37  *
  38  * A channel map consists of an array of \ref pa_channel_position values,
  39  * one for each channel. This array is stored together with a channel count
  40  * in a pa_channel_map structure.
  41  *
  42  * Before filling the structure, the application must initialise it using
  43  * pa_channel_map_init(). There are also a number of convenience functions
  44  * for standard channel mappings:
  45  *
  46  * \li pa_channel_map_init_mono() - Create a channel map with only mono audio.
  47  * \li pa_channel_map_init_stereo() - Create a standard stereo mapping.
  48  * \li pa_channel_map_init_auto() - Create a standard channel map for up to
  49  *                                  six channels.
  50  *
  51  * \section conv_sec Convenience functions
  52  *
  53  * The library contains a number of convenience functions for dealing with
  54  * channel maps:
  55  *
  56  * \li pa_channel_map_valid() - Tests if a channel map is valid.
  57  * \li pa_channel_map_equal() - Tests if two channel maps are identical.
  58  * \li pa_channel_map_snprint() - Creates a textual description of a channel
  59  *                                map.
  60  */
  61
  62 /** \file
  63  * Constants and routines for channel mapping handling */
  64
  65 PA_C_DECL_BEGIN
  66
  67 /** A list of channel labels */
  68 typedef enum pa_channel_position {
  69     PA_CHANNEL_POSITION_INVALID = -1,
  70     PA_CHANNEL_POSITION_MONO = 0,
  71
  72     PA_CHANNEL_POSITION_LEFT,
  73     PA_CHANNEL_POSITION_RIGHT,
  74     PA_CHANNEL_POSITION_CENTER,
  75
  76     PA_CHANNEL_POSITION_FRONT_LEFT = PA_CHANNEL_POSITION_LEFT,
  77     PA_CHANNEL_POSITION_FRONT_RIGHT = PA_CHANNEL_POSITION_RIGHT,
  78     PA_CHANNEL_POSITION_FRONT_CENTER = PA_CHANNEL_POSITION_CENTER,
  79
  80     PA_CHANNEL_POSITION_REAR_CENTER,
  81     PA_CHANNEL_POSITION_REAR_LEFT,
  82     PA_CHANNEL_POSITION_REAR_RIGHT,
  83
  84     PA_CHANNEL_POSITION_LFE,
  85     PA_CHANNEL_POSITION_SUBWOOFER = PA_CHANNEL_POSITION_LFE,
  86
  87     PA_CHANNEL_POSITION_FRONT_LEFT_OF_CENTER,
  88     PA_CHANNEL_POSITION_FRONT_RIGHT_OF_CENTER,
  89
  90     PA_CHANNEL_POSITION_SIDE_LEFT,
  91     PA_CHANNEL_POSITION_SIDE_RIGHT,
  92
  93     PA_CHANNEL_POSITION_AUX0,
  94     PA_CHANNEL_POSITION_AUX1,
  95     PA_CHANNEL_POSITION_AUX2,
  96     PA_CHANNEL_POSITION_AUX3,
  97     PA_CHANNEL_POSITION_AUX4,
  98     PA_CHANNEL_POSITION_AUX5,
  99     PA_CHANNEL_POSITION_AUX6,
 100     PA_CHANNEL_POSITION_AUX7,
 101     PA_CHANNEL_POSITION_AUX8,
 102     PA_CHANNEL_POSITION_AUX9,
 103     PA_CHANNEL_POSITION_AUX10,
 104     PA_CHANNEL_POSITION_AUX11,
 105     PA_CHANNEL_POSITION_AUX12,
 106     PA_CHANNEL_POSITION_AUX13,
 107     PA_CHANNEL_POSITION_AUX14,
 108     PA_CHANNEL_POSITION_AUX15,
 109
 110     PA_CHANNEL_POSITION_MAX
 111 } pa_channel_position_t;
 112
 113 /** A channel map which can be used to attach labels to specific
 114  * channels of a stream. These values are relevant for conversion and
 115  * mixing of streams */
 116 typedef struct pa_channel_map {
 117     uint8_t channels; /**< Number of channels */
 118     pa_channel_position_t map[PA_CHANNELS_MAX]; /**< Channel labels */
 119 } pa_channel_map;
 120
 121 /** Initialize the specified channel map and return a pointer to it */
 122 pa_channel_map* pa_channel_map_init(pa_channel_map *m);
 123
 124 /** Initialize the specified channel map for monoaural audio and return a pointer to it */
 125 pa_channel_map* pa_channel_map_init_mono(pa_channel_map *m);
 126
 127 /** Initialize the specified channel map for stereophonic audio and return a pointer to it */
 128 pa_channel_map* pa_channel_map_init_stereo(pa_channel_map *m);
 129
 130 /** Initialize the specified channel map for the specified number of channels using default labels and return a pointer to it */
 131 pa_channel_map* pa_channel_map_init_auto(pa_channel_map *m, unsigned channels);
 132
 133 /** Return a text label for the specified channel position */
 134 const char* pa_channel_position_to_string(pa_channel_position_t pos);
 135
 136 /** The maximum length of strings returned by pa_channel_map_snprint() */
 137 #define PA_CHANNEL_MAP_SNPRINT_MAX 64
 138
 139 /** Make a humand readable string from the specified channel map */
 140 char* pa_channel_map_snprint(char *s, size_t l, const pa_channel_map *map);
 141
 142 /** Compare two channel maps. Return 1 if both match. */
 143 int pa_channel_map_equal(const pa_channel_map *a, const pa_channel_map *b);
 144
 145 /** Return non-zero of the specified channel map is considered valid */
 146 int pa_channel_map_valid(const pa_channel_map *map);
 147
 148 PA_C_DECL_END
 149
 150 #endif