Qt Reference Documentation

# QVideoSurfaceFormat Class Reference

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

     #include <QVideoSurfaceFormat>

This class was introduced in Qt 4.6.

- 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 | isValid () const
QSize | pixelAspectRatio () const
QVideoFrame::PixelFormat | pixelFormat () const
QVariant | property ( const char * name ) const
QList<QByteArray> | propertyNames () const
Direction | scanLineDirection () const
void | setFrameRate ( qreal rate )
void | setFrameSize ( const QSize & size )
void | setFrameSize ( int width, int height )
void | setPixelAspectRatio ( const QSize & ratio )
void | setPixelAspectRatio ( int horizontal, int vertical )
void | setProperty ( const char * name, const QVariant & value )
void | setScanLineDirection ( Direction direction )
void | setViewport ( const QRect & viewport )
void | setYCbCrColorSpace ( YCbCrColorSpace space )
QSize | sizeHint () const
QRect | viewport () const
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 wider colors range.
`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 size 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 be the same as that of the surface format.

### 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.

### 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::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.

See also property().

### void QVideoSurfaceFormat::setScanLineDirection ( 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 ( 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().

### 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 a video format, and false if they are the same.

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

Assigns the values of other to a video stream description.

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

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