QAbstractVideoSurface Class Reference

The QAbstractVideoSurface class is a base class for video presentation surfaces. More...

#include <qabstractvideosurface.h>

Inheritance diagram for QAbstractVideoSurface:

Public Types
enum	Error {   NoError, UnsupportedFormatError, IncorrectFormatError, StoppedError,   ResourceError }
	This enum describes the errors that may be returned by the error() function. More...

Signals
void	activeChanged (bool active)
	Signals that the active state of a video surface has changed. More...
void	supportedFormatsChanged ()
	Signals that the set of formats supported by a video surface has changed. More...
void	surfaceFormatChanged (const QVideoSurfaceFormat &format)
	Signals that the configured format of a video surface has changed. More...
Signals inherited from QObject
void	destroyed (QObject *=0)
	This signal is emitted immediately before the object obj is destroyed, and can not be blocked. More...

Public Functions
Error	error () const
	Returns the last error that occurred. More...
bool	isActive () const
	Indicates whether a video surface has been started. More...
virtual bool	isFormatSupported (const QVideoSurfaceFormat &format) const
	Tests a video surface format to determine if a surface can accept it. More...
virtual QVideoSurfaceFormat	nearestFormat (const QVideoSurfaceFormat &format) const
	Returns a supported video surface format that is similar to format. More...
virtual bool	present (const QVideoFrame &frame)=0
	Presents a video frame. More...
	QAbstractVideoSurface (QObject *parent=0)
	Constructs a video surface with the given parent. More...
virtual bool	start (const QVideoSurfaceFormat &format)
	Starts a video surface presenting format frames. More...
virtual void	stop ()
	Stops a video surface presenting frames and releases any resources acquired in start(). More...
virtual QList< QVideoFrame::PixelFormat >	supportedPixelFormats (QAbstractVideoBuffer::HandleType handleType=QAbstractVideoBuffer::NoHandle) const =0
	Returns a list of pixel formats a video surface can present for a given handle type. More...
QVideoSurfaceFormat	surfaceFormat () const
	Returns the format of a video surface. More...
	~QAbstractVideoSurface ()
	Destroys a video surface. More...
Public Functions inherited from QObject
bool	blockSignals (bool b)
	If block is true, signals emitted by this object are blocked (i.e., emitting a signal will not invoke anything connected to it). More...
const QObjectList &	children () const
	Returns a list of child objects. More...
bool	connect (const QObject *sender, const char *signal, const char *member, Qt::ConnectionType type=Qt::AutoConnection) const
bool	disconnect (const char *signal=0, const QObject *receiver=0, const char *member=0)
bool	disconnect (const QObject *receiver, const char *member=0)
void	dumpObjectInfo ()
	Dumps information about signal connections, etc. More...
void	dumpObjectTree ()
	Dumps a tree of children to the debug output. More...
QList< QByteArray >	dynamicPropertyNames () const
	Returns the names of all properties that were dynamically added to the object using setProperty(). More...
virtual bool	event (QEvent *)
	This virtual function receives events to an object and should return true if the event e was recognized and processed. More...
virtual bool	eventFilter (QObject *, QEvent *)
	Filters events if this object has been installed as an event filter for the watched object. More...
template<typename T >
T	findChild (const QString &aName=QString()) const
	Returns the child of this object that can be cast into type T and that is called name, or 0 if there is no such object. More...
template<typename T >
QList< T >	findChildren (const QString &aName=QString()) const
	Returns all children of this object with the given name that can be cast to type T, or an empty list if there are no such objects. More...
template<typename T >
QList< T >	findChildren (const QRegExp &re) const
bool	inherits (const char *classname) const
	Returns true if this object is an instance of a class that inherits className or a QObject subclass that inherits className; otherwise returns false. More...
void	installEventFilter (QObject *)
	Installs an event filter filterObj on this object. More...
bool	isWidgetType () const
	Returns true if the object is a widget; otherwise returns false. More...
void	killTimer (int id)
	Kills the timer with timer identifier, id. More...
virtual const QMetaObject *	metaObject () const
	Returns a pointer to the meta-object of this object. More...
void	moveToThread (QThread *thread)
	Changes the thread affinity for this object and its children. More...
QString	objectName () const
QObject *	parent () const
	Returns a pointer to the parent object. More...
QVariant	property (const char *name) const
	Returns the value of the object's name property. More...
Q_INVOKABLE	QObject (QObject *parent=0)
	Constructs an object with parent object parent. More...
void	removeEventFilter (QObject *)
	Removes an event filter object obj from this object. More...
void	setObjectName (const QString &name)
void	setParent (QObject *)
	Makes the object a child of parent. More...
bool	setProperty (const char *name, const QVariant &value)
	Sets the value of the object's name property to value. More...
void	setUserData (uint id, QObjectUserData *data)
bool	signalsBlocked () const
	Returns true if signals are blocked; otherwise returns false. More...
int	startTimer (int interval)
	Starts a timer and returns a timer identifier, or returns zero if it could not start a timer. More...
QThread *	thread () const
	Returns the thread in which the object lives. More...
QObjectUserData *	userData (uint id) const
virtual	~QObject ()
	Destroys the object, deleting all its child objects. More...

Protected Functions
	QAbstractVideoSurface (QAbstractVideoSurfacePrivate &dd, QObject *parent)
void	setError (Error error)
	Sets the value of error() to error. More...
Protected Functions inherited from QObject
virtual void	childEvent (QChildEvent *)
	This event handler can be reimplemented in a subclass to receive child events. More...
virtual void	connectNotify (const char *signal)
	This virtual function is called when something has been connected to signal in this object. More...
virtual void	customEvent (QEvent *)
	This event handler can be reimplemented in a subclass to receive custom events. More...
virtual void	disconnectNotify (const char *signal)
	This virtual function is called when something has been disconnected from signal in this object. More...
	QObject (QObjectPrivate &dd, QObject *parent=0)
int	receivers (const char *signal) const
	Returns the number of receivers connected to the signal. More...
QObject *	sender () const
	Returns a pointer to the object that sent the signal, if called in a slot activated by a signal; otherwise it returns 0. More...
int	senderSignalIndex () const
virtual void	timerEvent (QTimerEvent *)
	This event handler can be reimplemented in a subclass to receive timer events for the object. More...

Additional Inherited Members
Public Slots inherited from QObject
void	deleteLater ()
	Schedules this object for deletion. More...
Static Public Functions inherited from QObject
static bool	connect (const QObject *sender, const char *signal, const QObject *receiver, const char *member, Qt::ConnectionType=Qt::AutoConnection)
	Creates a connection of the given type from the signal in the sender object to the method in the receiver object. More...
static bool	connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type=Qt::AutoConnection)
static bool	disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *member)
	Disconnects signal in object sender from method in object receiver. More...
static bool	disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &member)
static uint	registerUserData ()
static QString	tr (const char *sourceText, const char *comment=0, int n=-1)
static QString	trUtf8 (const char *sourceText, const char *comment=0, int n=-1)
Static Public Variables inherited from QObject
static const QMetaObject	staticMetaObject
	This variable stores the meta-object for the class. More...
Protected Variables inherited from QObject
QScopedPointer< QObjectData >	d_ptr
Static Protected Variables inherited from QObject
static const QMetaObject	staticQtMetaObject
Related Functions inherited from QObject
T	qFindChildqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QString &name)()
QList< T >	qFindChildrenqFindChildren (const QObject *obj, const QRegExp &regExp)()
T *	qobject_cast (QObject *object)
	QObjectList
void *	qt_find_obj_child (QObject *parent, const char *type, const QString &name)
	Returns a pointer to the object named name that inherits type and with a given parent. More...

Detailed Description

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.

Definition at line 59 of file qabstractvideosurface.h.

Enumerations

Error

enum QAbstractVideoSurface::Error

This enum describes the errors that may be returned by the error() function.

• NoError No error occurred.
• UnsupportedFormatError A video format was not supported.
• IncorrectFormatError A video frame was not compatible with the format of the surface.
• StoppedError The surface has not been started.
• ResourceError The surface could not allocate some resource.

Enumerator
NoError
UnsupportedFormatError
IncorrectFormatError
StoppedError
ResourceError

Definition at line 64 of file qabstractvideosurface.h.

    {
        NoError,
        UnsupportedFormatError,
        IncorrectFormatError,
        StoppedError,
        ResourceError
    };

Constructors and Destructors

QAbstractVideoSurface() [1/2]

QAbstractVideoSurface::QAbstractVideoSurface ( QObject *  parent = 0 )

explicit

Constructs a video surface with the given parent.

Definition at line 92 of file qabstractvideosurface.cpp.

    : QObject(*new QAbstractVideoSurfacePrivate, parent)
{
}

~QAbstractVideoSurface()

QAbstractVideoSurface::~QAbstractVideoSurface

(

)

Destroys a video surface.

Definition at line 110 of file qabstractvideosurface.cpp.

{
}

QAbstractVideoSurface() [2/2]

QAbstractVideoSurface::QAbstractVideoSurface ( QAbstractVideoSurfacePrivate &  dd, QObject *  parent  )

protected

Warning

This function is not part of the public interface.

Definition at line 101 of file qabstractvideosurface.cpp.

    : QObject(dd, parent)
{
}

Functions

activeChanged

QAbstractVideoSurface::activeChanged ( bool  active )

signal

Signals that the active state of a video surface has changed.

See also

isActive(), start(), stop()

Referenced by start(), and stop().

error()

QAbstractVideoSurface::Error QAbstractVideoSurface::error

(

)

const

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.

Definition at line 288 of file qabstractvideosurface.cpp.

Referenced by setError().

{
    return d_func()->error;
}

isActive()

bool QAbstractVideoSurface::isActive

(

)

const

Indicates whether a video surface has been started.

Returns true if the surface has been started, and false otherwise.

Definition at line 241 of file qabstractvideosurface.cpp.

{
    return d_func()->active;
}

isFormatSupported()

bool QAbstractVideoSurface::isFormatSupported ( const QVideoSurfaceFormat &  format ) const

virtual

Tests a video surface format to determine if a surface can accept it.

Returns true if the format is supported by the surface, and false otherwise.

Definition at line 134 of file qabstractvideosurface.cpp.

Referenced by nearestFormat().

{
    return supportedPixelFormats(format.handleType()).contains(format.pixelFormat());
}

nearestFormat()

QVideoSurfaceFormat QAbstractVideoSurface::nearestFormat ( const QVideoSurfaceFormat &  format ) const

virtual

Returns a supported video surface format that is similar to format.

A similar surface format is one that has the same QVideoSurfaceFormat::pixelFormat(){pixel format} and QVideoSurfaceFormat::handleType(){handle type} but differs in some of the other properties. For example if there are restrictions on the QVideoSurfaceFormat::frameSize() {frame sizes} a video surface can accept it may suggest a format with a larger frame size and a 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.

Definition at line 152 of file qabstractvideosurface.cpp.

{
    return isFormatSupported(format)
            ? format
            : QVideoSurfaceFormat();
}

present()

QAbstractVideoSurface::present ( const QVideoFrame &  frame )

pure virtual

Presents a video 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.

See also

error()

setError()

void QAbstractVideoSurface::setError ( Error  error )

protected

Sets the value of error() to error.

Definition at line 297 of file qabstractvideosurface.cpp.

{
    Q_D(QAbstractVideoSurface);

    d->error = error;
}

start()

bool QAbstractVideoSurface::start ( const QVideoSurfaceFormat &  format )

virtual

Starts a video surface presenting format frames.

Returns true if the surface was started, and false if an error occurred.

See also

isActive(), stop()

Definition at line 198 of file qabstractvideosurface.cpp.

{
    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;
}

stop()

void QAbstractVideoSurface::stop ( )

virtual

Stops a video surface presenting frames and releases any resources acquired in start().

See also

isActive(), start()

Definition at line 222 of file qabstractvideosurface.cpp.

{
    Q_D(QAbstractVideoSurface);

    if (d->active) {
        d->format = QVideoSurfaceFormat();
        d->active = false;

        emit activeChanged(false);
        emit surfaceFormatChanged(d->format);
    }
}

supportedFormatsChanged

QAbstractVideoSurface::supportedFormatsChanged ( )

signal

Signals that the set of formats supported by a video surface has changed.

See also

supportedPixelFormats(), isFormatSupported()

supportedPixelFormats()

QAbstractVideoSurface::supportedPixelFormats ( QAbstractVideoBuffer::HandleType  type = QAbstractVideoBuffer::NoHandle ) const

pure virtual

Returns a list of pixel formats a video surface can present for a given handle 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.

Referenced by isFormatSupported().

surfaceFormat()

QVideoSurfaceFormat QAbstractVideoSurface::surfaceFormat

(

)

const

Returns the format of a video surface.

Definition at line 174 of file qabstractvideosurface.cpp.

{
    return d_func()->format;
}

surfaceFormatChanged

QAbstractVideoSurface::surfaceFormatChanged ( const QVideoSurfaceFormat &  format )

signal

Signals that the configured format of a video surface has changed.

See also

surfaceFormat(), start()

Referenced by start(), and stop().

---

The documentation for this class was generated from the following files:

• /src/multimedia/video/qabstractvideosurface.h
• /src/multimedia/video/qabstractvideosurface.cpp