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