Integrate QAbstractVideoSurface API.

This introduces a QAbstractVideoSurface interface for implementing arbitrary
video outputs, and a QVideoFrame type.  Also included is the
QVideoSurfaceFormat class which is used to configure the input to a video
surface, and the QAbstractVideoBuffer class which allows QVideoFrames
to be constructed from non-native frame types.

Reviewed-by: Dmytro Poplavskiy

5 files changed, 246 insertions, 0 deletions

diff --git a/doc/src/examples/videographicsitem.qdoc b/doc/src/examples/videographicsitem.qdoc
new file mode 100644
index 0000000..861b587
--- /dev/null
+++ b/doc/src/examples/videographicsitem.qdoc
@@ -0,0 +1,52 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example video/videographicsitem
+    \title Video Graphics Item Example
+
+    The Video Graphics Item example shows how to implement a QGraphicsItem that displays video on a
+    graphics scene using QtMultimedia's QAbstractVideoSurface.
+
+    \image video-videographicsitem.png
+
+    \sa {Video Widget Example}
+*/
diff --git a/doc/src/examples/videowidget.qdoc b/doc/src/examples/videowidget.qdoc
new file mode 100644
index 0000000..27d5711
--- /dev/null
+++ b/doc/src/examples/videowidget.qdoc
@@ -0,0 +1,187 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain
+** additional rights. These rights are described in the Nokia Qt LGPL
+** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example video/videowidget
+    \title Video Widget Example
+
+    The Video Widget example shows how to implement a video widget using
+    QtMultimedia's QAbstractVideoSurface
+
+    \image video-videowidget.png
+
+    \section1 VideoWidgetSurface Class Definition
+
+    \snippet examples/video/videowidget/videowidgetsurface.h 0
+
+    The VideoWidgetSurface class inherits QAbstractVideoSurface and paints
+    video frames on a QWidget.  This is a separate class to VideoWidget as both
+    QAbstractVideoSurface and QWidget inherit QObject.
+
+    In addition to the functions from QAbstractVideoSurface, VideoWidgetSurface
+    has functions for determining the video display rectangle, and painting
+    the video.
+
+    \section1 VideoWidgetSurface Class Implementation
+
+    \snippet examples/video/videowidget/videowidgetsurface.cpp 0
+
+    From the supportedPixelFormats() function we return a list of pixel formats
+    the surface can paint. The order of the list hints at which formats are
+    preferred by the surface.  Assuming a 32-bit RGB backbuffer, we'd expect
+    that a 32-bit RGB type with no alpha to be fastest to paint so
+    QVideoFrame::Image_RGB32 is first in the list.
+
+    Since we don't support rendering using any special frame handles we don't
+    return any pixel formats if handleType is not
+    QAbstractVideoBuffer::NoHandle.
+
+    \snippet examples/video/videowidget/videowidgetsurface.cpp 1
+
+    In isFormatSupported() we test if the frame type of a surface format maps
+    to a valid QImage format, that the frame size is not empty, and the handle
+    type is QAbstractVideoBuffer::NoHandle.  Note that the
+    QAbstractVideoSurface implementation of isFormatSupported() will verify
+    that the list of supported pixel formats returned by
+    \c supportedPixelFormats(format.handleType()) contains the pixel format and
+    that the size is not empty so a reimplementation wasn't strictly necessary
+    in this case.
+
+    \snippet examples/video/videowidget/videowidgetsurface.cpp 2
+
+    To start our surface we'll extract the image format and size from the
+    selected video format and save it for use in the paint() function.  If the
+    image format, or size are invalid then we'll set an error and return false.
+    Otherwise we'll save the format and confirm the surface has been started,
+    by calling QAbstractVideoSurface::start(). Finally since the video size may
+    have changed we'll trigger an update of the widget, and video geometry.
+
+    \snippet examples/video/videowidget/videowidgetsurface.cpp 5
+
+    The updateVideoRect() function calculates the region within the widget the
+    video occupies.  The \l {QVideoSurfaceFormat::sizeHint()}{size hint} of the
+    video format gives a suggested size for the video calculated from the
+    \l {QVideoSurfaceFormat::viewport()}{viewport} and
+    \l {QVideoSurfaceFormat::pixelAspectRatio()}{pixel aspect ratio}.  If the
+    suggested size fits within the widget then we create a new rect of that
+    size in the center of the widget.  Otherwise we shrink the size maintaining
+    the aspect ratio so that it does fit.
+
+    \snippet examples/video/videowidget/videowidgetsurface.cpp 4
+
+    We can't paint from outside a paint event, so when a new frame is received
+    in present() we save a reference to it and force an immediate repaint of
+    the video region.  We retain the saved reference to the frame after the
+    repaint so that the widget can be repainted between frame changes if
+    necessary.
+
+    If the format of the frame doesn't match the surface format we can't paint
+    it or very likely any future frames.  So we set an
+    \l {QAbstractVideoSurface::UnsupportedFormatError}{UnsupportedFormatError}
+    on our surface and stop it immediately.
+
+    \snippet examples/video/videowidget/videowidgetsurface.cpp 6
+
+    The paint() function is called by the video widget to paint the current
+    video frame.  Before we draw the frame first we'll check the format for
+    the scan line direction and if the scan lines are arranged from bottom to
+    top we'll flip the painter so the frame isn't drawn upside down.  Then
+    using the image format information saved in the start() function we'll
+    construct a new QImage from the current video frame, and draw it to the
+    the widget.
+
+    \snippet examples/video/videowidget/videowidgetsurface.cpp 3
+
+    When the surface is stopped we need to release the current frame and
+    invalidate the video region.   Then we confirm the surface has been
+    stopped by calling QAbstractVideoSurface::stop() which sets the started
+    state to false and finally we update so the video widget so paints over
+    the last frame.
+
+    \section1 VideoWidget Class Definition
+
+    The VideoWidget class uses the VideoWidgetSurface class to implement a
+    video widget.
+
+    \snippet examples/video/videowidget/videowidget.h 0
+
+    The VideoWidget QWidget implementation is minimal with just the sizeHint(),
+    paintEvent(), and resizeEvent() functions in addition to the constructor,
+    destructor and an instance of VideoWidgetSurface.
+
+    \section1 VideoWidget Class Implementation
+
+    \snippet examples/video/videowidget/videowidget.cpp 0
+
+    In the VideoWidget constructor we set some flags to speed up re-paints a
+    little.  Setting the Qt::WA_NoSystemBackground flag and disabling automatic
+    background fills will stop Qt from a painting a background that'll be
+    completely obscured by the video.  The Qt::WA_PaintOnScreen flag will
+    allow us to paint to the screen instead of the back buffer where supported.
+
+    Next we set the background color to black, so that any borders around the
+    video are filled in black rather the default background color.
+
+    Finally we construct an instance of the VideoWidgetSurface class.
+
+    \snippet examples/video/videowidget/videowidget.cpp 1
+
+    In the destructor we simply delete the VideoWidgetSurface instance.
+
+    \snippet examples/video/videowidget/videowidget.cpp 2
+
+    We get the size hint for the widget from the video format of the surface
+    which is calculated from viewport and pixel aspect ratio of the video
+    format.
+
+    \snippet examples/video/videowidget/videowidget.cpp 3
+
+    When the video widget receives a paint event we first check if the surface
+    is started,  if not then we simply fill the widget with the background
+    color.  If it is then we draw a border around the video region clipped
+    by the paint region, before calling paint on the video surface to draw the
+    current frame.
+
+    \snippet examples/video/videowidget/videowidget.cpp 4
+
+    The resizeEvent() function is reimplemented to trigger an update of the
+    video region when the widget is resized.
+*/
diff --git a/doc/src/getting-started/examples.qdoc b/doc/src/getting-started/examples.qdoc
index 253a4e4..b0d6bf6 100644
--- a/doc/src/getting-started/examples.qdoc
+++ b/doc/src/getting-started/examples.qdoc
@@ -796,6 +796,13 @@
     \o \l{multimedia/audio/audioinput}{Audio Input}
     \endlist
 
+    \section1 Video Output
+
+    \list
+    \o \l{video/videowidget}{Video Widget}\raisedaster
+    \o \l{video/videographicsitem}{Video Graphics Item}
+    \endlist
+
     \section1 Phonon
 
     The Phonon Multimedia Framework brings multimedia support to Qt applications.
diff --git a/doc/src/images/video-videographicsitem.png b/doc/src/images/video-videographicsitem.png
new file mode 100644
index 0000000..e333c54
--- /dev/null
+++ b/doc/src/images/video-videographicsitem.png
diff --git a/doc/src/images/video-videowidget.png b/doc/src/images/video-videowidget.png
new file mode 100644
index 0000000..a3c7bcb
--- /dev/null
+++ b/doc/src/images/video-videowidget.png