QMediaPlayer: Update gst-pipeline docs

Added docs for using QAbstractVideoSurface
and example how to use QVideoWidget.

Change-Id: I27a105a3859086e6fa5d8a19672ef791ce9e5cca
Reviewed-by: Andy Shaw <andy.shaw@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

2 files changed, 42 insertions, 2 deletions

diff --git a/src/multimedia/doc/snippets/multimedia-snippets/media.cpp b/src/multimedia/doc/snippets/multimedia-snippets/media.cpp
index 8ec7cb072..7fd6259ea 100644
--- a/src/multimedia/doc/snippets/multimedia-snippets/media.cpp
+++ b/src/multimedia/doc/snippets/multimedia-snippets/media.cpp
@@ -56,6 +56,7 @@
 #include "qaudioprobe.h"
 #include "qaudiorecorder.h"
 #include "qvideoprobe.h"
+#include <QAbstractVideoSurface>
 
 class MediaExample : public QObject {
     Q_OBJECT
@@ -197,6 +198,36 @@ void MediaExample::MediaPlayer()
     player->play();
     //! [Pipeline]
 
+    //! [Pipeline Surface]
+    class Surface : public QAbstractVideoSurface
+    {
+    public:
+        Surface(QObject *p) : QAbstractVideoSurface(p) { }
+        QList<QVideoFrame::PixelFormat> supportedPixelFormats(QAbstractVideoBuffer::HandleType) const override
+        {
+            // Make sure that the driver supports this pixel format.
+            return QList<QVideoFrame::PixelFormat>() << QVideoFrame::Format_YUYV;
+        }
+
+        // Video frames are handled here.
+        bool present(const QVideoFrame &) override { return true; }
+    };
+
+    player = new QMediaPlayer;
+    player->setVideoOutput(new Surface(player));
+    player->setMedia(QUrl("gst-pipeline: videotestsrc ! qtvideosink"));
+    player->play();
+    //! [Pipeline Surface]
+
+    //! [Pipeline Widget]
+    player = new QMediaPlayer;
+    videoWidget = new QVideoWidget;
+    videoWidget->show();
+    player->setVideoOutput(videoWidget);
+    player->setMedia(QUrl("gst-pipeline: videotestsrc ! xvimagesink name=\"qtvideosink\""));
+    player->play();
+    //! [Pipeline Widget]
+
     //! [Pipeline appsrc]
     QImage img("images/qt-logo.png");
     img = img.convertToFormat(QImage::Format_ARGB32);
diff --git a/src/multimedia/playback/qmediaplayer.cpp b/src/multimedia/playback/qmediaplayer.cpp
index 44e91912b..2c66ad06a 100644
--- a/src/multimedia/playback/qmediaplayer.cpp
+++ b/src/multimedia/playback/qmediaplayer.cpp
@@ -1022,8 +1022,17 @@ void QMediaPlayer::setPlaybackRate(qreal rate)
 
     \snippet multimedia-snippets/media.cpp Pipeline
 
-    If the pipeline contains a video sink element named \c qtvideosink,
-    current QVideoWidget can be used to render the video.
+    If QAbstractVideoSurface is used as the video output,
+    \c qtvideosink can be used as a video sink element directly in the pipeline.
+    After that the surface will receive the video frames in QAbstractVideoSurface::present().
+
+    \snippet multimedia-snippets/media.cpp Pipeline Surface
+
+    If QVideoWidget is used as the video output
+    and the pipeline contains a video sink element named \c qtvideosink,
+    current QVideoWidget will be used to render the video.
+
+    \snippet multimedia-snippets/media.cpp Pipeline Widget
 
     If the pipeline contains appsrc element, it will be used to push data from \a stream.