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
110PA_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 */
117typedef 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 */
145typedef 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. */
153int 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 */
158pa_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 */
167pa_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. */
177char *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 */
187char *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 */
199char *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 */
209char *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 */
219char *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 */
230char *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 */
233pa_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 */
240pa_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 */
243pa_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 */
250pa_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 */
253pa_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 */
260pa_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 */
263int 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 */
266int 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! */
277pa_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. */
282pa_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 */
288pa_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 */
294pa_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 */
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. Returns dest,
305 * or NULL on error. \since 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.
329 * Returns \a v. \since 0.9.12 */
330pa_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 */
334int 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 */
338int 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 */
345float 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 */
356pa_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 */
363float 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 */
374pa_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 */
381float 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 */
392pa_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 */
397pa_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 */
405pa_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 */
413pa_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 */
419pa_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 */
425pa_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 */
430pa_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 */
434pa_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 */
438pa_cvolume* pa_cvolume_dec(pa_cvolume *v, pa_volume_t dec);
439
440PA_C_DECL_END
441
442#endif
443

source code of include/pulse/volume.h