]>
code.delx.au - pulseaudio/blob - src/pulse/volume.h
7 This file is part of PulseAudio.
9 Copyright 2004-2006 Lennart Poettering
10 Copyright 2006 Pierre Ossman <ossman@cendio.se> for Cendio AB
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.
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.
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
30 #include <pulse/cdecl.h>
31 #include <pulse/gccmacro.h>
32 #include <pulse/sample.h>
34 /** \page volume Volume Control
36 * \section overv_sec Overview
38 * Sinks, sources, sink inputs and samples can all have their own volumes.
39 * To deal with these, The PulseAudio libray contains a number of functions
42 * The basic volume type in PulseAudio is the \ref pa_volume_t type. Most of
43 * the time, applications will use the aggregated pa_cvolume structure that
44 * can store the volume of all channels at once.
46 * Volumes commonly span between muted (0%), and normal (100%). It is possible
47 * to set volumes to higher than 100%, but clipping might occur.
49 * \section calc_sec Calculations
51 * The volumes in PulseAudio are logarithmic in nature and applications
52 * shouldn't perform calculations with them directly. Instead, they should
53 * be converted to and from either dB or a linear scale:
55 * \li dB - pa_sw_volume_from_dB() / pa_sw_volume_to_dB()
56 * \li Linear - pa_sw_volume_from_linear() / pa_sw_volume_to_linear()
58 * For simple multiplication, pa_sw_volume_multiply() and
59 * pa_sw_cvolume_multiply() can be used.
61 * Calculations can only be reliably performed on software volumes
62 * as it is commonly unknown what scale hardware volumes relate to.
64 * The functions described above are only valid when used with
65 * software volumes. Hence it is usually a better idea to treat all
66 * volume values as opaque with a range from PA_VOLUME_MUTE (0%) to
67 * PA_VOLUME_NORM (100%) and to refrain from any calculations with
70 * \section conv_sec Convenience Functions
72 * To handle the pa_cvolume structure, the PulseAudio library provides a
73 * number of convenienc functions:
75 * \li pa_cvolume_valid() - Tests if a pa_cvolume structure is valid.
76 * \li pa_cvolume_equal() - Tests if two pa_cvolume structures are identical.
77 * \li pa_cvolume_channels_equal_to() - Tests if all channels of a pa_cvolume
78 * structure have a given volume.
79 * \li pa_cvolume_is_muted() - Tests if all channels of a pa_cvolume
80 * structure are muted.
81 * \li pa_cvolume_is_norm() - Tests if all channels of a pa_cvolume structure
82 * are at a normal volume.
83 * \li pa_cvolume_set() - Set all channels of a pa_cvolume structure to a
85 * \li pa_cvolume_reset() - Set all channels of a pa_cvolume structure to a
87 * \li pa_cvolume_mute() - Set all channels of a pa_cvolume structure to a
89 * \li pa_cvolume_avg() - Return the average volume of all channels.
90 * \li pa_cvolume_snprint() - Pretty print a pa_cvolume structure.
94 * Constants and routines for volume handling */
98 /** Volume specification:
99 * PA_VOLUME_MUTED: silence;
100 * < PA_VOLUME_NORM: decreased volume;
101 * PA_VOLUME_NORM: normal volume;
102 * > PA_VOLUME_NORM: increased volume */
103 typedef uint32_t pa_volume_t
;
105 /** Normal volume (100%) */
106 #define PA_VOLUME_NORM ((pa_volume_t) 0x10000U)
108 /** Muted volume (0%) */
109 #define PA_VOLUME_MUTED ((pa_volume_t) 0U)
111 /** A structure encapsulating a per-channel volume */
112 typedef struct pa_cvolume
{
113 uint8_t channels
; /**< Number of channels */
114 pa_volume_t values
[ PA_CHANNELS_MAX
]; /**< Per-channel volume */
117 /** Return non-zero when *a == *b */
118 int pa_cvolume_equal ( const pa_cvolume
* a
, const pa_cvolume
* b
) PA_GCC_PURE
;
120 /** Set the volume of all channels to PA_VOLUME_NORM */
121 #define pa_cvolume_reset(a, n) pa_cvolume_set((a), (n), PA_VOLUME_NORM)
123 /** Set the volume of all channels to PA_VOLUME_MUTED */
124 #define pa_cvolume_mute(a, n) pa_cvolume_set((a), (n), PA_VOLUME_MUTED)
126 /** Set the volume of all channels to the specified parameter */
127 pa_cvolume
* pa_cvolume_set ( pa_cvolume
* a
, unsigned channels
, pa_volume_t v
);
129 /** Maximum length of the strings returned by pa_cvolume_snprint() */
130 #define PA_CVOLUME_SNPRINT_MAX 64
132 /** Pretty print a volume structure */
133 char * pa_cvolume_snprint ( char * s
, size_t l
, const pa_cvolume
* c
);
135 /** Return the average volume of all channels */
136 pa_volume_t
pa_cvolume_avg ( const pa_cvolume
* a
) PA_GCC_PURE
;
138 /** Return TRUE when the passed cvolume structure is valid, FALSE otherwise */
139 int pa_cvolume_valid ( const pa_cvolume
* v
) PA_GCC_PURE
;
141 /** Return non-zero if the volume of all channels is equal to the specified value */
142 int pa_cvolume_channels_equal_to ( const pa_cvolume
* a
, pa_volume_t v
) PA_GCC_PURE
;
144 /** Return 1 if the specified volume has all channels muted */
145 #define pa_cvolume_is_muted(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_MUTED)
147 /** Return 1 if the specified volume has all channels on normal level */
148 #define pa_cvolume_is_norm(a) pa_cvolume_channels_equal_to((a), PA_VOLUME_NORM)
150 /** Multiply two volumes specifications, return the result. This uses PA_VOLUME_NORM as neutral element of multiplication. This is only valid for software volumes! */
151 pa_volume_t
pa_sw_volume_multiply ( pa_volume_t a
, pa_volume_t b
) PA_GCC_CONST
;
153 /** Multiply to per-channel volumes and return the result in *dest. This is only valid for software volumes! */
154 pa_cvolume
* pa_sw_cvolume_multiply ( pa_cvolume
* dest
, const pa_cvolume
* a
, const pa_cvolume
* b
);
156 /** Convert a decibel value to a volume. This is only valid for software volumes! */
157 pa_volume_t
pa_sw_volume_from_dB ( double f
) PA_GCC_CONST
;
159 /** Convert a volume to a decibel value. This is only valid for software volumes! */
160 double pa_sw_volume_to_dB ( pa_volume_t v
) PA_GCC_CONST
;
162 /** Convert a linear factor to a volume. This is only valid for software volumes! */
163 pa_volume_t
pa_sw_volume_from_linear ( double v
) PA_GCC_CONST
;
165 /** Convert a volume to a linear factor. This is only valid for software volumes! */
166 double pa_sw_volume_to_linear ( pa_volume_t v
) PA_GCC_CONST
;
169 #define PA_DECIBEL_MININFTY ((double) -INFINITY)
171 /** This value is used as minus infinity when using pa_volume_{to,from}_dB(). */
172 #define PA_DECIBEL_MININFTY ((double) -200.0)