QAbstractVideoSurface API review changes.

Rename isStarted() and startedChanged() to is active() and
activeChanged().
Remove the the similar format argument from isFormatSupported() and add
a new nearestFormat() function which provides the same functionality.

Reviewed-by: Justin McPherson

8 files changed, 76 insertions, 45 deletions

diff --git a/examples/multimedia/videographicsitem/videoitem.cpp b/examples/multimedia/videographicsitem/videoitem.cpp
index c95e335..2d7b38e 100644
--- a/examples/multimedia/videographicsitem/videoitem.cpp
+++ b/examples/multimedia/videographicsitem/videoitem.cpp
@@ -129,7 +129,7 @@ void VideoItem::stop()
 bool VideoItem::present(const QVideoFrame &frame)
 {
     if (!framePainted) {
-        if (!isStarted())
+        if (!QAbstractVideoSurface::isActive())
             setError(StoppedError);
 
         return false;
diff --git a/examples/multimedia/videographicsitem/videoplayer.cpp b/examples/multimedia/videographicsitem/videoplayer.cpp
index 83644db..9ac4152 100644
--- a/examples/multimedia/videographicsitem/videoplayer.cpp
+++ b/examples/multimedia/videographicsitem/videoplayer.cpp
@@ -119,8 +119,7 @@ void VideoPlayer::openFile()
     QString fileName = QFileDialog::getOpenFileName(this, tr("Open Movie"));
 
     if (!fileName.isEmpty()) {
-        if (videoItem->isStarted())
-            videoItem->stop();
+        videoItem->stop();
 
         movie.setFileName(fileName);
 
diff --git a/examples/multimedia/videowidget/videoplayer.cpp b/examples/multimedia/videowidget/videoplayer.cpp
index ed24714..cd146e8 100644
--- a/examples/multimedia/videowidget/videoplayer.cpp
+++ b/examples/multimedia/videowidget/videoplayer.cpp
@@ -100,8 +100,7 @@ void VideoPlayer::openFile()
     QString fileName = QFileDialog::getOpenFileName(this, tr("Open Movie"));
 
     if (!fileName.isEmpty()) {
-        if (surface->isStarted())
-            surface->stop();
+        surface->stop();
 
         movie.setFileName(fileName);
 
diff --git a/examples/multimedia/videowidget/videowidget.cpp b/examples/multimedia/videowidget/videowidget.cpp
index 80688e1..f73a52f 100644
--- a/examples/multimedia/videowidget/videowidget.cpp
+++ b/examples/multimedia/videowidget/videowidget.cpp
@@ -84,7 +84,7 @@ void VideoWidget::paintEvent(QPaintEvent *event)
 {
     QPainter painter(this);
 
-    if (surface->isStarted()) {
+    if (surface->isActive()) {
         const QRect videoRect = surface->videoRect();
 
         if (!videoRect.contains(event->rect())) {
diff --git a/src/multimedia/video/qabstractvideosurface.cpp b/src/multimedia/video/qabstractvideosurface.cpp
index a4f51a2..33dc815 100644
--- a/src/multimedia/video/qabstractvideosurface.cpp
+++ b/src/multimedia/video/qabstractvideosurface.cpp
@@ -57,8 +57,8 @@ QT_BEGIN_NAMESPACE
     of each frame is compatible with a stream format supplied when starting a presentation.
 
     A list of pixel formats a surface can present is given by the supportedPixelFormats() function,
-    and the isFormatSupported() function will test if a complete video format is supported.  In
-    some cases when a format is not supported; isFormatSupported() may suggest a similar format.
+    and the isFormatSupported() function will test if a video surface format is supported.  If a
+    format is not supported the nearestFormat() function may be able to suggest a similar format.
     For example if a surface supports fixed set of resolutions it may suggest the smallest
     supported resolution that contains the proposed resolution.
 
@@ -118,21 +118,37 @@ QAbstractVideoSurface::~QAbstractVideoSurface()
 */
 
 /*!
-    Tests a video \a format to determine if a surface can accept it.  If the format isn't supported
-    the surface may suggest a \a similar format that is supported.
+    Tests a video surface \a format to determine if a surface can accept it.
 
     Returns true if the format is supported by the surface, and false otherwise.
 */
 
-bool QAbstractVideoSurface::isFormatSupported(
-        const QVideoSurfaceFormat &format, QVideoSurfaceFormat *similar) const
+bool QAbstractVideoSurface::isFormatSupported(const QVideoSurfaceFormat &format) const
 {
-    Q_UNUSED(similar);
-
     return supportedPixelFormats(format.handleType()).contains(format.pixelFormat());
 }
 
 /*!
+    Returns a supported video surface format that is similar to \a format.
+
+    A similar surface format is one that has the same \l {QVideoSurfaceFormat::pixelFormat()}{pixel
+    format} and \l {QVideoSurfaceFormat::handleType()}{handle type} but differs in some of the other
+    properties.  For example if there are restrictions on the \l {QVideoSurfaceFormat::frameSize()}
+    {frame sizes} a video surface can accept it may suggest a format with a larger frame size and
+    a \l {QVideoSurfaceFormat::viewport()}{viewport} the size of the original frame size.
+
+    If the format is already supported it will be returned unchanged, or if there is no similar
+    supported format an invalid format will be returned.
+*/
+
+QVideoSurfaceFormat QAbstractVideoSurface::nearestFormat(const QVideoSurfaceFormat &format) const
+{
+    return isFormatSupported(format)
+            ? format
+            : QVideoSurfaceFormat();
+}
+
+/*!
     \fn QAbstractVideoSurface::supportedFormatsChanged()
 
     Signals that the set of formats supported by a video surface has changed.
@@ -162,23 +178,23 @@ QVideoSurfaceFormat QAbstractVideoSurface::surfaceFormat() const
 
     Returns true if the surface was started, and false if an error occurred.
 
-    \sa isStarted(), stop()
+    \sa isActive(), stop()
 */
 
 bool QAbstractVideoSurface::start(const QVideoSurfaceFormat &format)
 {
     Q_D(QAbstractVideoSurface);
 
-    bool wasStarted  = d->started;
+    bool wasActive  = d->active;
 
-    d->started = true;
+    d->active = true;
     d->format = format;
     d->error = NoError;
 
     emit surfaceFormatChanged(d->format);
 
-    if (!wasStarted)
-        emit startedChanged(true);
+    if (!wasActive)
+        emit activeChanged(true);
 
     return true;
 }
@@ -186,18 +202,18 @@ bool QAbstractVideoSurface::start(const QVideoSurfaceFormat &format)
 /*!
     Stops a video surface presenting frames and releases any resources acquired in start().
 
-    \sa isStarted(), start()
+    \sa isActive(), start()
 */
 
 void QAbstractVideoSurface::stop()
 {
     Q_D(QAbstractVideoSurface);
 
-    if (d->started) {
+    if (d->active) {
         d->format = QVideoSurfaceFormat();
-        d->started = false;
+        d->active = false;
 
-        emit startedChanged(false);
+        emit activeChanged(false);
         emit surfaceFormatChanged(d->format);
     }
 }
@@ -208,17 +224,17 @@ void QAbstractVideoSurface::stop()
     Returns true if the surface has been started, and false otherwise.
 */
 
-bool QAbstractVideoSurface::isStarted() const
+bool QAbstractVideoSurface::isActive() const
 {
-    return d_func()->started;
+    return d_func()->active;
 }
 
 /*!
-    \fn QAbstractVideoSurface::startedChanged(bool started)
+    \fn QAbstractVideoSurface::activeChanged(bool active)
 
-    Signals that the \a started state of a video surface has changed.
+    Signals that the \a active state of a video surface has changed.
 
-    \sa isStarted(), start(), stop()
+    \sa isActive(), start(), stop()
 */
 
 /*!
diff --git a/src/multimedia/video/qabstractvideosurface.h b/src/multimedia/video/qabstractvideosurface.h
index 3823eeb..58d06f1 100644
--- a/src/multimedia/video/qabstractvideosurface.h
+++ b/src/multimedia/video/qabstractvideosurface.h
@@ -75,22 +75,22 @@ public:
 
     virtual QList<QVideoFrame::PixelFormat> supportedPixelFormats(
             QAbstractVideoBuffer::HandleType handleType = QAbstractVideoBuffer::NoHandle) const = 0;
-    virtual bool isFormatSupported(
-            const QVideoSurfaceFormat &format, QVideoSurfaceFormat *similar = 0) const;
+    virtual bool isFormatSupported(const QVideoSurfaceFormat &format) const;
+    virtual QVideoSurfaceFormat nearestFormat(const QVideoSurfaceFormat &format) const;
 
     QVideoSurfaceFormat surfaceFormat() const;
 
     virtual bool start(const QVideoSurfaceFormat &format);
     virtual void stop();
 
-    bool isStarted() const;
+    bool isActive() const;
 
     virtual bool present(const QVideoFrame &frame) = 0;
 
     Error error() const;
 
 Q_SIGNALS:
-    void startedChanged(bool started);
+    void activeChanged(bool active);
     void surfaceFormatChanged(const QVideoSurfaceFormat &format);
     void supportedFormatsChanged();
 
diff --git a/src/multimedia/video/qabstractvideosurface_p.h b/src/multimedia/video/qabstractvideosurface_p.h
index 3142b78..8675fac 100644
--- a/src/multimedia/video/qabstractvideosurface_p.h
+++ b/src/multimedia/video/qabstractvideosurface_p.h
@@ -64,14 +64,13 @@ class QAbstractVideoSurfacePrivate : public QObjectPrivate
 public:
     QAbstractVideoSurfacePrivate()
         : error(QAbstractVideoSurface::NoError)
-        , started(false)
+        , active(false)
     {
     }
 
     mutable QAbstractVideoSurface::Error error;
     QVideoSurfaceFormat format;
-    bool started;
-
+    bool active;
 };
 
 QT_END_NAMESPACE
diff --git a/tests/auto/qabstractvideosurface/tst_qabstractvideosurface.cpp b/tests/auto/qabstractvideosurface/tst_qabstractvideosurface.cpp
index 20ca759..b4d2ac8 100644
--- a/tests/auto/qabstractvideosurface/tst_qabstractvideosurface.cpp
+++ b/tests/auto/qabstractvideosurface/tst_qabstractvideosurface.cpp
@@ -61,6 +61,8 @@ private slots:
     void setError();
     void isFormatSupported_data();
     void isFormatSupported();
+    void nearestFormat_data();
+    void nearestFormat();
     void start_data();
     void start();
 };
@@ -232,6 +234,22 @@ void tst_QAbstractVideoSurface::isFormatSupported()
     QCOMPARE(surface.isFormatSupported(format), supported);
 }
 
+void tst_QAbstractVideoSurface::nearestFormat_data()
+{
+    isFormatSupported_data();
+}
+
+void tst_QAbstractVideoSurface::nearestFormat()
+{
+    QFETCH(SupportedFormatMap, supportedFormats);
+    QFETCH(QVideoSurfaceFormat, format);
+    QFETCH(bool, supported);
+
+    QtTestVideoSurface surface(supportedFormats);
+
+    QCOMPARE(surface.nearestFormat(format) == format, supported);
+}
+
 void tst_QAbstractVideoSurface::start_data()
 {
     QTest::addColumn<QVideoSurfaceFormat>("format");
@@ -256,35 +274,35 @@ void tst_QAbstractVideoSurface::start()
     surface.setError(QAbstractVideoSurface::ResourceError);
 
     QSignalSpy formatSpy(&surface, SIGNAL(surfaceFormatChanged(QVideoSurfaceFormat)));
-    QSignalSpy startedSpy(&surface, SIGNAL(startedChanged(bool)));
+    QSignalSpy activeSpy(&surface, SIGNAL(activeChanged(bool)));
 
-    QVERIFY(!surface.isStarted());
+    QVERIFY(!surface.isActive());
     QCOMPARE(surface.surfaceFormat(), QVideoSurfaceFormat());
 
     QVERIFY(surface.start(format));
 
-    QVERIFY(surface.isStarted());
+    QVERIFY(surface.isActive());
     QCOMPARE(surface.surfaceFormat(), format);
 
     QCOMPARE(formatSpy.count(), 1);
-    QCOMPARE(qvariant_cast<QVideoSurfaceFormat>(formatSpy.at(0).at(0)), format);
+    QCOMPARE(qvariant_cast<QVideoSurfaceFormat>(formatSpy.last().at(0)), format);
 
-    QCOMPARE(startedSpy.count(), 1);
-    QCOMPARE(startedSpy.at(0).at(0).toBool(), true);
+    QCOMPARE(activeSpy.count(), 1);
+    QCOMPARE(activeSpy.last().at(0).toBool(), true);
 
     // error() is reset on a successful start.
     QCOMPARE(surface.error(), QAbstractVideoSurface::NoError);
 
     surface.stop();
 
-    QVERIFY(!surface.isStarted());
+    QVERIFY(!surface.isActive());
     QCOMPARE(surface.surfaceFormat(), QVideoSurfaceFormat());
 
     QCOMPARE(formatSpy.count(), 2);
-    QCOMPARE(qvariant_cast<QVideoSurfaceFormat>(formatSpy.at(1).at(0)), QVideoSurfaceFormat());
+    QCOMPARE(qvariant_cast<QVideoSurfaceFormat>(formatSpy.last().at(0)), QVideoSurfaceFormat());
 
-    QCOMPARE(startedSpy.count(), 2);
-    QCOMPARE(startedSpy.at(1).at(0).toBool(), false);
+    QCOMPARE(activeSpy.count(), 2);
+    QCOMPARE(activeSpy.last().at(0).toBool(), false);
 }
 
 QTEST_MAIN(tst_QAbstractVideoSurface)