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