diff options
author | Yoann Lopes <yoann.lopes@qt.io> | 2016-07-08 15:22:16 +0200 |
---|---|---|
committer | Yoann Lopes <yoann.lopes@qt.io> | 2016-08-22 09:50:06 +0000 |
commit | cc12446728d00161116d6e1823e161440415d2d5 (patch) | |
tree | 81998ddb81bdb602be6faf76878e849fe675a75a /src/multimedia/audio | |
parent | d47e412b7b196e37196fa7c7469ae3b54eecf6d4 (diff) |
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>
Diffstat (limited to 'src/multimedia/audio')
-rw-r--r-- | src/multimedia/audio/qaudioinput.cpp | 7 | ||||
-rw-r--r-- | src/multimedia/audio/qaudiooutput.cpp | 13 | ||||
-rw-r--r-- | src/multimedia/audio/qsoundeffect.cpp | 25 |
3 files changed, 39 insertions, 6 deletions
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) { |