From cc12446728d00161116d6e1823e161440415d2d5 Mon Sep 17 00:00:00 2001
From: Yoann Lopes <yoann.lopes@qt.io>
Date: Fri, 8 Jul 2016 15:22:16 +0200
Subject: Improve audio volume documentation

Added information about volume scales.

Change-Id: Ica8367396147e3e1c814b3575faa5cf0503be031
Reviewed-by: Venugopal Shivashankar <Venugopal.Shivashankar@qt.io>
Reviewed-by: Christian Stromme <christian.stromme@qt.io>
---
 src/multimedia/audio/qaudioinput.cpp  |  7 ++++++-
 src/multimedia/audio/qaudiooutput.cpp | 13 +++++++++++--
 src/multimedia/audio/qsoundeffect.cpp | 25 ++++++++++++++++++++++---
 3 files changed, 39 insertions(+), 6 deletions(-)

(limited to 'src/multimedia/audio')

diff --git a/src/multimedia/audio/qaudioinput.cpp b/src/multimedia/audio/qaudioinput.cpp
index bc6b6215b..ad54521fa 100644
--- a/src/multimedia/audio/qaudioinput.cpp
+++ b/src/multimedia/audio/qaudioinput.cpp
@@ -330,10 +330,15 @@ int QAudioInput::notifyInterval() const
 /*!
     Sets the input volume to \a volume.
 
+    The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+    range will be clamped.
+
     If the device does not support adjusting the input
     volume then \a volume will be ignored and the input
     volume will remain at 1.0.
 
+    The default volume is \c 1.0.
+
     Note: Adjustments to the volume will change the volume of this audio stream, not the global volume.
 */
 void QAudioInput::setVolume(qreal volume)
@@ -342,7 +347,7 @@ void QAudioInput::setVolume(qreal volume)
 }
 
 /*!
-    Returns the input volume (gain).
+    Returns the input volume.
 
     If the device does not support adjusting the input volume
     the returned value will be 1.0.
diff --git a/src/multimedia/audio/qaudiooutput.cpp b/src/multimedia/audio/qaudiooutput.cpp
index 585855ace..670dca7bc 100644
--- a/src/multimedia/audio/qaudiooutput.cpp
+++ b/src/multimedia/audio/qaudiooutput.cpp
@@ -349,9 +349,18 @@ QAudio::State QAudioOutput::state() const
 }
 
 /*!
-    Sets the volume.
-    Where \a volume is between 0.0 and 1.0 inclusive.
+    Sets the output volume to \a volume.
+
+    The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+    range will be clamped.
+
+    The default volume is \c 1.0.
+
     Note: Adjustments to the volume will change the volume of this audio stream, not the global volume.
+
+    UI volume controls should usually be scaled nonlinearly. For example, using a logarithmic scale
+    will produce linear changes in perceived loudness, which is what a user would normally expect
+    from a volume control. See QAudio::convertVolume() for more details.
 */
 void QAudioOutput::setVolume(qreal volume)
 {
diff --git a/src/multimedia/audio/qsoundeffect.cpp b/src/multimedia/audio/qsoundeffect.cpp
index f653de86e..d3b818073 100644
--- a/src/multimedia/audio/qsoundeffect.cpp
+++ b/src/multimedia/audio/qsoundeffect.cpp
@@ -258,12 +258,22 @@ int QSoundEffect::loopsRemaining() const
 /*!
     \qmlproperty qreal QtMultimedia::SoundEffect::volume
 
-    This property holds the volume of the sound effect playback, from 0.0 (silent) to 1.0 (maximum volume).
+    This property holds the volume of the sound effect playback.
+
+    The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+    range will be clamped.
+
+    The default volume is \c 1.0.
+
+    UI volume controls should usually be scaled nonlinearly. For example, using a logarithmic scale
+    will produce linear changes in perceived loudness, which is what a user would normally expect
+    from a volume control. See \l {QtMultimedia::QtMultimedia::convertVolume()}{QtMultimedia.convertVolume()}
+    for more details.
 */
 /*!
     \property QSoundEffect::volume
 
-    This property holds the volume of the sound effect playback, from 0.0 (silent) to 1.0 (maximum volume).
+    This property holds the volume of the sound effect playback, from 0.0 (silence) to 1.0 (full volume).
 */
 
 /*!
@@ -275,7 +285,16 @@ qreal QSoundEffect::volume() const
 }
 
 /*!
-    Sets the volume to play the sound effect at to \a volume, from 0.0 (silent) to 1.0 (maximum volume).
+    Sets the sound effect volume to \a volume.
+
+    The volume is scaled linearly from \c 0.0 (silence) to \c 1.0 (full volume). Values outside this
+    range will be clamped.
+
+    The default volume is \c 1.0.
+
+    UI volume controls should usually be scaled nonlinearly. For example, using a logarithmic scale
+    will produce linear changes in perceived loudness, which is what a user would normally expect
+    from a volume control. See QAudio::convertVolume() for more details.
  */
 void QSoundEffect::setVolume(qreal volume)
 {
-- 
cgit v1.2.1