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 (minimal valid) volume (0%, -inf dB) */
 110 #define PA_VOLUME_MUTED ((pa_volume_t) 0U)
 111
 112 /** Maximum valid volume we can store. \since 0.9.15 */
 113 #define PA_VOLUME_MAX ((pa_volume_t) UINT32_MAX-1)
 114
 115 /** Special 'invalid' volume. \since 0.9.16 */
 116 #define PA_VOLUME_INVALID ((pa_volume_t) UINT32_MAX)
 117
 118 /** A structure encapsulating a per-channel volume */
 119 typedef struct pa_cvolume {
 120     uint8_t channels;                     /**< Number of channels */
 121     pa_volume_t values[PA_CHANNELS_MAX];  /**< Per-channel volume  */
 122 } pa_cvolume;
 123
 124 /** Return non-zero when *a == *b */
 125 int pa_cvolume_equal(const pa_cvolume *a, const pa_cvolume *b) PA_GCC_PURE;
 126
 127 /** Initialize the specified volume and return a pointer to
 128  * it. The sample spec will have a defined state but
 129  * pa_cvolume_valid() will fail for it. \since 0.9.13 */
 130 pa_cvolume* pa_cvolume_init(pa_cvolume *a);
 131
 132 /** Set the volume of all channels to PA_VOLUME_NORM */
 133 #define pa_cvolume_reset(a, n) pa_cvolume_set((a), (n), PA_VOLUME_NORM)
 134
 135 /** Set the volume of all channels to PA_VOLUME_MUTED */
 136 #define pa_cvolume_mute(a, n) pa_cvolume_set((a), (n), PA_VOLUME_MUTED)
 137
 138 /** Set the volume of all channels to the specified parameter */
 139 pa_cvolume* pa_cvolume_set(pa_cvolume *a, unsigned channels, pa_volume_t v);
 140
 141 /** Maximum length of the strings returned by
 142  * pa_cvolume_snprint(). Please note that this value can change with
 143  * any release without warning and without being considered API or ABI
 144  * breakage. You should not use this definition anywhere where it
 145  * might become part of an ABI.*/
 146 #define PA_CVOLUME_SNPRINT_MAX 320
 147
 148 /** Pretty print a volume structure */
 149 char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c);
 150
 151 /** Maximum length of the strings returned by
 152  * pa_cvolume_snprint_dB(). Please note that this value can change with
 153  * any release without warning and without being considered API or ABI
 154  * breakage. You should not use this definition anywhere where it
 155  * might become part of an ABI. \since 0.9.13 */
 156 #define PA_SW_CVOLUME_SNPRINT_DB_MAX 448
 157
 158 /** Pretty print a volume structure but show dB values. \since 0.9.13 */
 159 char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c);
 160
 161 /** Maximum length of the strings returned by
 162  * pa_volume_snprint(). Please note that this value can change with
 163  * any release without warning and without being considered API or ABI
 164  * breakage. You should not use this definition anywhere where it
 165  * might become part of an ABI. \since 0.9.15 */
 166 #define PA_VOLUME_SNPRINT_MAX 10
 167
 168 /** Pretty print a volume \since 0.9.15 */
 169 char *pa_volume_snprint(char *s, size_t l, pa_volume_t v);
 170
 171 /** Maximum length of the strings returned by
 172  * pa_volume_snprint_dB(). Please note that this value can change with
 173  * any release without warning and without being considered API or ABI
 174  * breakage. You should not use this definition anywhere where it
 175  * might become part of an ABI. \since 0.9.15 */
 176 #define PA_SW_VOLUME_SNPRINT_DB_MAX 10
 177
 178 /** Pretty print a volume but show dB values. \since 0.9.15 */
 179 char *pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v);
 180
 181 /** Return the average volume of all channels */
 182 pa_volume_t pa_cvolume_avg(const pa_cvolume *a) PA_GCC_PURE;
 183
 184 /** Return the average volume of all channels that are included in the
 185  * specified channel map with the specified channel position mask. If
 186  * cm is NULL this call is identical to pa_cvolume_avg(). If no
 187  * channel is selected the returned value will be
 188  * PA_VOLUME_MUTED. \since 0.9.16 */
 189 pa_volume_t pa_cvolume_avg_mask(const pa_cvolume *a, const pa_channel_map *cm, pa_channel_position_mask_t mask) PA_GCC_PURE;
 190
 191 /** Return the maximum volume of all channels. \since 0.9.12 */
 192 pa_volume_t pa_cvolume_max(const pa_cvolume *a) PA_GCC_PURE;
 193
 194 /** Return the maximum volume of all channels that are included in the
 195  * specified channel map with the specified channel position mask. If
 196  * cm is NULL this call is identical to pa_cvolume_max(). If no
 197  * channel is selected the returned value will be PA_VOLUME_MUTED.
 198  * \since 0.9.16 */
 199 pa_volume_t pa_cvolume_max_mask(const pa_cvolume *a, const pa_channel_map *cm, pa_channel_position_mask_t mask) PA_GCC_PURE;
 200
 201 /** Return the minimum volume of all channels. \since 0.9.16 */
 202 pa_volume_t pa_cvolume_min(const pa_cvolume *a) PA_GCC_PURE;
 203
 204 /** Return the minimum volume of all channels that are included in the
 205  * specified channel map with the specified channel position mask. If
 206  * cm is NULL this call is identical to pa_cvolume_min(). If no
 207  * channel is selected the returned value will be PA_VOLUME_MUTED.
 208  * \since 0.9.16 */
 209 pa_volume_t pa_cvolume_min_mask(const pa_cvolume *a, const pa_channel_map *cm, pa_channel_position_mask_t mask) PA_GCC_PURE;
 210
 211 /** Return TRUE when the passed cvolume structure is valid, FALSE otherwise */
 212 int pa_cvolume_valid(const pa_cvolume *v) PA_GCC_PURE;
 213
 214 /** Return non-zero if the volume of all channels is equal to the specified value */
 215 int pa_cvolume_channels_equal_to(const pa_cvolume *a, pa_volume_t v) PA_GCC_PURE;
 216
 217 /** Return 1 if the specified volume has all channels muted */
 218 #define pa_cvolume_is_muted(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_MUTED)
 219
 220 /** Return 1 if the specified volume has all channels on normal level */
 221 #define pa_cvolume_is_norm(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_NORM)
 222
 223 /** Multiply two volume specifications, return the result. This uses
 224  * PA_VOLUME_NORM as neutral element of multiplication. This is only
 225  * valid for software volumes! */
 226 pa_volume_t pa_sw_volume_multiply(pa_volume_t a, pa_volume_t b) PA_GCC_CONST;
 227
 228 /** Multiply two per-channel volumes and return the result in
 229  * *dest. This is only valid for software volumes! a, b and dest may
 230  * point to the same structure. */
 231 pa_cvolume *pa_sw_cvolume_multiply(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
 232
 233 /** Multiply a per-channel volume with a scalar volume and return the
 234  * result in *dest. This is only valid for software volumes! a
 235  * and dest may point to the same structure. \since
 236  * 0.9.16 */
 237 pa_cvolume *pa_sw_cvolume_multiply_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b);
 238
 239 /** Divide two volume specifications, return the result. This uses
 240  * PA_VOLUME_NORM as neutral element of division. This is only valid
 241  * for software volumes! If a division by zero is tried the result
 242  * will be 0. \since 0.9.13 */
 243 pa_volume_t pa_sw_volume_divide(pa_volume_t a, pa_volume_t b) PA_GCC_CONST;
 244
 245 /** Divide two per-channel volumes and return the result in
 246  * *dest. This is only valid for software volumes! a, b
 247  * and dest may point to the same structure. \since 0.9.13 */
 248 pa_cvolume *pa_sw_cvolume_divide(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
 249
 250 /** Divide a per-channel volume by a scalar volume and return the
 251  * result in *dest. This is only valid for software volumes! a
 252  * and dest may point to the same structure. \since
 253  * 0.9.16 */
 254 pa_cvolume *pa_sw_cvolume_divide_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b);
 255
 256 /** Convert a decibel value to a volume (amplitude, not power). This is only valid for software volumes! */
 257 pa_volume_t pa_sw_volume_from_dB(double f) PA_GCC_CONST;
 258
 259 /** Convert a volume to a decibel value (amplitude, not power). This is only valid for software volumes! */
 260 double pa_sw_volume_to_dB(pa_volume_t v) PA_GCC_CONST;
 261
 262 /** Convert a linear factor to a volume. This is only valid for software volumes! */
 263 pa_volume_t pa_sw_volume_from_linear(double v) PA_GCC_CONST;
 264
 265 /** Convert a volume to a linear factor. This is only valid for software volumes! */
 266 double pa_sw_volume_to_linear(pa_volume_t v) PA_GCC_CONST;
 267
 268 #ifdef INFINITY
 269 #define PA_DECIBEL_MININFTY ((double) -INFINITY)
 270 #else
 271 /** This floor value is used as minus infinity when using pa_volume_{to,from}_dB(). */
 272 #define PA_DECIBEL_MININFTY ((double) -200.0)
 273 #endif
 274
 275 /** Remap a volume from one channel mapping to a different channel mapping. \since 0.9.12 */
 276 pa_cvolume *pa_cvolume_remap(pa_cvolume *v, const pa_channel_map *from, const pa_channel_map *to);
 277
 278 /** Return non-zero if the specified volume is compatible with the
 279  * specified sample spec. \since 0.9.13 */
 280 int pa_cvolume_compatible(const pa_cvolume *v, const pa_sample_spec *ss) PA_GCC_PURE;
 281
 282 /** Return non-zero if the specified volume is compatible with the
 283  * specified sample spec. \since 0.9.15 */
 284 int pa_cvolume_compatible_with_channel_map(const pa_cvolume *v, const pa_channel_map *cm) PA_GCC_PURE;
 285
 286 /** Calculate a 'balance' value for the specified volume with the
 287  * specified channel map. The return value will range from -1.0f
 288  * (left) to +1.0f (right). If no balance value is applicable to this
 289  * channel map the return value will always be 0.0f. See
 290  * pa_channel_map_can_balance(). \since 0.9.15 */
 291 float pa_cvolume_get_balance(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE;
 292
 293 /** Adjust the 'balance' value for the specified volume with the
 294  * specified channel map. v will be modified in place and
 295  * returned. The balance is a value between -1.0f and +1.0f. This
 296  * operation might not be reversible! Also, after this call
 297  * pa_cvolume_get_balance() is not guaranteed to actually return the
 298  * requested balance value (e.g. when the input volume was zero anyway for
 299  * all channels). If no balance value is applicable to
 300  * this channel map the volume will not be modified. See
 301  * pa_channel_map_can_balance(). \since 0.9.15 */
 302 pa_cvolume* pa_cvolume_set_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance);
 303
 304 /** Calculate a 'fade' value (i.e. 'balance' between front and rear)
 305  * for the specified volume with the specified channel map. The return
 306  * value will range from -1.0f (rear) to +1.0f (left). If no fade
 307  * value is applicable to this channel map the return value will
 308  * always be 0.0f. See pa_channel_map_can_fade(). \since 0.9.15 */
 309 float pa_cvolume_get_fade(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE;
 310
 311 /** Adjust the 'fade' value (i.e. 'balance' between front and rear)
 312  * for the specified volume with the specified channel map. v will be
 313  * modified in place and returned. The balance is a value between
 314  * -1.0f and +1.0f. This operation might not be reversible! Also,
 315  * after this call pa_cvolume_get_fade() is not guaranteed to actually
 316  * return the requested fade value (e.g. when the input volume was
 317  * zero anyway for all channels). If no fade value is applicable to
 318  * this channel map the volume will not be modified. See
 319  * pa_channel_map_can_fade(). \since 0.9.15 */
 320 pa_cvolume* pa_cvolume_set_fade(pa_cvolume *v, const pa_channel_map *map, float new_fade);
 321
 322 /** Scale the passed pa_cvolume structure so that the maximum volume
 323  * of all channels equals max. The proportions between the channel
 324  * volumes are kept. \since 0.9.15 */
 325 pa_cvolume* pa_cvolume_scale(pa_cvolume *v, pa_volume_t max);
 326
 327 /** Scale the passed pa_cvolume structure so that the maximum volume
 328  * of all channels selected via cm/mask equals max. This also modifies
 329  * the volume of those channels that are unmasked. The proportions
 330  * between the channel volumes are kept. \since 0.9.16 */
 331 pa_cvolume* pa_cvolume_scale_mask(pa_cvolume *v, pa_volume_t max, pa_channel_map *cm, pa_channel_position_mask_t mask);
 332
 333 /** Set the passed volume to all channels at the specified channel
 334  * position. Will return the updated volume struct, or NULL if there
 335  * is no channel at the position specified. You can check if a channel
 336  * map includes a specific position by calling
 337  * pa_channel_map_has_position(). \since 0.9.16 */
 338 pa_cvolume* pa_cvolume_set_position(pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t, pa_volume_t v);
 339
 340 /** Get the maximum volume of all channels at the specified channel
 341  * position. Will return 0 if there is no channel at the position
 342  * specified. You can check if a channel map includes a specific
 343  * position by calling pa_channel_map_has_position(). \since 0.9.16 */
 344 pa_volume_t pa_cvolume_get_position(pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t) PA_GCC_PURE;
 345
 346 /** This goes through all channels in a and b and sets the
 347  * corresponding channel in dest to the greater volume of both. a, b
 348  * and dest may point to the same structure. \since 0.9.16 */
 349 pa_cvolume* pa_cvolume_merge(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
 350
 351 /** Increase the volume passed in by 'inc', but not exceeding 'limit'.
 352  * The proportions between the channels are kept. \since 0.9.19 */
 353 pa_cvolume* pa_cvolume_inc_clamp(pa_cvolume *v, pa_volume_t inc, pa_volume_t limit);
 354
 355 /** Increase the volume passed in by 'inc'. The proportions between
 356  * the channels are kept. \since 0.9.16 */
 357 pa_cvolume* pa_cvolume_inc(pa_cvolume *v, pa_volume_t inc);
 358
 359 /** Increase the volume passed in by 'inc'. The proportions between
 360  * the channels are kept. \since 0.9.16 */
 361 pa_cvolume* pa_cvolume_dec(pa_cvolume *v, pa_volume_t dec);
 362
 363 PA_C_DECL_END
 364
 365 #endif