QVideoSurfaceFormat Class

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

Header:	#include <QVideoSurfaceFormat>
qmake:	QT += multimedia

• List of all members, including inherited members

Public Types

enum	Direction { TopToBottom, BottomToTop }
enum	YCbCrColorSpace { YCbCr_Undefined, YCbCr_BT601, YCbCr_BT709, YCbCr_xvYCC601, YCbCr_xvYCC709, YCbCr_JPEG }

Public Functions

	QVideoSurfaceFormat()
	QVideoSurfaceFormat(const QSize &size, QVideoFrame::PixelFormat format, QAbstractVideoBuffer::HandleType type = QAbstractVideoBuffer::NoHandle)
	QVideoSurfaceFormat(const QVideoSurfaceFormat &other)
	~QVideoSurfaceFormat()
int	frameHeight() const
qreal	frameRate() const
QSize	frameSize() const
int	frameWidth() const
QAbstractVideoBuffer::HandleType	handleType() const
bool	isMirrored() const
bool	isValid() const
QSize	pixelAspectRatio() const
QVideoFrame::PixelFormat	pixelFormat() const
QVariant	property(const char *name) const
QList<QByteArray>	propertyNames() const
QVideoSurfaceFormat::Direction	scanLineDirection() const
void	setFrameRate(qreal rate)
void	setFrameSize(const QSize &size)
void	setFrameSize(int width, int height)
void	setMirrored(bool mirrored)
void	setPixelAspectRatio(const QSize &ratio)
void	setPixelAspectRatio(int horizontal, int vertical)
void	setProperty(const char *name, const QVariant &value)
void	setScanLineDirection(QVideoSurfaceFormat::Direction direction)
void	setViewport(const QRect &viewport)
void	setYCbCrColorSpace(QVideoSurfaceFormat::YCbCrColorSpace space)
QSize	sizeHint() const
QRect	viewport() const
QVideoSurfaceFormat::YCbCrColorSpace	yCbCrColorSpace() const
bool	operator!=(const QVideoSurfaceFormat &other) const
QVideoSurfaceFormat &	operator=(const QVideoSurfaceFormat &other)
bool	operator==(const QVideoSurfaceFormat &other) const

Detailed Description

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

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.

Member Type Documentation

enum QVideoSurfaceFormat::Direction

Enumerates the layout direction of video scan lines.

Constant	Value	Description
QVideoSurfaceFormat::TopToBottom	0	Scan lines are arranged from the top of the frame to the bottom.
QVideoSurfaceFormat::BottomToTop	1	Scan lines are arranged from the bottom of the frame to the top.

enum QVideoSurfaceFormat::YCbCrColorSpace

Enumerates the Y'CbCr color space of video frames.

Constant	Value	Description
QVideoSurfaceFormat::YCbCr_Undefined	0	No color space is specified.
QVideoSurfaceFormat::YCbCr_BT601	1	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.
QVideoSurfaceFormat::YCbCr_BT709	2	A Y'CbCr color space defined by ITU-R BT.709 with the same values range as YCbCr_BT601. Used for HDTV.
QVideoSurfaceFormat::YCbCr_xvYCC601	3	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 a wider range of colors.
QVideoSurfaceFormat::YCbCr_xvYCC709	4	The BT.709 color space with the value range extended to 0 to 255.
QVideoSurfaceFormat::YCbCr_JPEG	5	The full range Y'CbCr color space used in JPEG files.

Member Function Documentation

QVideoSurfaceFormat::QVideoSurfaceFormat()

Constructs a null video stream format.

QVideoSurfaceFormat::QVideoSurfaceFormat(const QSize &size, QVideoFrame::PixelFormat format, QAbstractVideoBuffer::HandleType type = QAbstractVideoBuffer::NoHandle)

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

QVideoSurfaceFormat::QVideoSurfaceFormat(const QVideoSurfaceFormat &other)

Constructs a copy of other.

QVideoSurfaceFormat::~QVideoSurfaceFormat()

Destroys a video stream description.

int QVideoSurfaceFormat::frameHeight() const

Returns the height of frame in a video stream.

qreal QVideoSurfaceFormat::frameRate() const

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

See also setFrameRate().

QSize QVideoSurfaceFormat::frameSize() const

Returns the dimensions of frames in a video stream.

See also setFrameSize(), frameWidth(), and frameHeight().

int QVideoSurfaceFormat::frameWidth() const

Returns the width of frames in a video stream.

See also frameSize() and frameHeight().

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 mapped with the QAbstractVideoBuffer::ReadOnly flag. If the handleType() is not QAbstractVideoBuffer::NoHandle then the handle type of the buffer must be the same as that of the surface format.

bool QVideoSurfaceFormat::isMirrored() const

Returns true if the surface is mirrored around its vertical axis. This is typically needed for video frames coming from a front camera of a mobile device.

Note: The mirroring here differs from QImage::mirrored, as a vertically mirrored QImage will be mirrored around its x-axis.

This function was introduced in Qt 5.11.

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.

QSize QVideoSurfaceFormat::pixelAspectRatio() const

Returns a video stream's pixel aspect ratio.

See also setPixelAspectRatio().

QVideoFrame::PixelFormat QVideoSurfaceFormat::pixelFormat() const

Returns the pixel format of frames in a video stream.

QVariant QVideoSurfaceFormat::property(const char *name) const

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

See also setProperty().

QList<QByteArray> QVideoSurfaceFormat::propertyNames() const

Returns a list of video format dynamic property names.

QVideoSurfaceFormat::Direction QVideoSurfaceFormat::scanLineDirection() const

Returns the direction of scan lines.

See also setScanLineDirection().

void QVideoSurfaceFormat::setFrameRate(qreal rate)

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

See also frameRate().

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.

See also frameSize().

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

This is an overloaded function.

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

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

void QVideoSurfaceFormat::setMirrored(bool mirrored)

Sets if the surface is mirrored around its vertical axis. This is typically needed for video frames coming from a front camera of a mobile device. Default value is false.

Note: The mirroring here differs from QImage::mirrored, as a vertically mirrored QImage will be mirrored around its x-axis.

This function was introduced in Qt 5.11.

See also isMirrored().

void QVideoSurfaceFormat::setPixelAspectRatio(const QSize &ratio)

Sets a video stream's pixel aspect ratio.

See also pixelAspectRatio().

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

This is an overloaded function.

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

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

Sets the video format's name property to value.

Trying to set a read only property will be ignored.

See also property().

void QVideoSurfaceFormat::setScanLineDirection(QVideoSurfaceFormat::Direction direction)

Sets the direction of scan lines.

See also scanLineDirection().

void QVideoSurfaceFormat::setViewport(const QRect &viewport)

Sets the viewport of a video stream to viewport.

See also viewport().

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.

See also yCbCrColorSpace().

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.

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.

See also setViewport().

QVideoSurfaceFormat::YCbCrColorSpace QVideoSurfaceFormat::yCbCrColorSpace() const

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

See also setYCbCrColorSpace().

bool QVideoSurfaceFormat::operator!=(const QVideoSurfaceFormat &other) const

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

QVideoSurfaceFormat &QVideoSurfaceFormat::operator=(const QVideoSurfaceFormat &other)

Assigns the values of other to this object.

bool QVideoSurfaceFormat::operator==(const QVideoSurfaceFormat &other) const

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