PulseAudio 16.1

volume.h
Go to the documentation of this file.
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
110PA_C_DECL_BEGIN
111
117 typedef uint32_t pa_volume_t;
118
120#define PA_VOLUME_NORM ((pa_volume_t) 0x10000U)
121
123#define PA_VOLUME_MUTED ((pa_volume_t) 0U)
124
126#define PA_VOLUME_MAX ((pa_volume_t) UINT32_MAX/2)
127
133#define PA_VOLUME_UI_MAX (pa_sw_volume_from_dB(+11.0))
134
136#define PA_VOLUME_INVALID ((pa_volume_t) UINT32_MAX)
137
139#define PA_VOLUME_IS_VALID(v) ((v) <= PA_VOLUME_MAX)
140
142#define PA_CLAMP_VOLUME(v) (PA_CLAMP_UNLIKELY((v), PA_VOLUME_MUTED, PA_VOLUME_MAX))
143
145 typedef struct pa_cvolume {
146 uint8_t channels;
147 pa_volume_t values[PA_CHANNELS_MAX];
148} pa_cvolume;
149
153 int pa_cvolume_equal(const pa_cvolume *a, const pa_cvolume *b) PA_GCC_PURE;
154
158 pa_cvolume* pa_cvolume_init(pa_cvolume *a);
159
161#define pa_cvolume_reset(a, n) pa_cvolume_set((a), (n), PA_VOLUME_NORM)
162
164#define pa_cvolume_mute(a, n) pa_cvolume_set((a), (n), PA_VOLUME_MUTED)
165
167 pa_cvolume* pa_cvolume_set(pa_cvolume *a, unsigned channels, pa_volume_t v);
168
174#define PA_CVOLUME_SNPRINT_MAX 320
175
177 char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c);
178
184#define PA_SW_CVOLUME_SNPRINT_DB_MAX 448
185
187 char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c);
188
193#define PA_CVOLUME_SNPRINT_VERBOSE_MAX 1984
194
199 char *pa_cvolume_snprint_verbose(char *s, size_t l, const pa_cvolume *c, const pa_channel_map *map, int print_dB);
200
206#define PA_VOLUME_SNPRINT_MAX 10
207
209 char *pa_volume_snprint(char *s, size_t l, pa_volume_t v);
210
216#define PA_SW_VOLUME_SNPRINT_DB_MAX 11
217
219 char *pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v);
220
225#define PA_VOLUME_SNPRINT_VERBOSE_MAX 35
226
230 char *pa_volume_snprint_verbose(char *s, size_t l, pa_volume_t v, int print_dB);
231
233 pa_volume_t pa_cvolume_avg(const pa_cvolume *a) PA_GCC_PURE;
234
240 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;
241
243 pa_volume_t pa_cvolume_max(const pa_cvolume *a) PA_GCC_PURE;
244
250 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;
251
253 pa_volume_t pa_cvolume_min(const pa_cvolume *a) PA_GCC_PURE;
254
260 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;
261
263 int pa_cvolume_valid(const pa_cvolume *v) PA_GCC_PURE;
264
266 int pa_cvolume_channels_equal_to(const pa_cvolume *a, pa_volume_t v) PA_GCC_PURE;
267
269#define pa_cvolume_is_muted(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_MUTED)
270
272#define pa_cvolume_is_norm(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_NORM)
273
277 pa_volume_t pa_sw_volume_multiply(pa_volume_t a, pa_volume_t b) PA_GCC_CONST;
278
282 pa_cvolume *pa_sw_cvolume_multiply(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
283
288 pa_cvolume *pa_sw_cvolume_multiply_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b);
289
294 pa_volume_t pa_sw_volume_divide(pa_volume_t a, pa_volume_t b) PA_GCC_CONST;
295
300 pa_cvolume *pa_sw_cvolume_divide(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
301
306 pa_cvolume *pa_sw_cvolume_divide_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b);
307
309 pa_volume_t pa_sw_volume_from_dB(double f) PA_GCC_CONST;
310
312 double pa_sw_volume_to_dB(pa_volume_t v) PA_GCC_CONST;
313
316 pa_volume_t pa_sw_volume_from_linear(double v) PA_GCC_CONST;
317
319 double 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
325#define PA_DECIBEL_MININFTY ((double) -200.0)
326#endif
327
330 pa_cvolume *pa_cvolume_remap(pa_cvolume *v, const pa_channel_map *from, const pa_channel_map *to);
331
334 int pa_cvolume_compatible(const pa_cvolume *v, const pa_sample_spec *ss) PA_GCC_PURE;
335
338 int pa_cvolume_compatible_with_channel_map(const pa_cvolume *v, const pa_channel_map *cm) PA_GCC_PURE;
339
345 float pa_cvolume_get_balance(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE;
346
356 pa_cvolume* pa_cvolume_set_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance);
357
363 float pa_cvolume_get_fade(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE;
364
374 pa_cvolume* pa_cvolume_set_fade(pa_cvolume *v, const pa_channel_map *map, float new_fade);
375
381 float pa_cvolume_get_lfe_balance(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE;
382
392 pa_cvolume* pa_cvolume_set_lfe_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance);
393
397 pa_cvolume* pa_cvolume_scale(pa_cvolume *v, pa_volume_t max);
398
405 pa_cvolume* pa_cvolume_scale_mask(pa_cvolume *v, pa_volume_t max, const pa_channel_map *cm, pa_channel_position_mask_t mask);
406
413 pa_cvolume* pa_cvolume_set_position(pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t, pa_volume_t v);
414
419 pa_volume_t pa_cvolume_get_position(const pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t) PA_GCC_PURE;
420
425 pa_cvolume* pa_cvolume_merge(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
426
430 pa_cvolume* pa_cvolume_inc_clamp(pa_cvolume *v, pa_volume_t inc, pa_volume_t limit);
431
434 pa_cvolume* pa_cvolume_inc(pa_cvolume *v, pa_volume_t inc);
435
438 pa_cvolume* pa_cvolume_dec(pa_cvolume *v, pa_volume_t dec);
439
440PA_C_DECL_END
441
442#endif
channelmap.h
Constants and routines for channel mapping handling.
pa_channel_position_t
enum pa_channel_position pa_channel_position_t
A list of channel labels.
pa_channel_position_mask_t
uint64_t pa_channel_position_mask_t
A mask of channel positions.
Definition: channelmap.h:212
gccmacro.h
GCC attribute macros.
PA_GCC_CONST
#define PA_GCC_CONST
This function's return value depends only the arguments list (stricter version of PA_GCC_PURE)
Definition: gccmacro.h:80
PA_GCC_PURE
#define PA_GCC_PURE
This function's return value depends only the arguments list and global state.
Definition: gccmacro.h:71
sample.h
Constants and routines for sample type handling.
PA_CHANNELS_MAX
#define PA_CHANNELS_MAX
Maximum number of allowed channels.
Definition: sample.h:128
pa_channel_map
A channel map which can be used to attach labels to specific channels of a stream.
Definition: channelmap.h:264
pa_cvolume
A structure encapsulating a per-channel volume.
Definition: volume.h:145
pa_cvolume::channels
uint8_t channels
Number of channels.
Definition: volume.h:146
pa_cvolume::values
pa_volume_t values[PA_CHANNELS_MAX]
Per-channel volume.
Definition: volume.h:147
pa_sample_spec
A sample format and attribute specification.
Definition: sample.h:252
pa_sw_volume_to_linear
double pa_sw_volume_to_linear(pa_volume_t v) PA_GCC_CONST
Convert a volume to a linear factor.
pa_cvolume_get_lfe_balance
float pa_cvolume_get_lfe_balance(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE
Calculate a 'lfe balance' value for the specified volume with the specified channel map.
pa_sw_cvolume_snprint_dB
char * pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c)
Pretty print a volume structure, showing dB values.
pa_cvolume_avg
pa_volume_t pa_cvolume_avg(const pa_cvolume *a) PA_GCC_PURE
Return the average volume of all channels.
pa_cvolume_compatible_with_channel_map
int pa_cvolume_compatible_with_channel_map(const pa_cvolume *v, const pa_channel_map *cm) PA_GCC_PURE
Return non-zero if the specified volume is compatible with the specified sample spec.
pa_cvolume_avg_mask
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
Return the average volume of all channels that are included in the specified channel map with the spe...
pa_cvolume_inc_clamp
pa_cvolume * pa_cvolume_inc_clamp(pa_cvolume *v, pa_volume_t inc, pa_volume_t limit)
Increase the volume passed in by 'inc', but not exceeding 'limit'.
pa_sw_volume_snprint_dB
char * pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v)
Pretty print a volume but show dB values.
pa_sw_volume_multiply
pa_volume_t pa_sw_volume_multiply(pa_volume_t a, pa_volume_t b) PA_GCC_CONST
Multiply two volume specifications, return the result.
pa_sw_volume_to_dB
double pa_sw_volume_to_dB(pa_volume_t v) PA_GCC_CONST
Convert a volume to a decibel value (amplitude, not power).
pa_sw_cvolume_multiply_scalar
pa_cvolume * pa_sw_cvolume_multiply_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b)
Multiply a per-channel volume with a scalar volume and return the result in *dest.
pa_cvolume_channels_equal_to
int pa_cvolume_channels_equal_to(const pa_cvolume *a, pa_volume_t v) PA_GCC_PURE
Return non-zero if the volume of all channels is equal to the specified value.
pa_cvolume_snprint
char * pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c)
Pretty print a volume structure.
pa_sw_cvolume_multiply
pa_cvolume * pa_sw_cvolume_multiply(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b)
Multiply two per-channel volumes and return the result in *dest.
pa_cvolume_remap
pa_cvolume * pa_cvolume_remap(pa_cvolume *v, const pa_channel_map *from, const pa_channel_map *to)
Remap a volume from one channel mapping to a different channel mapping.
pa_cvolume_max_mask
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
Return the maximum volume of all channels that are included in the specified channel map with the spe...
pa_cvolume_set_lfe_balance
pa_cvolume * pa_cvolume_set_lfe_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance)
Adjust the 'lfe balance' value for the specified volume with the specified channel map.
pa_cvolume_set
pa_cvolume * pa_cvolume_set(pa_cvolume *a, unsigned channels, pa_volume_t v)
Set the volume of the specified number of channels to the volume v.
pa_cvolume_scale
pa_cvolume * pa_cvolume_scale(pa_cvolume *v, pa_volume_t max)
Scale the passed pa_cvolume structure so that the maximum volume of all channels equals max.
pa_cvolume_merge
pa_cvolume * pa_cvolume_merge(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b)
This goes through all channels in a and b and sets the corresponding channel in dest to the greater v...
pa_cvolume_init
pa_cvolume * pa_cvolume_init(pa_cvolume *a)
Initialize the specified volume and return a pointer to it.
pa_cvolume_scale_mask
pa_cvolume * pa_cvolume_scale_mask(pa_cvolume *v, pa_volume_t max, const pa_channel_map *cm, pa_channel_position_mask_t mask)
Scale the passed pa_cvolume structure so that the maximum volume of all channels selected via cm/mask...
pa_volume_t
uint32_t pa_volume_t
Volume specification: PA_VOLUME_MUTED: silence; < PA_VOLUME_NORM: decreased volume; PA_VOLUME_NORM: n...
Definition: volume.h:117
pa_sw_cvolume_divide_scalar
pa_cvolume * pa_sw_cvolume_divide_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b)
Divide a per-channel volume by a scalar volume and return the result in *dest.
pa_cvolume_equal
int pa_cvolume_equal(const pa_cvolume *a, const pa_cvolume *b) PA_GCC_PURE
Return non-zero when *a == *b, checking that both a and b have the same number of channels and that t...
pa_cvolume_snprint_verbose
char * pa_cvolume_snprint_verbose(char *s, size_t l, const pa_cvolume *c, const pa_channel_map *map, int print_dB)
Pretty print a volume structure in a verbose way.
pa_cvolume_inc
pa_cvolume * pa_cvolume_inc(pa_cvolume *v, pa_volume_t inc)
Increase the volume passed in by 'inc'.
pa_cvolume_dec
pa_cvolume * pa_cvolume_dec(pa_cvolume *v, pa_volume_t dec)
Decrease the volume passed in by 'dec'.
pa_cvolume_max
pa_volume_t pa_cvolume_max(const pa_cvolume *a) PA_GCC_PURE
Return the maximum volume of all channels.
pa_cvolume_compatible
int pa_cvolume_compatible(const pa_cvolume *v, const pa_sample_spec *ss) PA_GCC_PURE
Return non-zero if the specified volume is compatible with the specified sample spec.
pa_volume_snprint_verbose
char * pa_volume_snprint_verbose(char *s, size_t l, pa_volume_t v, int print_dB)
Pretty print a volume in a verbose way.
pa_cvolume_min_mask
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
Return the minimum volume of all channels that are included in the specified channel map with the spe...
pa_cvolume_get_fade
float pa_cvolume_get_fade(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE
Calculate a 'fade' value (i.e. 'balance' between front and rear) for the specified volume with the sp...
pa_sw_volume_from_linear
pa_volume_t pa_sw_volume_from_linear(double v) PA_GCC_CONST
Convert a linear factor to a volume.
pa_cvolume_valid
int pa_cvolume_valid(const pa_cvolume *v) PA_GCC_PURE
Return non-zero when the passed cvolume structure is valid.
pa_cvolume
struct pa_cvolume pa_cvolume
A structure encapsulating a per-channel volume.
pa_cvolume_set_position
pa_cvolume * pa_cvolume_set_position(pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t, pa_volume_t v)
Set the passed volume to all channels at the specified channel position.
pa_cvolume_set_fade
pa_cvolume * pa_cvolume_set_fade(pa_cvolume *v, const pa_channel_map *map, float new_fade)
Adjust the 'fade' value (i.e. 'balance' between front and rear) for the specified volume with the spe...
pa_cvolume_set_balance
pa_cvolume * pa_cvolume_set_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance)
Adjust the 'balance' value for the specified volume with the specified channel map.
pa_cvolume_min
pa_volume_t pa_cvolume_min(const pa_cvolume *a) PA_GCC_PURE
Return the minimum volume of all channels.
pa_sw_volume_from_dB
pa_volume_t pa_sw_volume_from_dB(double f) PA_GCC_CONST
Convert a decibel value to a volume (amplitude, not power).
pa_sw_volume_divide
pa_volume_t pa_sw_volume_divide(pa_volume_t a, pa_volume_t b) PA_GCC_CONST
Divide two volume specifications, return the result.
pa_sw_cvolume_divide
pa_cvolume * pa_sw_cvolume_divide(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b)
Divide two per-channel volumes and return the result in *dest.
pa_cvolume_get_position
pa_volume_t pa_cvolume_get_position(const pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t) PA_GCC_PURE
Get the maximum volume of all channels at the specified channel position.
pa_volume_snprint
char * pa_volume_snprint(char *s, size_t l, pa_volume_t v)
Pretty print a volume.
pa_cvolume_get_balance
float pa_cvolume_get_balance(const pa_cvolume *v, const pa_channel_map *map) PA_GCC_PURE
Calculate a 'balance' value for the specified volume with the specified channel map.