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