From fe46759fc0a39418a3b5f32cf78a162c35a7aef7 Mon Sep 17 00:00:00 2001
From: Yoann Lopes <yoann.lopes@qt.io>
Date: Fri, 13 May 2016 17:13:03 +0200
Subject: 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>
---
 .../multimedia/qdeclarativemultimediaglobal.cpp    | 51 ++++++++++++++++++++++
 .../multimedia/qdeclarativemultimediaglobal_p.h    | 11 +++++
 2 files changed, 62 insertions(+)

(limited to 'src/imports')

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.
-- 
cgit v1.2.3