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