On 15.10.2017 15:56, Tanu Kaskinen wrote: > Changes: > - Mention that source outputs have volume too. > - Don't claim that most distributions have flat volumes enabled. > - Volumes use a cubic scale, not logarithmic. > - Reword the warning about using the conversion functions on hardware > volumes. The old wording gave the incorrect impression that hardware > volumes could never be converted to dB or linear scale. > --- > src/pulse/volume.h | 39 ++++++++++++++++++--------------------- > 1 file changed, 18 insertions(+), 21 deletions(-) > > diff --git a/src/pulse/volume.h b/src/pulse/volume.h > index 8cf4fa45b..03497f747 100644 > --- a/src/pulse/volume.h > +++ b/src/pulse/volume.h > @@ -34,9 +34,9 @@ > * > * \section overv_sec Overview > * > - * Sinks, sources, sink inputs and samples can all have their own volumes. > - * To deal with these, The PulseAudio library contains a number of functions > - * that ease handling. > + * Sinks, sources, sink inputs, source outputs and samples can all have their > + * own volumes. To deal with these, The PulseAudio library contains a number of > + * functions that ease handling. > * > * The basic volume type in PulseAudio is the \ref pa_volume_t type. Most of > * the time, applications will use the aggregated pa_cvolume structure that > @@ -47,13 +47,12 @@ > * > * There is no single well-defined meaning attached to the 100% volume for a > * sink input. In fact, it depends on the server configuration. With flat > - * volumes enabled (the default in most Linux distributions), it means the > - * maximum volume that the sound hardware is capable of, which is usually so > - * high that you absolutely must not set sink input volume to 100% unless the > - * the user explicitly requests that (note that usually you shouldn't set the > - * volume anyway if the user doesn't explicitly request it, instead, let > - * PulseAudio decide the volume for the sink input). With flat volumes disabled > - * (the default in Ubuntu), the sink input volume is relative to the sink > + * volumes enabled, it means the maximum volume that the sound hardware is > + * capable of, which is usually so high that you absolutely must not set sink > + * input volume to 100% unless the the user explicitly requests that (note that > + * usually you shouldn't set the volume anyway if the user doesn't explicitly > + * request it, instead, let PulseAudio decide the volume for the sink input). > + * With flat volumes disabled the sink input volume is relative to the sink > * volume, so 100% sink input volume means that the sink input is played at the > * current sink volume level. In this case 100% is often a good default volume > * for a sink input, although you still should let PulseAudio decide the > @@ -62,9 +61,9 @@ > * > * \section calc_sec Calculations > * > - * The volumes in PulseAudio are logarithmic in nature and applications > - * shouldn't perform calculations with them directly. Instead, they should > - * be converted to and from either dB or a linear scale: > + * The volumes in PulseAudio are cubic in nature and applications shouldn't > + * perform calculations with them directly. Instead, they should be converted > + * to and from either dB or a linear scale: > * > * \li dB - pa_sw_volume_from_dB() / pa_sw_volume_to_dB() > * \li Linear - pa_sw_volume_from_linear() / pa_sw_volume_to_linear() > @@ -72,14 +71,12 @@ > * For simple multiplication, pa_sw_volume_multiply() and > * pa_sw_cvolume_multiply() can be used. > * > - * Calculations can only be reliably performed on software volumes > - * as it is commonly unknown what scale hardware volumes relate to. > - * > - * The functions described above are only valid when used with > - * software volumes. Hence it is usually a better idea to treat all > - * volume values as opaque with a range from PA_VOLUME_MUTED (0%) to > - * PA_VOLUME_NORM (100%) and to refrain from any calculations with > - * them. > + * It's often unknown what scale hardware volumes relate to. Don't use the > + * above functions on sink and source volumes, unless the sink or source in > + * question has the PA_SINK_DECIBEL_VOLUME or PA_SOURCE_DECIBEL_VOLUME flag > + * set. The conversion functions are rarely needed anyway, most of the time > + * it's sufficient to treat all volumes as opaque with a range from > + * PA_VOLUME_MUTED (0%) to PA_VOLUME_NORM (100%). > * > * \section conv_sec Convenience Functions > * Looks good to me.
