diff options
author | Yoann Lopes <yoann.lopes@qt.io> | 2016-05-13 17:13:03 +0200 |
---|---|---|
committer | Yoann Lopes <yoann.lopes@qt.io> | 2016-06-03 21:11:58 +0000 |
commit | fe46759fc0a39418a3b5f32cf78a162c35a7aef7 (patch) | |
tree | b043309dc6ee6a3de2b7477113125adda6ae1911 /src/imports | |
parent | 78a73643a31a761ada8cfafa80ddf2fb916c1d6a (diff) | |
download | qtmultimedia-fe46759fc0a39418a3b5f32cf78a162c35a7aef7.tar.gz |
Add new volume conversion API.
All Qt Multimedia volume APIs expect a linear volume factor. However,
UI volume controls should typically use a logarithmic or cubic scale
to match how the human ear perceives loudness.
The new helper function (C++ and QML) provides a way to do the
conversion from one scale to another.
Change-Id: If7795426b728ab0e8fd6635988dbc9be795e3e5e
Reviewed-by: Christian Stromme <christian.stromme@qt.io>
Diffstat (limited to 'src/imports')
-rw-r--r-- | src/imports/multimedia/qdeclarativemultimediaglobal.cpp | 51 | ||||
-rw-r--r-- | src/imports/multimedia/qdeclarativemultimediaglobal_p.h | 11 |
2 files changed, 62 insertions, 0 deletions
diff --git a/src/imports/multimedia/qdeclarativemultimediaglobal.cpp b/src/imports/multimedia/qdeclarativemultimediaglobal.cpp index b2a1aed12..bb1b9c9d8 100644 --- a/src/imports/multimedia/qdeclarativemultimediaglobal.cpp +++ b/src/imports/multimedia/qdeclarativemultimediaglobal.cpp @@ -183,4 +183,55 @@ QJSValue QDeclarativeMultimediaGlobal::availableCameras() const return availableCameras; } +/*! + \qmlmethod real QtMultimedia::QtMultimedia::convertVolume(real volume, VolumeScale from, VolumeScale to) + + Converts an audio \a volume \a from a volume scale \a to another, and returns the result. + + Depending on the context, different scales are used to represent audio volume. All Qt Multimedia + classes that have an audio volume use a linear scale, the reason is that the loudness of a + speaker is controlled by modulating its voltage on a linear scale. The human ear on the other + hand, perceives loudness in a logarithmic way. That is why the decibel scale, being a logarithmic + scale, is typically used to define sound levels. UI volume controls in professional audio + applications usually use a decibel scale. The cubic scale is a computationally cheap + approximation of a logarithmic scale, most applications should use a cubic scale for their UI + volume controls. + + Valid values for \a from and \a to are: + \list + \li QtMultimedia.LinearVolumeScale - Linear scale. \c 0.0 (0%) is silence and \c 1.0 (100%) is + full volume. All Qt Multimedia types that have an audio volume use a linear scale. + \li QtMultimedia.CubicVolumeScale - Cubic scale. \c 0.0 (0%) is silence and \c 1.0 (100%) is full + volume. UI volume controls should usually use a cubic scale. + \li QtMultimedia.DecibelVolumeScale - Decibel (dB, amplitude) logarithmic scale. \c -200 is + silence and \c 0 is full volume. + \endlist + + The following example shows how the volume value from a UI volume control can be converted so + that the perceived increase in loudness is the same when increasing the volume control from 0.2 + to 0.3 as it is from 0.5 to 0.6: + + \code + Slider { + id: volumeSlider + + property real volume: QtMultimedia.convertVolume(volumeSlider.value, + QtMultimedia.CubicVolumeScale, + QtMultimedia.LinearVolumeScale) + } + + MediaPlayer { + volume: volumeSlider.volume + } + \endcode + + \since 5.8 +*/ +qreal QDeclarativeMultimediaGlobal::convertVolume(qreal volume, + QDeclarativeMultimediaGlobal::VolumeScale from, + QDeclarativeMultimediaGlobal::VolumeScale to) const +{ + return QAudio::convertVolume(volume, QAudio::VolumeScale(from), QAudio::VolumeScale(to)); +} + QT_END_NAMESPACE diff --git a/src/imports/multimedia/qdeclarativemultimediaglobal_p.h b/src/imports/multimedia/qdeclarativemultimediaglobal_p.h index 2374b560c..a8413cc09 100644 --- a/src/imports/multimedia/qdeclarativemultimediaglobal_p.h +++ b/src/imports/multimedia/qdeclarativemultimediaglobal_p.h @@ -53,6 +53,7 @@ #include <QtQml/qqml.h> #include <QtQml/qjsvalue.h> +#include <QtMultimedia/qaudio.h> QT_BEGIN_NAMESPACE @@ -63,12 +64,22 @@ class QDeclarativeMultimediaGlobal : public QObject Q_PROPERTY(QJSValue defaultCamera READ defaultCamera NOTIFY defaultCameraChanged) Q_PROPERTY(QJSValue availableCameras READ availableCameras NOTIFY availableCamerasChanged) + Q_ENUMS(VolumeScale) + public: + enum VolumeScale { + LinearVolumeScale = QAudio::LinearVolumeScale, + CubicVolumeScale = QAudio::CubicVolumeScale, + DecibelVolumeScale = QAudio::DecibelVolumeScale + }; + explicit QDeclarativeMultimediaGlobal(QJSEngine *engine, QObject *parent = 0); QJSValue defaultCamera() const; QJSValue availableCameras() const; + Q_INVOKABLE qreal convertVolume(qreal volume, VolumeScale from, VolumeScale to) const; + Q_SIGNALS: // Unused at the moment. QCameraInfo doesn't notify when cameras are added or removed, // but it might change in the future. |