QVideoSurfaceFormat Class Reference

The QVideoSurfaceFormat class specifies the stream format of a video presentation surface. More...

#include <qvideosurfaceformat.h>

Public Types
enum	Direction { TopToBottom, BottomToTop }
	Enumerates the layout direction of video scan lines. More...
enum	YCbCrColorSpace {   YCbCr_Undefined, YCbCr_BT601, YCbCr_BT709, YCbCr_xvYCC601,   YCbCr_xvYCC709, YCbCr_JPEG }
	Enumerates the Y'CbCr color space of video frames. More...

Public Functions
int	frameHeight () const
	Returns the height of frame in a video stream. More...
qreal	frameRate () const
	Returns the frame rate of a video stream in frames per second. More...
QSize	frameSize () const
	Returns the size of frames in a video stream. More...
int	frameWidth () const
	Returns the width of frames in a video stream. More...
QAbstractVideoBuffer::HandleType	handleType () const
	Returns the type of handle the surface uses to present the frame data. More...
bool	isValid () const
	Identifies if a video surface format has a valid pixel format and frame size. More...
bool	operator!= (const QVideoSurfaceFormat &format) const
	Returns true if other is different to a video format, and false if they are the same. More...
QVideoSurfaceFormat &	operator= (const QVideoSurfaceFormat &format)
	Assigns the values of other to a video stream description. More...
bool	operator== (const QVideoSurfaceFormat &format) const
	Returns true if other is the same as a video format, and false if they are the different. More...
QSize	pixelAspectRatio () const
	Returns a video stream's pixel aspect ratio. More...
QVideoFrame::PixelFormat	pixelFormat () const
	Returns the pixel format of frames in a video stream. More...
QVariant	property (const char *name) const
	Returns the value of the video format's name property. More...
QList< QByteArray >	propertyNames () const
	Returns a list of video format dynamic property names. More...
	QVideoSurfaceFormat ()
	Constructs a null video stream format. More...
	QVideoSurfaceFormat (const QSize &size, QVideoFrame::PixelFormat pixelFormat, QAbstractVideoBuffer::HandleType handleType=QAbstractVideoBuffer::NoHandle)
	Contructs a description of stream which receives stream of type buffers with given frame size and pixel format. More...
	QVideoSurfaceFormat (const QVideoSurfaceFormat &format)
	Constructs a copy of other. More...
Direction	scanLineDirection () const
	Returns the direction of scan lines. More...
void	setFrameRate (qreal rate)
	Sets the frame rate of a video stream in frames per second. More...
void	setFrameSize (const QSize &size)
	Sets the size of frames in a video stream to size. More...
void	setFrameSize (int width, int height)
	Sets the width and height of frames in a video stream. More...
void	setPixelAspectRatio (const QSize &ratio)
	Sets a video stream's pixel aspect ratio. More...
void	setPixelAspectRatio (int width, int height)
	Sets the horizontal and vertical elements of a video stream's pixel aspect ratio. More...
void	setProperty (const char *name, const QVariant &value)
	Sets the video format's name property to value. More...
void	setScanLineDirection (Direction direction)
	Sets the direction of scan lines. More...
void	setViewport (const QRect &viewport)
	Sets the viewport of a video stream to viewport. More...
void	setYCbCrColorSpace (YCbCrColorSpace colorSpace)
	Sets the Y'CbCr color space of a video stream. More...
QSize	sizeHint () const
	Returns a suggested size in pixels for the video stream. More...
QRect	viewport () const
	Returns the viewport of a video stream. More...
YCbCrColorSpace	yCbCrColorSpace () const
	Returns the Y'CbCr color space of a video stream. More...
	~QVideoSurfaceFormat ()
	Destroys a video stream description. More...

Properties
QSharedDataPointer< QVideoSurfaceFormatPrivate >	d

Detailed Description

The QVideoSurfaceFormat class specifies the stream format of a video presentation surface.

Since

4.6

A video surface presents a stream of video frames. The surface's format describes the type of the frames and determines how they should be presented.

The core properties of a video stream required to setup a video surface are the pixel format given by pixelFormat(), and the frame dimensions given by frameSize().

If the surface is to present frames using a frame's handle a surface format will also include a handle type which is given by the handleType() function.

The region of a frame that is actually displayed on a video surface is given by the viewport(). A stream may have a viewport less than the entire region of a frame to allow for videos smaller than the nearest optimal size of a video frame. For example the width of a frame may be extended so that the start of each scan line is eight byte aligned.

Other common properties are the pixelAspectRatio(), scanLineDirection(), and frameRate(). Additionally a stream may have some additional type specific properties which are listed by the dynamicPropertyNames() function and can be accessed using the property(), and setProperty() functions.

Definition at line 62 of file qvideosurfaceformat.h.

Enumerations

Direction

enum QVideoSurfaceFormat::Direction

Enumerates the layout direction of video scan lines.

• TopToBottom Scan lines are arranged from the top of the frame to the bottom.
• BottomToTop Scan lines are arranged from the bottom of the frame to the top.

Enumerator
TopToBottom
BottomToTop

Definition at line 65 of file qvideosurfaceformat.h.

    {
        TopToBottom,
        BottomToTop
    };

YCbCrColorSpace

enum QVideoSurfaceFormat::YCbCrColorSpace

Enumerates the Y'CbCr color space of video frames.

• YCbCr_Undefined No color space is specified.

• YCbCr_BT601 A Y'CbCr color space defined by ITU-R recommendation BT.601 with Y value range from 16 to 235, and Cb/Cr range from 16 to 240. Used in standard definition video.

• YCbCr_BT709 A Y'CbCr color space defined by ITU-R BT.709 with the same values range as YCbCr_BT601. Used for HDTV.

• YCbCr_xvYCC601 The BT.601 color space with the value range extended to 0 to 255. It is backward compatibile with BT.601 and uses values outside BT.601 range to represent wider colors range.

• YCbCr_xvYCC709 The BT.709 color space with the value range extended to 0 to 255.

• YCbCr_JPEG The full range Y'CbCr color space used in JPEG files.

Enumerator
YCbCr_Undefined
YCbCr_BT601
YCbCr_BT709
YCbCr_xvYCC601
YCbCr_xvYCC709
YCbCr_JPEG

Definition at line 71 of file qvideosurfaceformat.h.

    {
        YCbCr_Undefined,
        YCbCr_BT601,
        YCbCr_BT709,
        YCbCr_xvYCC601,
        YCbCr_xvYCC709,
        YCbCr_JPEG,
#ifndef qdoc
        YCbCr_CustomMatrix
#endif
    };

Constructors and Destructors

QVideoSurfaceFormat() [1/3]

QVideoSurfaceFormat::QVideoSurfaceFormat

(

)

Constructs a null video stream format.

Definition at line 212 of file qvideosurfaceformat.cpp.

    : d(new QVideoSurfaceFormatPrivate)
{
}

QVideoSurfaceFormat() [2/3]

QVideoSurfaceFormat::QVideoSurfaceFormat	(	const QSize &	size,
		QVideoFrame::PixelFormat	pixelFormat,
		QAbstractVideoBuffer::HandleType	handleType = QAbstractVideoBuffer::NoHandle
	)

Contructs a description of stream which receives stream of type buffers with given frame size and pixel format.

Definition at line 222 of file qvideosurfaceformat.cpp.

    : d(new QVideoSurfaceFormatPrivate(size, format, type))
{
}

QVideoSurfaceFormat() [3/3]

QVideoSurfaceFormat::QVideoSurfaceFormat

(

const QVideoSurfaceFormat &

format

)

Constructs a copy of other.

Definition at line 232 of file qvideosurfaceformat.cpp.

    : d(other.d)
{
}

~QVideoSurfaceFormat()

QVideoSurfaceFormat::~QVideoSurfaceFormat

(

)

Destroys a video stream description.

Definition at line 252 of file qvideosurfaceformat.cpp.

{
}

Functions

frameHeight()

int QVideoSurfaceFormat::frameHeight

(

)

const

Returns the height of frame in a video stream.

Definition at line 334 of file qvideosurfaceformat.cpp.

{
    return d->frameSize.height();
}

frameRate()

qreal QVideoSurfaceFormat::frameRate

(

)

const

Returns the frame rate of a video stream in frames per second.

Definition at line 412 of file qvideosurfaceformat.cpp.

{
    return d->frameRate;
}

frameSize()

QSize QVideoSurfaceFormat::frameSize

(

)

const

Returns the size of frames in a video stream.

See also

frameWidth(), frameHeight()

Definition at line 314 of file qvideosurfaceformat.cpp.

Referenced by operator<<().

{
    return d->frameSize;
}

frameWidth()

int QVideoSurfaceFormat::frameWidth

(

)

const

Returns the width of frames in a video stream.

See also

frameSize(), frameHeight()

Definition at line 325 of file qvideosurfaceformat.cpp.

{
    return d->frameSize.width();
}

handleType()

QAbstractVideoBuffer::HandleType QVideoSurfaceFormat::handleType

(

)

const

Returns the type of handle the surface uses to present the frame data.

If the handle type is QAbstractVideoBuffer::NoHandle buffers with any handle type are valid provided they can be QAbstractVideoBuffer::map(){mapped} with the QAbstractVideoBuffer::ReadOnly flag. If the handleType() is not QAbstractVideoBuffer::NoHandle then the handle type of the buffer be the same as that of the surface format.

Definition at line 303 of file qvideosurfaceformat.cpp.

Referenced by QAbstractVideoSurface::isFormatSupported().

{
    return d->handleType;
}

isValid()

bool QVideoSurfaceFormat::isValid

(

)

const

Identifies if a video surface format has a valid pixel format and frame size.

Returns true if the format is valid, and false otherwise.

Definition at line 262 of file qvideosurfaceformat.cpp.

{
    return d->pixelFormat != QVideoFrame::Format_Invalid && d->frameSize.isValid();
}

operator!=()

bool QVideoSurfaceFormat::operator!=

(

const QVideoSurfaceFormat &

format

)

const

Returns true if other is different to a video format, and false if they are the same.

Definition at line 280 of file qvideosurfaceformat.cpp.

{
    return d != other.d && !(*d == *other.d);
}

operator=()

QVideoSurfaceFormat & QVideoSurfaceFormat::operator=

(

const QVideoSurfaceFormat &

format

)

Assigns the values of other to a video stream description.

Definition at line 241 of file qvideosurfaceformat.cpp.

{
    d = other.d;

    return *this;
}

operator==()

bool QVideoSurfaceFormat::operator==

(

const QVideoSurfaceFormat &

format

)

const

Returns true if other is the same as a video format, and false if they are the different.

Definition at line 271 of file qvideosurfaceformat.cpp.

{
    return d == other.d || *d == *other.d;
}

pixelAspectRatio()

QSize QVideoSurfaceFormat::pixelAspectRatio

(

)

const

Returns a video stream's pixel aspect ratio.

Definition at line 430 of file qvideosurfaceformat.cpp.

Referenced by operator<<().

{
    return d->pixelAspectRatio;
}

pixelFormat()

QVideoFrame::PixelFormat QVideoSurfaceFormat::pixelFormat

(

)

const

Returns the pixel format of frames in a video stream.

Definition at line 289 of file qvideosurfaceformat.cpp.

Referenced by QAbstractVideoSurface::isFormatSupported(), and operator<<().

{
    return d->pixelFormat;
}

property()

QVariant QVideoSurfaceFormat::property

(

const char *

name

)

const

Returns the value of the video format's name property.

Definition at line 517 of file qvideosurfaceformat.cpp.

Referenced by operator<<().

{
    if (qstrcmp(name, "handleType") == 0) {
        return QVariant::fromValue(d->handleType);
    } else if (qstrcmp(name, "pixelFormat") == 0) {
        return QVariant::fromValue(d->pixelFormat);
    } else if (qstrcmp(name, "handleType") == 0) {
        return QVariant::fromValue(d->handleType);
    } else if (qstrcmp(name, "frameSize") == 0) {
        return d->frameSize;
    } else if (qstrcmp(name, "frameWidth") == 0) {
        return d->frameSize.width();
    } else if (qstrcmp(name, "frameHeight") == 0) {
        return d->frameSize.height();
    } else if (qstrcmp(name, "viewport") == 0) {
        return d->viewport;
    } else if (qstrcmp(name, "scanLineDirection") == 0) {
        return QVariant::fromValue(d->scanLineDirection);
    } else if (qstrcmp(name, "frameRate") == 0) {
        return QVariant::fromValue(d->frameRate);
    } else if (qstrcmp(name, "pixelAspectRatio") == 0) {
        return QVariant::fromValue(d->pixelAspectRatio);
    } else if (qstrcmp(name, "sizeHint") == 0) {
        return sizeHint();
    } else if (qstrcmp(name, "yCbCrColorSpace") == 0) {
        return QVariant::fromValue(d->ycbcrColorSpace);
    } else {
        int id = 0;
        for (; id < d->propertyNames.count() && d->propertyNames.at(id) != name; ++id) {}

        return id < d->propertyValues.count()
                ? d->propertyValues.at(id)
                : QVariant();
    }
}

propertyNames()

QList< QByteArray > QVideoSurfaceFormat::propertyNames

(

)

const

Returns a list of video format dynamic property names.

Definition at line 497 of file qvideosurfaceformat.cpp.

Referenced by operator<<().

{
    return (QList<QByteArray>()
            << "handleType"
            << "pixelFormat"
            << "frameSize"
            << "frameWidth"
            << "viewport"
            << "scanLineDirection"
            << "frameRate"
            << "pixelAspectRatio"
            << "sizeHint"
            << "yCbCrColorSpace")
            + d->propertyNames;
}

scanLineDirection()

QVideoSurfaceFormat::Direction QVideoSurfaceFormat::scanLineDirection

(

)

const

Returns the direction of scan lines.

Definition at line 394 of file qvideosurfaceformat.cpp.

{
    return d->scanLineDirection;
}

setFrameRate()

void QVideoSurfaceFormat::setFrameRate

(

qreal

rate

)

Sets the frame rate of a video stream in frames per second.

Definition at line 421 of file qvideosurfaceformat.cpp.

{
    d->frameRate = rate;
}

setFrameSize() [1/2]

void QVideoSurfaceFormat::setFrameSize

(

const QSize &

size

)

Sets the size of frames in a video stream to size.

This will reset the viewport() to fill the entire frame.

Definition at line 345 of file qvideosurfaceformat.cpp.

{
    d->frameSize = size;
    d->viewport = QRect(QPoint(0, 0), size);
}

setFrameSize() [2/2]

void QVideoSurfaceFormat::setFrameSize	(	int	width,
		int	height
	)

Sets the width and height of frames in a video stream.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This will reset the viewport() to fill the entire frame.

Definition at line 362 of file qvideosurfaceformat.cpp.

{
    d->frameSize = QSize(width, height);
    d->viewport = QRect(0, 0, width, height);
}

setPixelAspectRatio() [1/2]

void QVideoSurfaceFormat::setPixelAspectRatio

(

const QSize &

ratio

)

Sets a video stream's pixel aspect ratio.

Definition at line 439 of file qvideosurfaceformat.cpp.

{
    d->pixelAspectRatio = ratio;
}

setPixelAspectRatio() [2/2]

void QVideoSurfaceFormat::setPixelAspectRatio	(	int	horizontal,
		int	vertical
	)

Sets the horizontal and vertical elements of a video stream's pixel aspect ratio.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 453 of file qvideosurfaceformat.cpp.

{
    d->pixelAspectRatio = QSize(horizontal, vertical);
}

setProperty()

void QVideoSurfaceFormat::setProperty	(	const char *	name,
		const QVariant &	value
	)

Sets the video format's name property to value.

Definition at line 557 of file qvideosurfaceformat.cpp.

{
    if (qstrcmp(name, "handleType") == 0) {
        // read only.
    } else if (qstrcmp(name, "pixelFormat") == 0) {
        // read only.
    } else if (qstrcmp(name, "frameSize") == 0) {
        if (value.canConvert<QSize>()) {
            d->frameSize = qvariant_cast<QSize>(value);
            d->viewport = QRect(QPoint(0, 0), d->frameSize);
        }
    } else if (qstrcmp(name, "frameWidth") == 0) {
        // read only.
    } else if (qstrcmp(name, "frameHeight") == 0) {
        // read only.
    } else if (qstrcmp(name, "viewport") == 0) {
        if (value.canConvert<QRect>())
            d->viewport = qvariant_cast<QRect>(value);
    } else if (qstrcmp(name, "scanLineDirection") == 0) {
        if (value.canConvert<Direction>())
            d->scanLineDirection = qvariant_cast<Direction>(value);
    } else if (qstrcmp(name, "frameRate") == 0) {
        if (value.canConvert<qreal>())
            d->frameRate = qvariant_cast<qreal>(value);
    } else if (qstrcmp(name, "pixelAspectRatio") == 0) {
        if (value.canConvert<QSize>())
            d->pixelAspectRatio = qvariant_cast<QSize>(value);
    } else if (qstrcmp(name, "sizeHint") == 0) {
        // read only.
    } else if (qstrcmp(name, "yCbCrColorSpace") == 0) {
          if (value.canConvert<YCbCrColorSpace>())
              d->ycbcrColorSpace = qvariant_cast<YCbCrColorSpace>(value);
    } else {
        int id = 0;
        for (; id < d->propertyNames.count() && d->propertyNames.at(id) != name; ++id) {}

        if (id < d->propertyValues.count()) {
            if (value.isNull()) {
                d->propertyNames.removeAt(id);
                d->propertyValues.removeAt(id);
            } else {
                d->propertyValues[id] = value;
            }
        } else if (!value.isNull()) {
            d->propertyNames.append(QByteArray(name));
            d->propertyValues.append(value);
        }
    }
}

setScanLineDirection()

void QVideoSurfaceFormat::setScanLineDirection

(

Direction

direction

)

Sets the direction of scan lines.

Definition at line 403 of file qvideosurfaceformat.cpp.

{
    d->scanLineDirection = direction;
}

setViewport()

void QVideoSurfaceFormat::setViewport

(

const QRect &

viewport

)

Sets the viewport of a video stream to viewport.

Definition at line 385 of file qvideosurfaceformat.cpp.

{
    d->viewport = viewport;
}

setYCbCrColorSpace()

void QVideoSurfaceFormat::setYCbCrColorSpace

(

QVideoSurfaceFormat::YCbCrColorSpace

space

)

Sets the Y'CbCr color space of a video stream.

It is only used with raw YUV frame types.

Definition at line 472 of file qvideosurfaceformat.cpp.

{
    d->ycbcrColorSpace = space;
}

sizeHint()

QSize QVideoSurfaceFormat::sizeHint

(

)

const

Returns a suggested size in pixels for the video stream.

This is the size of the viewport scaled according to the pixel aspect ratio.

Definition at line 483 of file qvideosurfaceformat.cpp.

Referenced by property().

{
    QSize size = d->viewport.size();

    if (d->pixelAspectRatio.height() != 0)
        size.setWidth(size.width() * d->pixelAspectRatio.width() / d->pixelAspectRatio.height());

    return size;
}

viewport()

QRect QVideoSurfaceFormat::viewport

(

)

const

Returns the viewport of a video stream.

The viewport is the region of a video frame that is actually displayed.

By default the viewport covers an entire frame.

Definition at line 376 of file qvideosurfaceformat.cpp.

Referenced by operator<<(), and setViewport().

{
    return d->viewport;
}

yCbCrColorSpace()

QVideoSurfaceFormat::YCbCrColorSpace QVideoSurfaceFormat::yCbCrColorSpace

(

)

const

Returns the Y'CbCr color space of a video stream.

Definition at line 462 of file qvideosurfaceformat.cpp.

{
    return d->ycbcrColorSpace;
}

Properties

d

QSharedDataPointer<QVideoSurfaceFormatPrivate> QVideoSurfaceFormat::d

private

Definition at line 132 of file qvideosurfaceformat.h.

Referenced by frameHeight(), frameRate(), frameSize(), frameWidth(), handleType(), isValid(), operator!=(), operator=(), operator==(), pixelAspectRatio(), pixelFormat(), property(), propertyNames(), scanLineDirection(), setFrameRate(), setFrameSize(), setPixelAspectRatio(), setProperty(), setScanLineDirection(), setViewport(), setYCbCrColorSpace(), sizeHint(), viewport(), and yCbCrColorSpace().

---

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

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