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, see <http://www.gnu.org/licenses/>. 22 ***/ 23 24 #include <inttypes.h> 25 #include <limits.h> 26 27 #include <pulse/cdecl.h> 28 #include <pulse/gccmacro.h> 29 #include <pulse/sample.h> 30 #include <pulse/channelmap.h> 31 #include <pulse/version.h> 32 33 /** \page volume Volume Control 34 * 35 * \section overv_sec Overview 36 * 37 * Sinks, sources, sink inputs, source outputs and samples can all have their 38 * own volumes. To deal with these, The PulseAudio library contains a number of 39 * functions that ease handling. 40 * 41 * The basic volume type in PulseAudio is the \ref pa_volume_t type. Most of 42 * the time, applications will use the aggregated pa_cvolume structure that 43 * can store the volume of all channels at once. 44 * 45 * Volumes commonly span between muted (0%), and normal (100%). It is possible 46 * to set volumes to higher than 100%, but clipping might occur. 47 * 48 * There is no single well-defined meaning attached to the 100% volume for a 49 * sink input. In fact, it depends on the server configuration. With flat 50 * volumes enabled, it means the maximum volume that the sound hardware is 51 * capable of, which is usually so high that you absolutely must not set sink 52 * input volume to 100% unless the the user explicitly requests that (note that 53 * usually you shouldn't set the volume anyway if the user doesn't explicitly 54 * request it, instead, let PulseAudio decide the volume for the sink input). 55 * With flat volumes disabled the sink input volume is relative to the sink 56 * volume, so 100% sink input volume means that the sink input is played at the 57 * current sink volume level. In this case 100% is often a good default volume 58 * for a sink input, although you still should let PulseAudio decide the 59 * default volume. It is possible to figure out whether flat volume mode is in 60 * effect for a given sink by calling pa_context_get_sink_info_by_name(). 61 * 62 * \section calc_sec Calculations 63 * 64 * The volumes in PulseAudio are cubic in nature and applications shouldn't 65 * perform calculations with them directly. Instead, they should be converted 66 * to and from either dB or a linear scale: 67 * 68 * \li dB - pa_sw_volume_from_dB() / pa_sw_volume_to_dB() 69 * \li Linear - pa_sw_volume_from_linear() / pa_sw_volume_to_linear() 70 * 71 * For simple multiplication, pa_sw_volume_multiply() and 72 * pa_sw_cvolume_multiply() can be used. 73 * 74 * It's often unknown what scale hardware volumes relate to. Don't use the 75 * above functions on sink and source volumes, unless the sink or source in 76 * question has the PA_SINK_DECIBEL_VOLUME or PA_SOURCE_DECIBEL_VOLUME flag 77 * set. The conversion functions are rarely needed anyway, most of the time 78 * it's sufficient to treat all volumes as opaque with a range from 79 * PA_VOLUME_MUTED (0%) to PA_VOLUME_NORM (100%). 80 * 81 * \section conv_sec Convenience Functions 82 * 83 * To handle the pa_cvolume structure, the PulseAudio library provides a 84 * number of convenience functions: 85 * 86 * \li pa_cvolume_valid() - Tests if a pa_cvolume structure is valid. 87 * \li pa_cvolume_equal() - Tests if two pa_cvolume structures are identical. 88 * \li pa_cvolume_channels_equal_to() - Tests if all channels of a pa_cvolume 89 * structure have a given volume. 90 * \li pa_cvolume_is_muted() - Tests if all channels of a pa_cvolume 91 * structure are muted. 92 * \li pa_cvolume_is_norm() - Tests if all channels of a pa_cvolume structure 93 * are at a normal volume. 94 * \li pa_cvolume_set() - Set the first n channels of a pa_cvolume structure to 95 * a certain volume. 96 * \li pa_cvolume_reset() - Set the first n channels of a pa_cvolume structure 97 * to a normal volume. 98 * \li pa_cvolume_mute() - Set the first n channels of a pa_cvolume structure 99 * to a muted volume. 100 * \li pa_cvolume_avg() - Return the average volume of all channels. 101 * \li pa_cvolume_snprint() - Pretty print a pa_cvolume structure. 102 */ 103 104 /** \file 105 * Constants and routines for volume handling 106 * 107 * See also \subpage volume 108 */ 109 110 PA_C_DECL_BEGIN 111 112 /** Volume specification: 113 * PA_VOLUME_MUTED: silence; 114 * < PA_VOLUME_NORM: decreased volume; 115 * PA_VOLUME_NORM: normal volume; 116 * > PA_VOLUME_NORM: increased volume */ 117 typedef uint32_t pa_volume_t; 118 119 /** Normal volume (100%, 0 dB) */ 120 #define PA_VOLUME_NORM ((pa_volume_t) 0x10000U) 121 122 /** Muted (minimal valid) volume (0%, -inf dB) */ 123 #define PA_VOLUME_MUTED ((pa_volume_t) 0U) 124 125 /** Maximum valid volume we can store. \since 0.9.15 */ 126 #define PA_VOLUME_MAX ((pa_volume_t) UINT32_MAX/2) 127 128 /** Recommended maximum volume to show in user facing UIs. 129 * Note: UIs should deal gracefully with volumes greater than this value 130 * and not cause feedback loops etc. - i.e. if the volume is more than 131 * this, the UI should not limit it and push the limited value back to 132 * the server. \since 0.9.23 */ 133 #define PA_VOLUME_UI_MAX (pa_sw_volume_from_dB(+11.0)) 134 135 /** Special 'invalid' volume. \since 0.9.16 */ 136 #define PA_VOLUME_INVALID ((pa_volume_t) UINT32_MAX) 137 138 /** Check if volume is valid. \since 1.0 */ 139 #define PA_VOLUME_IS_VALID(v) ((v) <= PA_VOLUME_MAX) 140 141 /** Clamp volume to the permitted range. \since 1.0 */ 142 #define PA_CLAMP_VOLUME(v) (PA_CLAMP_UNLIKELY((v), PA_VOLUME_MUTED, PA_VOLUME_MAX)) 143 144 /** A structure encapsulating a per-channel volume */ 145 typedef struct pa_cvolume { 146 uint8_t channels; /**< Number of channels */ 147 pa_volume_t values[PA_CHANNELS_MAX]; /**< Per-channel volume */ 148 } pa_cvolume; 149 150 /** Return non-zero when *a == *b, checking that both a and b 151 * have the same number of channels and that the volumes of 152 * channels in a equal those in b. */ 153 int pa_cvolume_equal(const pa_cvolume *a, const pa_cvolume *b) PA_GCC_PURE; 154 155 /** Initialize the specified volume and return a pointer to 156 * it. The sample spec will have a defined state but 157 * pa_cvolume_valid() will fail for it. \since 0.9.13 */ 158 pa_cvolume* pa_cvolume_init(pa_cvolume *a); 159 160 /** Set the volume of the first n channels to PA_VOLUME_NORM */ 161 #define pa_cvolume_reset(a, n) pa_cvolume_set((a), (n), PA_VOLUME_NORM) 162 163 /** Set the volume of the first n channels to PA_VOLUME_MUTED */ 164 #define pa_cvolume_mute(a, n) pa_cvolume_set((a), (n), PA_VOLUME_MUTED) 165 166 /** Set the volume of the specified number of channels to the volume v */ 167 pa_cvolume* pa_cvolume_set(pa_cvolume *a, unsigned channels, pa_volume_t v); 168 169 /** Maximum length of the strings returned by 170 * pa_cvolume_snprint(). Please note that this value can change with 171 * any release without warning and without being considered API or ABI 172 * breakage. You should not use this definition anywhere where it 173 * might become part of an ABI.*/ 174 #define PA_CVOLUME_SNPRINT_MAX 320 175 176 /** Pretty print a volume structure. Returns \a s. */ 177 char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c); 178 179 /** Maximum length of the strings returned by 180 * pa_sw_cvolume_snprint_dB(). Please note that this value can change with 181 * any release without warning and without being considered API or ABI 182 * breakage. You should not use this definition anywhere where it 183 * might become part of an ABI. \since 0.9.13 */ 184 #define PA_SW_CVOLUME_SNPRINT_DB_MAX 448 185 186 /** Pretty print a volume structure, showing dB values. Returns \a s. \since 0.9.13 */ 187 char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c); 188 189 /** Maximum length of the strings returned by pa_cvolume_snprint_verbose(). 190 * Please note that this value can change with any release without warning and 191 * without being considered API or ABI breakage. You should not use this 192 * definition anywhere where it might become part of an ABI. \since 5.0 */ 193 #define PA_CVOLUME_SNPRINT_VERBOSE_MAX 1984 194 195 /** Pretty print a volume structure in a verbose way. The volume for each 196 * channel is printed in several formats: the raw pa_volume_t value, 197 * percentage, and if print_dB is non-zero, also the dB value. If map is not 198 * NULL, the channel names will be printed. Returns \a s. \since 5.0 */ 199 char *pa_cvolume_snprint_verbose(char *s, size_t l, const pa_cvolume *c, const pa_channel_map *map, int print_dB); 200 201 /** Maximum length of the strings returned by 202 * pa_volume_snprint(). Please note that this value can change with 203 * any release without warning and without being considered API or ABI 204 * breakage. You should not use this definition anywhere where it 205 * might become part of an ABI. \since 0.9.15 */ 206 #define PA_VOLUME_SNPRINT_MAX 10 207 208 /** Pretty print a volume. Returns \a s. \since 0.9.15 */ 209 char *pa_volume_snprint(char *s, size_t l, pa_volume_t v); 210 211 /** Maximum length of the strings returned by 212 * pa_sw_volume_snprint_dB(). Please note that this value can change with 213 * any release without warning and without being considered API or ABI 214 * breakage. You should not use this definition anywhere where it 215 * might become part of an ABI. \since 0.9.15 */ 216 #define PA_SW_VOLUME_SNPRINT_DB_MAX 11 217 218 /** Pretty print a volume but show dB values. Returns \a s. \since 0.9.15 */ 219 char *pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v); 220 221 /** Maximum length of the strings returned by pa_volume_snprint_verbose(). 222 * Please note that this value can change with any release without warning and 223 * withou being considered API or ABI breakage. You should not use this 224 * definition anywhere where it might become part of an ABI. \since 5.0 */ 225 #define PA_VOLUME_SNPRINT_VERBOSE_MAX 35 226 227 /** Pretty print a volume in a verbose way. The volume is printed in several 228 * formats: the raw pa_volume_t value, percentage, and if print_dB is non-zero, 229 * also the dB value. Returns \a s. \since 5.0 */ 230 char *pa_volume_snprint_verbose(char *s, size_t l, pa_volume_t v, int print_dB); 231 232 /** Return the average volume of all channels */ 233 pa_volume_t pa_cvolume_avg(const pa_cvolume *a) PA_GCC_PURE; 234 235 /** Return the average volume of all channels that are included in the 236 * specified channel map with the specified channel position mask. If 237 * cm is NULL this call is identical to pa_cvolume_avg(). If no 238 * channel is selected the returned value will be 239 * PA_VOLUME_MUTED. \since 0.9.16 */ 240 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; 241 242 /** Return the maximum volume of all channels. \since 0.9.12 */ 243 pa_volume_t pa_cvolume_max(const pa_cvolume *a) PA_GCC_PURE; 244 245 /** Return the maximum volume of all channels that are included in the 246 * specified channel map with the specified channel position mask. If 247 * cm is NULL this call is identical to pa_cvolume_max(). If no 248 * channel is selected the returned value will be PA_VOLUME_MUTED. 249 * \since 0.9.16 */ 250 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; 251 252 /** Return the minimum volume of all channels. \since 0.9.16 */ 253 pa_volume_t pa_cvolume_min(const pa_cvolume *a) PA_GCC_PURE; 254 255 /** Return the minimum volume of all channels that are included in the 256 * specified channel map with the specified channel position mask. If 257 * cm is NULL this call is identical to pa_cvolume_min(). If no 258 * channel is selected the returned value will be PA_VOLUME_MUTED. 259 * \since 0.9.16 */ 260 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; 261 262 /** Return non-zero when the passed cvolume structure is valid */ 263 int pa_cvolume_valid(const pa_cvolume *v) PA_GCC_PURE; 264 265 /** Return non-zero if the volume of all channels is equal to the specified value */ 266 int pa_cvolume_channels_equal_to(const pa_cvolume *a, pa_volume_t v) PA_GCC_PURE; 267 268 /** Return 1 if the specified volume has all channels muted */ 269 #define pa_cvolume_is_muted(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_MUTED) 270 271 /** Return 1 if the specified volume has all channels on normal level */ 272 #define pa_cvolume_is_norm(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_NORM) 273 274 /** Multiply two volume specifications, return the result. This uses 275 * PA_VOLUME_NORM as neutral element of multiplication. This is only 276 * valid for software volumes! */ 277 pa_volume_t pa_sw_volume_multiply(pa_volume_t a, pa_volume_t b) PA_GCC_CONST; 278 279 /** Multiply two per-channel volumes and return the result in 280 * *dest. This is only valid for software volumes! a, b and dest may 281 * point to the same structure. Returns dest, or NULL on error. */ 282 pa_cvolume *pa_sw_cvolume_multiply(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b); 283 284 /** Multiply a per-channel volume with a scalar volume and return the 285 * result in *dest. This is only valid for software volumes! a 286 * and dest may point to the same structure. Returns dest, or NULL on error. 287 * \since 0.9.16 */ 288 pa_cvolume *pa_sw_cvolume_multiply_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b); 289 290 /** Divide two volume specifications, return the result. This uses 291 * PA_VOLUME_NORM as neutral element of division. This is only valid 292 * for software volumes! If a division by zero is tried the result 293 * will be 0. \since 0.9.13 */ 294 pa_volume_t pa_sw_volume_divide(pa_volume_t a, pa_volume_t b) PA_GCC_CONST; 295 296 /** Divide two per-channel volumes and return the result in 297 * *dest. This is only valid for software volumes! a, b 298 * and dest may point to the same structure. Returns dest, 299 * or NULL on error. \since 0.9.13 */ 300 pa_cvolume *pa_sw_cvolume_divide(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b); 301 302 /** Divide a per-channel volume by a scalar volume and return the 303 * result in *dest. This is only valid for software volumes! a 304 * and dest may point to the same structure. Returns dest, 305 * or NULL on error. \since 0.9.16 */ 306 pa_cvolume *pa_sw_cvolume_divide_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b); 307 308 /** Convert a decibel value to a volume (amplitude, not power). This is only valid for software volumes! */ 309 pa_volume_t pa_sw_volume_from_dB(double f) PA_GCC_CONST; 310 311 /** Convert a volume to a decibel value (amplitude, not power). This is only valid for software volumes! */ 312 double pa_sw_volume_to_dB(pa_volume_t v) PA_GCC_CONST; 313 314 /** Convert a linear factor to a volume. 0.0 and less is muted while 315 * 1.0 is PA_VOLUME_NORM. This is only valid for software volumes! */ 316 pa_volume_t pa_sw_volume_from_linear(double v) PA_GCC_CONST; 317 318 /** Convert a volume to a linear factor. This is only valid for software volumes! */ 319 double pa_sw_volume_to_linear(pa_volume_t v) PA_GCC_CONST; 320 321 #ifdef INFINITY 322 #define PA_DECIBEL_MININFTY ((double) -INFINITY) 323 #else 324 /** This floor value is used as minus infinity when using pa_sw_volume_to_dB() / pa_sw_volume_from_dB(). */ 325 #define PA_DECIBEL_MININFTY ((double) -200.0) 326 #endif 327 328 /** Remap a volume from one channel mapping to a different channel mapping. 329 * Returns \a v. \since 0.9.12 */ 330 pa_cvolume *pa_cvolume_remap(pa_cvolume *v, const pa_channel_map *from, const pa_channel_map *to); 331 332 /** Return non-zero if the specified volume is compatible with the 333 * specified sample spec. \since 0.9.13 */ 334 int pa_cvolume_compatible(const pa_cvolume *v, const pa_sample_spec *ss) PA_GCC_PURE; 335 336 /** Return non-zero if the specified volume is compatible with the 337 * specified sample spec. \since 0.9.15 */ 338 int pa_cvolume_compatible_with_channel_map(const pa_cvolume *v, const pa_channel_map *cm) PA_GCC_PURE; 339 340 /** Calculate a 'balance' value for the specified volume with the 341 * specified channel map. The return value will range from -1.0f 342 * (left) to +1.0f (right). If no balance value is applicable to this 343 * channel map the return value will always be 0.0f. See 344 * pa_channel_map_can_balance(). \since 0.9.15 */ 345 float pa_cvolume_get_balance(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE; 346 347 /** Adjust the 'balance' value for the specified volume with the 348 * specified channel map. v will be modified in place and 349 * returned. The balance is a value between -1.0f and +1.0f. This 350 * operation might not be reversible! Also, after this call 351 * pa_cvolume_get_balance() is not guaranteed to actually return the 352 * requested balance value (e.g. when the input volume was zero anyway for 353 * all channels). If no balance value is applicable to 354 * this channel map the volume will not be modified. See 355 * pa_channel_map_can_balance(). Will return NULL on error. \since 0.9.15 */ 356 pa_cvolume* pa_cvolume_set_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance); 357 358 /** Calculate a 'fade' value (i.e.\ 'balance' between front and rear) 359 * for the specified volume with the specified channel map. The return 360 * value will range from -1.0f (rear) to +1.0f (left). If no fade 361 * value is applicable to this channel map the return value will 362 * always be 0.0f. See pa_channel_map_can_fade(). \since 0.9.15 */ 363 float pa_cvolume_get_fade(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE; 364 365 /** Adjust the 'fade' value (i.e.\ 'balance' between front and rear) 366 * for the specified volume with the specified channel map. v will be 367 * modified in place and returned. The balance is a value between 368 * -1.0f and +1.0f. This operation might not be reversible! Also, 369 * after this call pa_cvolume_get_fade() is not guaranteed to actually 370 * return the requested fade value (e.g. when the input volume was 371 * zero anyway for all channels). If no fade value is applicable to 372 * this channel map the volume will not be modified. See 373 * pa_channel_map_can_fade(). Will return NULL on error. \since 0.9.15 */ 374 pa_cvolume* pa_cvolume_set_fade(pa_cvolume *v, const pa_channel_map *map, float new_fade); 375 376 /** Calculate a 'lfe balance' value for the specified volume with 377 * the specified channel map. The return value will range from 378 * -1.0f (no lfe) to +1.0f (only lfe), where 0.0f is balanced. 379 * If no value is applicable to this channel map the return value 380 * will always be 0.0f. See pa_channel_map_can_lfe_balance(). \since 8.0 */ 381 float pa_cvolume_get_lfe_balance(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE; 382 383 /** Adjust the 'lfe balance' value for the specified volume with 384 * the specified channel map. v will be modified in place and returned. 385 * The balance is a value between -1.0f (no lfe) and +1.0f (only lfe). 386 * This operation might not be reversible! Also, after this call 387 * pa_cvolume_get_lfe_balance() is not guaranteed to actually 388 * return the requested value (e.g. when the input volume was 389 * zero anyway for all channels). If no lfe balance value is applicable to 390 * this channel map the volume will not be modified. See 391 * pa_channel_map_can_lfe_balance(). Will return NULL on error. \since 8.0 */ 392 pa_cvolume* pa_cvolume_set_lfe_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance); 393 394 /** Scale the passed pa_cvolume structure so that the maximum volume 395 * of all channels equals max. The proportions between the channel 396 * volumes are kept. Returns \a v, or NULL on error. \since 0.9.15 */ 397 pa_cvolume* pa_cvolume_scale(pa_cvolume *v, pa_volume_t max); 398 399 /** Scale the passed pa_cvolume structure so that the maximum volume 400 * of all channels selected via cm/mask equals max. This also modifies 401 * the volume of those channels that are unmasked. The proportions 402 * between the channel volumes are kept. If cm is NULL this call is 403 * identical to pa_cvolume_scale(). Returns \a v, or NULL on error. 404 * \since 0.9.16 */ 405 pa_cvolume* pa_cvolume_scale_mask(pa_cvolume *v, pa_volume_t max, const pa_channel_map *cm, pa_channel_position_mask_t mask); 406 407 /** Set the passed volume to all channels at the specified channel 408 * position. Will return the updated volume struct, or NULL if there 409 * is no channel at the position specified. You can check if a channel 410 * map includes a specific position by calling 411 * pa_channel_map_has_position(). Returns \a cv, or NULL on error. 412 * \since 0.9.16 */ 413 pa_cvolume* pa_cvolume_set_position(pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t, pa_volume_t v); 414 415 /** Get the maximum volume of all channels at the specified channel 416 * position. Will return 0 if there is no channel at the position 417 * specified. You can check if a channel map includes a specific 418 * position by calling pa_channel_map_has_position(). \since 0.9.16 */ 419 pa_volume_t pa_cvolume_get_position(const pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t) PA_GCC_PURE; 420 421 /** This goes through all channels in a and b and sets the 422 * corresponding channel in dest to the greater volume of both. a, b 423 * and dest may point to the same structure. Returns \a dest, or NULL 424 * on error. \since 0.9.16 */ 425 pa_cvolume* pa_cvolume_merge(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b); 426 427 /** Increase the volume passed in by 'inc', but not exceeding 'limit'. 428 * The proportions between the channels are kept. 429 * Returns \a v, or NULL on error. \since 0.9.19 */ 430 pa_cvolume* pa_cvolume_inc_clamp(pa_cvolume *v, pa_volume_t inc, pa_volume_t limit); 431 432 /** Increase the volume passed in by 'inc'. The proportions between 433 * the channels are kept. Returns \a v, or NULL on error. \since 0.9.16 */ 434 pa_cvolume* pa_cvolume_inc(pa_cvolume *v, pa_volume_t inc); 435 436 /** Decrease the volume passed in by 'dec'. The proportions between 437 * the channels are kept. Returns \a v, or NULL on error. \since 0.9.16 */ 438 pa_cvolume* pa_cvolume_dec(pa_cvolume *v, pa_volume_t dec); 439 440 PA_C_DECL_END 441 442 #endif 443