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