code.delx.au - pulseaudio/blob - src/pulse/volume.h

   1 #ifndef foovolumehfoo
   2 #define foovolumehfoo
   3
   4 /***
   5   This file is part of PulseAudio.
   6
   7   Copyright 2004-2006 Lennart Poettering
   8   Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
   9
  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.1 of the License,
  13   or (at your option) any later version.
  14
  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.
  19
  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
  23   USA.
  24 ***/
  25
  26 #include <inttypes.h>
  27
  28 #include <pulse/cdecl.h>
  29 #include <pulse/gccmacro.h>
  30 #include <pulse/sample.h>
  31 #include <pulse/channelmap.h>
  32 #include <pulse/version.h>
  33
  34 /** \page volume Volume Control
  35  *
  36  * \section overv_sec Overview
  37  *
  38  * Sinks, sources, sink inputs and samples can all have their own volumes.
  39  * To deal with these, The PulseAudio libray contains a number of functions
  40  * that ease handling.
  41  *
  42  * The basic volume type in PulseAudio is the \ref pa_volume_t type. Most of
  43  * the time, applications will use the aggregated pa_cvolume structure that
  44  * can store the volume of all channels at once.
  45  *
  46  * Volumes commonly span between muted (0%), and normal (100%). It is possible
  47  * to set volumes to higher than 100%, but clipping might occur.
  48  *
  49  * \section calc_sec Calculations
  50  *
  51  * The volumes in PulseAudio are logarithmic in nature and applications
  52  * shouldn't perform calculations with them directly. Instead, they should
  53  * be converted to and from either dB or a linear scale:
  54  *
  55  * \li dB - pa_sw_volume_from_dB() / pa_sw_volume_to_dB()
  56  * \li Linear - pa_sw_volume_from_linear() / pa_sw_volume_to_linear()
  57  *
  58  * For simple multiplication, pa_sw_volume_multiply() and
  59  * pa_sw_cvolume_multiply() can be used.
  60  *
  61  * Calculations can only be reliably performed on software volumes
  62  * as it is commonly unknown what scale hardware volumes relate to.
  63  *
  64  * The functions described above are only valid when used with
  65  * software volumes. Hence it is usually a better idea to treat all
  66  * volume values as opaque with a range from PA_VOLUME_MUTED (0%) to
  67  * PA_VOLUME_NORM (100%) and to refrain from any calculations with
  68  * them.
  69  *
  70  * \section conv_sec Convenience Functions
  71  *
  72  * To handle the pa_cvolume structure, the PulseAudio library provides a
  73  * number of convenienc functions:
  74  *
  75  * \li pa_cvolume_valid() - Tests if a pa_cvolume structure is valid.
  76  * \li pa_cvolume_equal() - Tests if two pa_cvolume structures are identical.
  77  * \li pa_cvolume_channels_equal_to() - Tests if all channels of a pa_cvolume
  78  *                             structure have a given volume.
  79  * \li pa_cvolume_is_muted() - Tests if all channels of a pa_cvolume
  80  *                             structure are muted.
  81  * \li pa_cvolume_is_norm() - Tests if all channels of a pa_cvolume structure
  82  *                            are at a normal volume.
  83  * \li pa_cvolume_set() - Set all channels of a pa_cvolume structure to a
  84  *                        certain volume.
  85  * \li pa_cvolume_reset() - Set all channels of a pa_cvolume structure to a
  86  *                          normal volume.
  87  * \li pa_cvolume_mute() - Set all channels of a pa_cvolume structure to a
  88  *                         muted volume.
  89  * \li pa_cvolume_avg() - Return the average volume of all channels.
  90  * \li pa_cvolume_snprint() - Pretty print a pa_cvolume structure.
  91  */
  92
  93 /** \file
  94  * Constants and routines for volume handling */
  95
  96 PA_C_DECL_BEGIN
  97
  98 /** Volume specification:
  99  *  PA_VOLUME_MUTED: silence;
 100  * < PA_VOLUME_NORM: decreased volume;
 101  *   PA_VOLUME_NORM: normal volume;
 102  * > PA_VOLUME_NORM: increased volume */
 103 typedef uint32_t pa_volume_t;
 104
 105 /** Normal volume (100%) */
 106 #define PA_VOLUME_NORM ((pa_volume_t) 0x10000U)
 107
 108 /** Muted volume (0%) */
 109 #define PA_VOLUME_MUTED ((pa_volume_t) 0U)
 110
 111 /** A structure encapsulating a per-channel volume */
 112 typedef struct pa_cvolume {
 113     uint8_t channels;                     /**< Number of channels */
 114     pa_volume_t values[PA_CHANNELS_MAX];  /**< Per-channel volume  */
 115 } pa_cvolume;
 116
 117 /** Return non-zero when *a == *b */
 118 int pa_cvolume_equal(const pa_cvolume *a, const pa_cvolume *b) PA_GCC_PURE;
 119
 120 /** Initialize the specified volume and return a pointer to
 121  * it. The sample spec will have a defined state but
 122  * pa_cvolume_valid() will fail for it. \since 0.9.13 */
 123 pa_cvolume* pa_cvolume_init(pa_cvolume *a);
 124
 125 /** Set the volume of all channels to PA_VOLUME_NORM */
 126 #define pa_cvolume_reset(a, n) pa_cvolume_set((a), (n), PA_VOLUME_NORM)
 127
 128 /** Set the volume of all channels to PA_VOLUME_MUTED */
 129 #define pa_cvolume_mute(a, n) pa_cvolume_set((a), (n), PA_VOLUME_MUTED)
 130
 131 /** Set the volume of all channels to the specified parameter */
 132 pa_cvolume* pa_cvolume_set(pa_cvolume *a, unsigned channels, pa_volume_t v);
 133
 134 /** Maximum length of the strings returned by
 135  * pa_cvolume_snprint(). Please note that this value can change with
 136  * any release without warning and without being considered API or ABI
 137  * breakage. You should not use this definition anywhere where it
 138  * might become part of an ABI.*/
 139 #define PA_CVOLUME_SNPRINT_MAX 320
 140
 141 /** Pretty print a volume structure */
 142 char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c);
 143
 144 /** Maximum length of the strings returned by
 145  * pa_cvolume_snprint_dB(). Please note that this value can change with
 146  * any release without warning and without being considered API or ABI
 147  * breakage. You should not use this definition anywhere where it
 148  * might become part of an ABI. \since 0.9.13 */
 149 #define PA_SW_CVOLUME_SNPRINT_DB_MAX 448
 150
 151 /** Pretty print a volume structure but show dB values. \since 0.9.13 */
 152 char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c);
 153
 154 /** Maximum length of the strings returned by
 155  * pa_volume_snprint(). Please note that this value can change with
 156  * any release without warning and without being considered API or ABI
 157  * breakage. You should not use this definition anywhere where it
 158  * might become part of an ABI. \since 0.9.15 */
 159 #define PA_VOLUME_SNPRINT_MAX 10
 160
 161 /** Pretty print a volume \since 0.9.15 */
 162 char *pa_volume_snprint(char *s, size_t l, pa_volume_t v);
 163
 164 /** Maximum length of the strings returned by
 165  * pa_volume_snprint_dB(). Please note that this value can change with
 166  * any release without warning and without being considered API or ABI
 167  * breakage. You should not use this definition anywhere where it
 168  * might become part of an ABI. \since 0.9.15 */
 169 #define PA_SW_VOLUME_SNPRINT_DB_MAX 10
 170
 171 /** Pretty print a volume but show dB values. \since 0.9.15 */
 172 char *pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v);
 173
 174 /** Return the average volume of all channels */
 175 pa_volume_t pa_cvolume_avg(const pa_cvolume *a) PA_GCC_PURE;
 176
 177 /** Return the maximum volume of all channels. \since 0.9.12 */
 178 pa_volume_t pa_cvolume_max(const pa_cvolume *a) PA_GCC_PURE;
 179
 180 /** Return TRUE when the passed cvolume structure is valid, FALSE otherwise */
 181 int pa_cvolume_valid(const pa_cvolume *v) PA_GCC_PURE;
 182
 183 /** Return non-zero if the volume of all channels is equal to the specified value */
 184 int pa_cvolume_channels_equal_to(const pa_cvolume *a, pa_volume_t v) PA_GCC_PURE;
 185
 186 /** Return 1 if the specified volume has all channels muted */
 187 #define pa_cvolume_is_muted(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_MUTED)
 188
 189 /** Return 1 if the specified volume has all channels on normal level */
 190 #define pa_cvolume_is_norm(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_NORM)
 191
 192 /** Multiply two volume specifications, return the result. This uses
 193  * PA_VOLUME_NORM as neutral element of multiplication. This is only
 194  * valid for software volumes! */
 195 pa_volume_t pa_sw_volume_multiply(pa_volume_t a, pa_volume_t b) PA_GCC_CONST;
 196
 197 /** Multiply two per-channel volumes and return the result in
 198  * *dest. This is only valid for software volumes! */
 199 pa_cvolume *pa_sw_cvolume_multiply(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
 200
 201 /** Divide two volume specifications, return the result. This uses
 202  * PA_VOLUME_NORM as neutral element of division. This is only valid
 203  * for software volumes! If a division by zero is tried the result
 204  * will be 0. \since 0.9.13 */
 205 pa_volume_t pa_sw_volume_divide(pa_volume_t a, pa_volume_t b) PA_GCC_CONST;
 206
 207 /** Multiply to per-channel volumes and return the result in
 208  * *dest. This is only valid for software volumes! \since 0.9.13 */
 209 pa_cvolume *pa_sw_cvolume_divide(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
 210
 211 /** Convert a decibel value to a volume. This is only valid for software volumes! */
 212 pa_volume_t pa_sw_volume_from_dB(double f) PA_GCC_CONST;
 213
 214 /** Convert a volume to a decibel value. This is only valid for software volumes! */
 215 double pa_sw_volume_to_dB(pa_volume_t v) PA_GCC_CONST;
 216
 217 /** Convert a linear factor to a volume. This is only valid for software volumes! */
 218 pa_volume_t pa_sw_volume_from_linear(double v) PA_GCC_CONST;
 219
 220 /** Convert a volume to a linear factor. This is only valid for software volumes! */
 221 double pa_sw_volume_to_linear(pa_volume_t v) PA_GCC_CONST;
 222
 223 #ifdef INFINITY
 224 #define PA_DECIBEL_MININFTY ((double) -INFINITY)
 225 #else
 226 /** This value is used as minus infinity when using pa_volume_{to,from}_dB(). */
 227 #define PA_DECIBEL_MININFTY ((double) -200.0)
 228 #endif
 229
 230 /** Remap a volume from one channel mapping to a different channel mapping. \since 0.9.12 */
 231 pa_cvolume *pa_cvolume_remap(pa_cvolume *v, const pa_channel_map *from, const pa_channel_map *to);
 232
 233 /** Return non-zero if the specified volume is compatible with the
 234  * specified sample spec. \since 0.9.13 */
 235 int pa_cvolume_compatible(const pa_cvolume *v, const pa_sample_spec *ss) PA_GCC_PURE;
 236
 237 /** Return non-zero if the specified volume is compatible with the
 238  * specified sample spec. \since 0.9.15 */
 239 int pa_cvolume_compatible_with_channel_map(const pa_cvolume *v, const pa_channel_map *cm) PA_GCC_PURE;
 240
 241 /** Calculate a 'balance' value for the specified volume with the
 242  * specified channel map. The return value will range from -1.0f
 243  * (left) to +1.0f (right). If no balance value is applicable to this
 244  * channel map the return value will always be 0.0f. See
 245  * pa_channel_map_can_balance(). \since 0.9.15 */
 246 float pa_cvolume_get_balance(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE;
 247
 248 /** Adjust the 'balance' value for the specified volume with the
 249  * specified channel map. v will be modified in place and
 250  * returned. The balance is a value between -1.0f and +1.0f. This
 251  * operation might not be reversible! Also, after this call
 252  * pa_cvolume_get_balance() is not guaranteed to actually return the
 253  * requested balance value (e.g. when the input volume was zero anyway for
 254  * all channels). If no balance value is applicable to
 255  * this channel map the volume will not be modified. See
 256  * pa_channel_map_can_balance(). \since 0.9.15 */
 257 pa_cvolume* pa_cvolume_set_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance);
 258
 259 /** Calculate a 'fade' value (i.e. 'balance' between front and rear)
 260  * for the specified volume with the specified channel map. The return
 261  * value will range from -1.0f (rear) to +1.0f (left). If no fade
 262  * value is applicable to this channel map the return value will
 263  * always be 0.0f. See pa_channel_map_can_fade(). \since 0.9.15 */
 264 float pa_cvolume_get_fade(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE;
 265
 266 /** Adjust the 'fade' value (i.e. 'balance' between front and rear)
 267  * for the specified volume with the specified channel map. v will be
 268  * modified in place and returned. The balance is a value between
 269  * -1.0f and +1.0f. This operation might not be reversible! Also,
 270  * after this call pa_cvolume_get_fade() is not guaranteed to actually
 271  * return the requested fade value (e.g. when the input volume was
 272  * zero anyway for all channels). If no fade value is applicable to
 273  * this channel map the volume will not be modified. See
 274  * pa_channel_map_can_fade(). \since 0.9.15 */
 275 pa_cvolume* pa_cvolume_set_fade(pa_cvolume *v, const pa_channel_map *map, float new_fade);
 276
 277 /** Scale the passed pa_cvolume structure so that the maximum volume
 278  * of all channels equals max. The proportions between the channel
 279  * volumes are kept. \since 0.9.15 */
 280 pa_cvolume* pa_cvolume_scale(pa_cvolume *v, pa_volume_t max);
 281
 282 PA_C_DECL_END
 283
 284 #endif