Merge remote-tracking branch 'origin/5.8' into dev

Conflicts:
	src/imports/multimedia/multimedia.cpp

Change-Id: I38899391ec8d2fcec6f2d46514286759f7a27629

13 files changed, 119 insertions, 26 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/qaudiosystemplugin.cpp b/src/multimedia/audio/qaudiosystemplugin.cpp
index 438b8b7bb..636b614d4 100644
--- a/src/multimedia/audio/qaudiosystemplugin.cpp
+++ b/src/multimedia/audio/qaudiosystemplugin.cpp
@@ -77,7 +77,7 @@ QAudioSystemPluginExtension::~QAudioSystemPluginExtension()
 
     \sa QAbstractAudioDeviceInfo, QAbstractAudioOutput, QAbstractAudioInput
 
-    Qt comes with plugins for Windows (WinMM and WASAPI), Linux (ALSA and PulseAudio), OS X / iOS
+    Qt comes with plugins for Windows (WinMM and WASAPI), Linux (ALSA and PulseAudio), \macos / iOS
     (CoreAudio), Android (OpenSL ES) and QNX.
 
     If no audio plugins are available, a fallback dummy backend will be used.
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)
 {
diff --git a/src/multimedia/audio/qsoundeffect_pulse_p.cpp b/src/multimedia/audio/qsoundeffect_pulse_p.cpp
index 79d1d96ab..6e4aadd0b 100644
--- a/src/multimedia/audio/qsoundeffect_pulse_p.cpp
+++ b/src/multimedia/audio/qsoundeffect_pulse_p.cpp
@@ -419,7 +419,13 @@ void QSoundEffectPrivate::setSource(const QUrl &url)
 #ifdef QT_PA_DEBUG
     qDebug() << this << "setSource =" << url;
 #endif
+
+    // Make sure the stream is empty before loading a new source (otherwise whatever is there will
+    // be played before the new source)
+    emptyStream();
+
     stop();
+
     if (m_sample) {
         if (!m_sampleReady) {
             disconnect(m_sample, SIGNAL(error()), this, SLOT(decoderError()));
@@ -594,7 +600,7 @@ void QSoundEffectPrivate::playAvailable()
             setLoopsRemaining(0);
             m_playQueued = true;
             Q_ASSERT(m_pulseStream);
-            emptyStream();
+            emptyStream(ReloadSampleWhenDone);
             return;
         }
         setLoopsRemaining(m_loopCount);
@@ -604,18 +610,25 @@ void QSoundEffectPrivate::playAvailable()
     setPlaying(true);
 }
 
-void QSoundEffectPrivate::emptyStream()
+void QSoundEffectPrivate::emptyStream(EmptyStreamOptions options)
 {
 #ifdef QT_PA_DEBUG
     qDebug() << this << "emptyStream";
 #endif
+    if (!m_pulseStream || m_emptying)
+        return;
+
+    const bool reloadSample = options.testFlag(ReloadSampleWhenDone);
+    pa_stream_success_cb_t flushCompleteCb = reloadSample ? stream_flush_reload_callback
+                                                          : stream_flush_callback;
+
     m_emptying = true;
     pa_stream_set_write_callback(m_pulseStream, 0, 0);
     pa_stream_set_underflow_callback(m_pulseStream, 0, 0);
-    pa_operation_unref(pa_stream_flush(m_pulseStream, stream_flush_callback, m_ref->getRef()));
+    pa_operation_unref(pa_stream_flush(m_pulseStream, flushCompleteCb, m_ref->getRef()));
 }
 
-void QSoundEffectPrivate::emptyComplete(void *stream)
+void QSoundEffectPrivate::emptyComplete(void *stream, bool reload)
 {
     PulseDaemonLocker locker;
 #ifdef QT_PA_DEBUG
@@ -625,7 +638,7 @@ void QSoundEffectPrivate::emptyComplete(void *stream)
     m_emptying = false;
 
     if ((pa_stream *)stream == m_pulseStream)
-        pa_operation_unref(pa_stream_cork(m_pulseStream, 1, stream_cork_callback, m_ref->getRef()));
+        pa_operation_unref(pa_stream_cork(m_pulseStream, 1, reload ? stream_cork_callback : 0, m_ref->getRef()));
 }
 
 void QSoundEffectPrivate::sampleReady()
@@ -729,6 +742,10 @@ void QSoundEffectPrivate::prepare()
     if (!m_pulseStream || !m_sampleReady)
         return;
     PulseDaemonLocker locker;
+
+    if (pa_stream_get_state(m_pulseStream) != PA_STREAM_READY)
+        return;
+
     pa_stream_set_write_callback(m_pulseStream, stream_write_callback, this);
     pa_stream_set_underflow_callback(m_pulseStream, stream_underrun_callback, this);
     m_stopping = false;
@@ -857,7 +874,7 @@ void QSoundEffectPrivate::stop()
     PulseDaemonLocker locker;
     m_stopping = true;
     if (m_pulseStream) {
-        emptyStream();
+        emptyStream(ReloadSampleWhenDone);
         if (m_reloadCategory) {
             unloadPulseStream(); // upon play we reconnect anyway
         }
@@ -1100,10 +1117,26 @@ void QSoundEffectPrivate::stream_flush_callback(pa_stream *s, int success, void
 
     if (!success)
         qWarning("QSoundEffect(pulseaudio): faild to drain");
+
+    QMetaObject::invokeMethod(self, "emptyComplete", Qt::QueuedConnection, Q_ARG(void*, s), Q_ARG(bool, false));
+}
+
+void QSoundEffectPrivate::stream_flush_reload_callback(pa_stream *s, int success, void *userdata)
+{
 #ifdef QT_PA_DEBUG
-    qDebug() << self << "stream_flush_callback";
+    qDebug() << "stream_flush_reload_callback";
 #endif
-    QMetaObject::invokeMethod(self, "emptyComplete", Qt::QueuedConnection, Q_ARG(void*, s));
+    Q_UNUSED(s);
+    QSoundEffectRef *ref = reinterpret_cast<QSoundEffectRef*>(userdata);
+    QSoundEffectPrivate *self = ref->soundEffect();
+    ref->release();
+    if (!self)
+        return;
+
+    if (!success)
+        qWarning("QSoundEffect(pulseaudio): faild to drain");
+
+    QMetaObject::invokeMethod(self, "emptyComplete", Qt::QueuedConnection, Q_ARG(void*, s), Q_ARG(bool, true));
 }
 
 void QSoundEffectPrivate::stream_write_done_callback(void *p)
diff --git a/src/multimedia/audio/qsoundeffect_pulse_p.h b/src/multimedia/audio/qsoundeffect_pulse_p.h
index 6bf2416cf..020aa031a 100644
--- a/src/multimedia/audio/qsoundeffect_pulse_p.h
+++ b/src/multimedia/audio/qsoundeffect_pulse_p.h
@@ -117,7 +117,7 @@ private Q_SLOTS:
     void underRun();
     void prepare();
     void streamReady();
-    void emptyComplete(void *stream);
+    void emptyComplete(void *stream, bool reload);
 
     void handleAvailabilityChanged(bool available);
 
@@ -125,7 +125,12 @@ private:
     void playAvailable();
     void playSample();
 
-    void emptyStream();
+    enum EmptyStreamOption {
+        ReloadSampleWhenDone = 0x1
+    };
+    Q_DECLARE_FLAGS(EmptyStreamOptions, EmptyStreamOption)
+    void emptyStream(EmptyStreamOptions options = EmptyStreamOptions());
+
     void createPulseStream();
     void unloadPulseStream();
 
@@ -140,6 +145,7 @@ private:
     static void stream_underrun_callback(pa_stream *s, void *userdata);
     static void stream_cork_callback(pa_stream *s, int success, void *userdata);
     static void stream_flush_callback(pa_stream *s, int success, void *userdata);
+    static void stream_flush_reload_callback(pa_stream *s, int success, void *userdata);
     static void stream_write_done_callback(void *p);
     static void stream_adjust_prebuffer_callback(pa_stream *s, int success, void *userdata);
     static void stream_reset_buffer_callback(pa_stream *s, int success, void *userdata);
diff --git a/src/multimedia/controls/qmediaplayercontrol.cpp b/src/multimedia/controls/qmediaplayercontrol.cpp
index cd56dffcb..46de05b51 100644
--- a/src/multimedia/controls/qmediaplayercontrol.cpp
+++ b/src/multimedia/controls/qmediaplayercontrol.cpp
@@ -175,6 +175,8 @@ QMediaPlayerControl::QMediaPlayerControl(QObject *parent):
     \fn QMediaPlayerControl::setVolume(int volume)
 
     Sets the audio \a volume of a player control.
+
+    The volume is scaled linearly, ranging from \c 0 (silence) to \c 100 (full volume).
 */
 
 /*!
diff --git a/src/multimedia/controls/qmediarecordercontrol.cpp b/src/multimedia/controls/qmediarecordercontrol.cpp
index 4654d16eb..611f1fdcc 100644
--- a/src/multimedia/controls/qmediarecordercontrol.cpp
+++ b/src/multimedia/controls/qmediarecordercontrol.cpp
@@ -160,13 +160,15 @@ QMediaRecorderControl::~QMediaRecorderControl()
 /*!
     \fn qreal QMediaRecorderControl::volume() const
 
-    Returns the linear audio gain of media recorder.
+    Returns the audio volume of a media recorder control.
 */
 
 /*!
     \fn void QMediaRecorderControl::setVolume(qreal gain)
 
-    Sets the linear audio \a gain of a media recorder.
+    Sets the audio \a volume of a media recorder control.
+
+    The volume is scaled linearly, ranging from \c 0 (silence) to \c 100 (full volume).
 */
 
 /*!
diff --git a/src/multimedia/doc/src/qtmultimedia-examples.qdoc b/src/multimedia/doc/src/qtmultimedia-examples.qdoc
index 582efc5e1..dd35aeb1a 100644
--- a/src/multimedia/doc/src/qtmultimedia-examples.qdoc
+++ b/src/multimedia/doc/src/qtmultimedia-examples.qdoc
@@ -32,6 +32,6 @@
     \brief Demonstrates the multimedia functionality provided by Qt.
 
     The \l{Qt Multimedia} module provides low-level audio support on Linux,
-    Windows and OS X. It also provides audio plugin API to allow developers
+    Windows and \macos. It also provides audio plugin API to allow developers
     implement their own audio support for custom devices and platforms.
 */
diff --git a/src/multimedia/playback/qmediaplayer.cpp b/src/multimedia/playback/qmediaplayer.cpp
index c5261921a..648c13220 100644
--- a/src/multimedia/playback/qmediaplayer.cpp
+++ b/src/multimedia/playback/qmediaplayer.cpp
@@ -1372,8 +1372,14 @@ QList<QAudio::Role> QMediaPlayer::supportedAudioRoles() const
     \property QMediaPlayer::volume
     \brief the current playback volume.
 
-    The playback volume is linear in effect and the value can range from 0 -
-    100, values outside this range will be clamped.
+    The playback volume is scaled linearly, ranging from \c 0 (silence) to \c 100 (full volume).
+    Values outside this range will be clamped.
+
+    By default the volume is \c 100.
+
+    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.
 */
 
 /*!
diff --git a/src/multimedia/playback/qmediaplaylist.cpp b/src/multimedia/playback/qmediaplaylist.cpp
index 4ffcad398..97fe75044 100644
--- a/src/multimedia/playback/qmediaplaylist.cpp
+++ b/src/multimedia/playback/qmediaplaylist.cpp
@@ -448,10 +448,12 @@ bool QMediaPlaylist::clear()
 
 bool QMediaPlaylistPrivate::readItems(QMediaPlaylistReader *reader)
 {
+    QList<QMediaContent> items;
+
     while (!reader->atEnd())
-        playlist()->addMedia(reader->readItem());
+        items.append(reader->readItem());
 
-    return true;
+    return playlist()->addMedia(items);
 }
 
 bool QMediaPlaylistPrivate::writeItems(QMediaPlaylistWriter *writer)
diff --git a/src/multimedia/recording/qmediarecorder.cpp b/src/multimedia/recording/qmediarecorder.cpp
index a5f4c15ce..7b0234988 100644
--- a/src/multimedia/recording/qmediarecorder.cpp
+++ b/src/multimedia/recording/qmediarecorder.cpp
@@ -556,7 +556,16 @@ void QMediaRecorder::setMuted(bool muted)
 /*!
     \property QMediaRecorder::volume
 
-    \brief the linear audio gain of media recorder.
+    \brief the current recording audio 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.
 */
 
 qreal QMediaRecorder::volume() const
diff --git a/src/multimedia/video/qabstractvideobuffer.cpp b/src/multimedia/video/qabstractvideobuffer.cpp
index 877fe3544..50e38a98c 100644
--- a/src/multimedia/video/qabstractvideobuffer.cpp
+++ b/src/multimedia/video/qabstractvideobuffer.cpp
@@ -98,7 +98,7 @@ int QAbstractVideoBufferPrivate::map(
     \value NoHandle The buffer has no handle, its data can only be accessed by mapping the buffer.
     \value GLTextureHandle The handle of the buffer is an OpenGL texture ID.
     \value XvShmImageHandle The handle contains pointer to shared memory XVideo image.
-    \value CoreImageHandle The handle contains pointer to OS X CIImage.
+    \value CoreImageHandle The handle contains pointer to \macos CIImage.
     \value QPixmapHandle The handle of the buffer is a QPixmap.
     \value EGLImageHandle The handle of the buffer is an EGLImageKHR.
     \value UserHandle Start value for user defined handle types.