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

[Tanu Kaskinen]

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
  *
-- 
2.14.2