summaryrefslogtreecommitdiffstats
path: root/src/multimedia/video/qabstractvideosurface.cpp
diff options
context:
space:
mode:
Diffstat (limited to 'src/multimedia/video/qabstractvideosurface.cpp')
-rw-r--r--src/multimedia/video/qabstractvideosurface.cpp283
1 files changed, 283 insertions, 0 deletions
diff --git a/src/multimedia/video/qabstractvideosurface.cpp b/src/multimedia/video/qabstractvideosurface.cpp
new file mode 100644
index 0000000..3dabb6b
--- /dev/null
+++ b/src/multimedia/video/qabstractvideosurface.cpp
@@ -0,0 +1,283 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the QtMultimedia module 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 Technology Preview License Agreement accompanying
+** this package.
+**
+** 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.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "qabstractvideosurface_p.h"
+
+QT_BEGIN_NAMESPACE
+
+/*!
+ \class QAbstractVideoSurface
+ \brief The QAbstractVideoSurface class is a base class for video presentation surfaces.
+ \since 4.6
+
+ The QAbstractVideoSurface class defines the standard interface that video producers use to
+ inter-operate with video presentation surfaces. It is not supposed to be instantiated directly.
+ Instead, you should subclass it to create new video surfaces.
+
+ A video surface presents a continuous stream of identically formatted frames, where the format
+ 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 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.
+
+ The start() function takes a supported format and enables a video surface. Once started a
+ surface will begin displaying the frames it receives in the present() function. Surfaces may
+ hold a reference to the buffer of a presented video frame until a new frame is presented or
+ streaming is stopped. The stop() function will disable a surface and a release any video
+ buffers it holds references to.
+*/
+
+/*!
+ \enum QAbstractVideoSurface::Error
+ This enum describes the errors that may be returned by the error() function.
+
+ \value NoError No error occurred.
+ \value UnsupportedFormatError A video format was not supported.
+ \value IncorrectFormatError A video frame was not compatible with the format of the surface.
+ \value StoppedError The surface has not been started.
+ \value ResourceError The surface could not allocate some resource.
+*/
+
+/*!
+ Constructs a video surface with the given \a parent.
+*/
+
+QAbstractVideoSurface::QAbstractVideoSurface(QObject *parent)
+ : QObject(*new QAbstractVideoSurfacePrivate, parent)
+{
+}
+
+/*!
+ \internal
+*/
+
+QAbstractVideoSurface::QAbstractVideoSurface(QAbstractVideoSurfacePrivate &dd, QObject *parent)
+ : QObject(dd, parent)
+{
+}
+
+/*!
+ Destroys a video surface.
+*/
+
+QAbstractVideoSurface::~QAbstractVideoSurface()
+{
+}
+
+/*!
+ \fn QAbstractVideoSurface::supportedPixelFormats(QAbstractVideoBuffer::HandleType type) const
+
+ Returns a list of pixel formats a video surface can present for a given handle \a type.
+
+ The pixel formats returned for the QAbstractVideoBuffer::NoHandle type are valid for any buffer
+ that can be mapped in read-only mode.
+
+ Types that are first in the list can be assumed to be faster to render.
+*/
+
+/*!
+ 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) const
+{
+ 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.
+
+ \sa supportedPixelFormats(), isFormatSupported()
+*/
+
+/*!
+ Returns the format of a video surface.
+*/
+
+QVideoSurfaceFormat QAbstractVideoSurface::surfaceFormat() const
+{
+ return d_func()->format;
+}
+
+/*!
+ \fn QAbstractVideoSurface::surfaceFormatChanged(const QVideoSurfaceFormat &format)
+
+ Signals that the configured \a format of a video surface has changed.
+
+ \sa surfaceFormat(), start()
+*/
+
+/*!
+ Starts a video surface presenting \a format frames.
+
+ Returns true if the surface was started, and false if an error occurred.
+
+ \sa isActive(), stop()
+*/
+
+bool QAbstractVideoSurface::start(const QVideoSurfaceFormat &format)
+{
+ Q_D(QAbstractVideoSurface);
+
+ bool wasActive = d->active;
+
+ d->active = true;
+ d->format = format;
+ d->error = NoError;
+
+ emit surfaceFormatChanged(d->format);
+
+ if (!wasActive)
+ emit activeChanged(true);
+
+ return true;
+}
+
+/*!
+ Stops a video surface presenting frames and releases any resources acquired in start().
+
+ \sa isActive(), start()
+*/
+
+void QAbstractVideoSurface::stop()
+{
+ Q_D(QAbstractVideoSurface);
+
+ if (d->active) {
+ d->format = QVideoSurfaceFormat();
+ d->active = false;
+
+ emit activeChanged(false);
+ emit surfaceFormatChanged(d->format);
+ }
+}
+
+/*!
+ Indicates whether a video surface has been started.
+
+ Returns true if the surface has been started, and false otherwise.
+*/
+
+bool QAbstractVideoSurface::isActive() const
+{
+ return d_func()->active;
+}
+
+/*!
+ \fn QAbstractVideoSurface::activeChanged(bool active)
+
+ Signals that the \a active state of a video surface has changed.
+
+ \sa isActive(), start(), stop()
+*/
+
+/*!
+ \fn QAbstractVideoSurface::present(const QVideoFrame &frame)
+
+ Presents a video \a frame.
+
+ Returns true if the frame was presented, and false if an error occurred.
+
+ Not all surfaces will block until the presentation of a frame has completed. Calling present()
+ on a non-blocking surface may fail if called before the presentation of a previous frame has
+ completed. In such cases the surface may not return to a ready state until it's had an
+ opportunity to process events.
+
+ If present() fails for any other reason the surface will immediately enter the stopped state
+ and an error() value will be set.
+
+ A video surface must be in the started state for present() to succeed, and the format of the
+ video frame must be compatible with the current video surface format.
+
+ \sa error()
+*/
+
+/*!
+ Returns the last error that occurred.
+
+ If a surface fails to start(), or stops unexpectedly this function can be called to discover
+ what error occurred.
+*/
+
+QAbstractVideoSurface::Error QAbstractVideoSurface::error() const
+{
+ return d_func()->error;
+}
+
+/*!
+ Sets the value of error() to \a error.
+*/
+
+void QAbstractVideoSurface::setError(Error error)
+{
+ Q_D(QAbstractVideoSurface);
+
+ d->error = error;
+}
+
+QT_END_NAMESPACE