1 #ifndef foovolumehfoo 2 #define foovolumehfoo 3 4 /* $Id: volume.h 1971 2007-10-28 19:13:50Z lennart $ */ 5 6 /*** 7 This file is part of PulseAudio. 8 9 Copyright 2004-2006 Lennart Poettering 10 Copyright 2006 Pierre Ossman <ossman (at) cendio.se> for Cendio AB 11 12 PulseAudio is free software; you can redistribute it and/or modify 13 it under the terms of the GNU Lesser General Public License as published 14 by the Free Software Foundation; either version 2 of the License, 15 or (at your option) any later version. 16 17 PulseAudio is distributed in the hope that it will be useful, but 18 WITHOUT ANY WARRANTY; without even the implied warranty of 19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 20 General Public License for more details. 21 22 You should have received a copy of the GNU Lesser General Public License 23 along with PulseAudio; if not, write to the Free Software 24 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 25 USA. 26 ***/ 27 28 #include <inttypes.h> 29 #include <pulse/cdecl.h> 30 #include <pulse/sample.h> 31 32 /** \page volume Volume Control 33 * 34 * \section overv_sec Overview 35 * 36 * Sinks, sources, sink inputs and samples can all have their own volumes. 37 * To deal with these, The PulseAudio libray contains a number of functions 38 * that ease handling. 39 * 40 * The basic volume type in PulseAudio is the \ref pa_volume_t type. Most of 41 * the time, applications will use the aggregated pa_cvolume structure that 42 * can store the volume of all channels at once. 43 * 44 * Volumes commonly span between muted (0%), and normal (100%). It is possible 45 * to set volumes to higher than 100%, but clipping might occur. 46 * 47 * \section calc_sec Calculations 48 * 49 * The volumes in PulseAudio are logarithmic in nature and applications 50 * shouldn't perform calculations with them directly. Instead, they should 51 * be converted to and from either dB or a linear scale: 52 * 53 * \li dB - pa_sw_volume_from_dB() / pa_sw_volume_to_dB() 54 * \li Linear - pa_sw_volume_from_linear() / pa_sw_volume_to_linear() 55 * 56 * For simple multiplication, pa_sw_volume_multiply() and 57 * pa_sw_cvolume_multiply() can be used. 58 * 59 * Calculations can only be reliably performed on software volumes 60 * as it is commonly unknown what scale hardware volumes relate to. 61 * 62 * The functions described above are only valid when used with 63 * software volumes. Hence it is usually a better idea to treat all 64 * volume values as opaque with a range from PA_VOLUME_MUTE (0%) to 65 * PA_VOLUME_NORM (100%) and to refrain from any calculations with 66 * them. 67 * 68 * \section conv_sec Convenience Functions 69 * 70 * To handle the pa_cvolume structure, the PulseAudio library provides a 71 * number of convenienc functions: 72 * 73 * \li pa_cvolume_valid() - Tests if a pa_cvolume structure is valid. 74 * \li pa_cvolume_equal() - Tests if two pa_cvolume structures are identical. 75 * \li pa_cvolume_channels_equal_to() - Tests if all channels of a pa_cvolume 76 * structure have a given volume. 77 * \li pa_cvolume_is_muted() - Tests if all channels of a pa_cvolume 78 * structure are muted. 79 * \li pa_cvolume_is_norm() - Tests if all channels of a pa_cvolume structure 80 * are at a normal volume. 81 * \li pa_cvolume_set() - Set all channels of a pa_cvolume structure to a 82 * certain volume. 83 * \li pa_cvolume_reset() - Set all channels of a pa_cvolume structure to a 84 * normal volume. 85 * \li pa_cvolume_mute() - Set all channels of a pa_cvolume structure to a 86 * muted volume. 87 * \li pa_cvolume_avg() - Return the average volume of all channels. 88 * \li pa_cvolume_snprint() - Pretty print a pa_cvolume structure. 89 */ 90 91 /** \file 92 * Constants and routines for volume handling */ 93 94 PA_C_DECL_BEGIN 95 96 /** Volume specification: 97 * PA_VOLUME_MUTED: silence; 98 * < PA_VOLUME_NORM: decreased volume; 99 * PA_VOLUME_NORM: normal volume; 100 * > PA_VOLUME_NORM: increased volume */ 101 typedef uint32_t pa_volume_t; 102 103 /** Normal volume (100%) */ 104 #define PA_VOLUME_NORM (0x10000) 105 106 /** Muted volume (0%) */ 107 #define PA_VOLUME_MUTED (0) 108 109 /** A structure encapsulating a per-channel volume */ 110 typedef struct pa_cvolume { 111 uint8_t channels; /**< Number of channels */ 112 pa_volume_t values[PA_CHANNELS_MAX]; /**< Per-channel volume */ 113 } pa_cvolume; 114 115 /** Return non-zero when *a == *b */ 116 int pa_cvolume_equal(const pa_cvolume *a, const pa_cvolume *b) PA_GCC_PURE; 117 118 /** Set the volume of all channels to PA_VOLUME_NORM */ 119 #define pa_cvolume_reset(a, n) pa_cvolume_set((a), (n), PA_VOLUME_NORM) 120 121 /** Set the volume of all channels to PA_VOLUME_MUTED */ 122 #define pa_cvolume_mute(a, n) pa_cvolume_set((a), (n), PA_VOLUME_MUTED) 123 124 /** Set the volume of all channels to the specified parameter */ 125 pa_cvolume* pa_cvolume_set(pa_cvolume *a, unsigned channels, pa_volume_t v); 126 127 /** Maximum length of the strings returned by pa_cvolume_snprint() */ 128 #define PA_CVOLUME_SNPRINT_MAX 64 129 130 /** Pretty print a volume structure */ 131 char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c); 132 133 /** Return the average volume of all channels */ 134 pa_volume_t pa_cvolume_avg(const pa_cvolume *a) PA_GCC_PURE; 135 136 /** Return TRUE when the passed cvolume structure is valid, FALSE otherwise */ 137 int pa_cvolume_valid(const pa_cvolume *v) PA_GCC_PURE; 138 139 /** Return non-zero if the volume of all channels is equal to the specified value */ 140 int pa_cvolume_channels_equal_to(const pa_cvolume *a, pa_volume_t v) PA_GCC_PURE; 141 142 /** Return 1 if the specified volume has all channels muted */ 143 #define pa_cvolume_is_muted(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_MUTED) 144 145 /** Return 1 if the specified volume has all channels on normal level */ 146 #define pa_cvolume_is_norm(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_NORM) 147 148 /** Multiply two volumes specifications, return the result. This uses PA_VOLUME_NORM as neutral element of multiplication. This is only valid for software volumes! */ 149 pa_volume_t pa_sw_volume_multiply(pa_volume_t a, pa_volume_t b) PA_GCC_CONST; 150 151 /** Multiply to per-channel volumes and return the result in *dest. This is only valid for software volumes! */ 152 pa_cvolume *pa_sw_cvolume_multiply(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b) PA_GCC_PURE; 153 154 /** Convert a decibel value to a volume. This is only valid for software volumes! \since 0.4 */ 155 pa_volume_t pa_sw_volume_from_dB(double f) PA_GCC_CONST; 156 157 /** Convert a volume to a decibel value. This is only valid for software volumes! \since 0.4 */ 158 double pa_sw_volume_to_dB(pa_volume_t v) PA_GCC_CONST; 159 160 /** Convert a linear factor to a volume. This is only valid for software volumes! \since 0.8 */ 161 pa_volume_t pa_sw_volume_from_linear(double v) PA_GCC_CONST; 162 163 /** Convert a volume to a linear factor. This is only valid for software volumes! \since 0.8 */ 164 double pa_sw_volume_to_linear(pa_volume_t v) PA_GCC_CONST; 165 166 #ifdef INFINITY 167 #define PA_DECIBEL_MININFTY (-INFINITY) 168 #else 169 /** This value is used as minus infinity when using pa_volume_{to,from}_dB(). \since 0.4 */ 170 #define PA_DECIBEL_MININFTY (-200) 171 #endif 172 173 PA_C_DECL_END 174 175 #endif 176
