[pulseaudio-discuss] [PATCH] volume: improve documentation

[Georg Chini]

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.