- Qt 6.12
- Qt Multimedia
- C++ Classes
- QtMultimedia
- QVideoFrameFormat
- Qt 6.12.0 Reference Documentation

# QVideoFrameFormat Class

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

Header: | `#include <QVideoFrameFormat>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Multimedia)` `target_link_libraries(mytarget PRIVATE Qt6::Multimedia)`
qmake: | `QT += multimedia`

- List of all members, including inherited members
- Deprecated members

## Public Types

enum | ColorRange { ColorRange_Unknown, ColorRange_Video, ColorRange_Full }
enum | ColorSpace { ColorSpace_Undefined, ColorSpace_BT601, ColorSpace_BT709, ColorSpace_AdobeRgb, ColorSpace_BT2020 }
enum | ColorTransfer { ColorTransfer_Unknown, ColorTransfer_BT709, ColorTransfer_BT601, ColorTransfer_Linear, ColorTransfer_Gamma22, …, ColorTransfer_STD_B67 }
enum | Direction { TopToBottom, BottomToTop }
enum | PixelFormat { Format_Invalid, Format_ARGB8888, Format_ARGB8888_Premultiplied, Format_XRGB8888, Format_BGRA8888, …, Format_YUV420P10 }

## Public Functions

| QVideoFrameFormat()
| QVideoFrameFormat(const QSize &size, QVideoFrameFormat::PixelFormat format)
| QVideoFrameFormat(const QVideoFrameFormat &other)
| QVideoFrameFormat(QVideoFrameFormat &&other)
| ~QVideoFrameFormat()
QVideoFrameFormat::ColorRange | colorRange() const
QVideoFrameFormat::ColorSpace | colorSpace() const
QVideoFrameFormat::ColorTransfer | colorTransfer() const
int | frameHeight() const
qreal | frameRate() const
QSize | frameSize() const
int | frameWidth() const
bool | isMirrored() const
bool | isValid() const
QVideoFrameFormat::PixelFormat | pixelFormat() const
int | planeCount() const
QtVideo::Rotation | rotation() const
QVideoFrameFormat::Direction | scanLineDirection() const
void | setColorRange(QVideoFrameFormat::ColorRange range)
void | setColorSpace(QVideoFrameFormat::ColorSpace colorSpace)
void | setColorTransfer(QVideoFrameFormat::ColorTransfer colorTransfer)
void | setFrameRate(qreal rate)
void | setFrameSize(const QSize &size)
void | setFrameSize(int width, int height)
void | setMaxLuminance(float lum)
void | setMirrored(bool mirrored)
void | setRotation(QtVideo::Rotation angle)
void | setScanLineDirection(QVideoFrameFormat::Direction direction)
void | setStreamFrameRate(qreal rate)
void | setViewport(const QRect &viewport)
qreal | streamFrameRate() const
void | swap(QVideoFrameFormat &other)
QRect | viewport() const
bool | operator!=(const QVideoFrameFormat &other) const
QVideoFrameFormat & | operator=(QVideoFrameFormat &&other)
QVideoFrameFormat & | operator=(const QVideoFrameFormat &other)
bool | operator==(const QVideoFrameFormat &other) const

## Static Public Members

QImage::Format | imageFormatFromPixelFormat(QVideoFrameFormat::PixelFormat format)
QVideoFrameFormat::PixelFormat | pixelFormatFromImageFormat(QImage::Format format)
QString | pixelFormatToString(QVideoFrameFormat::PixelFormat pixelFormat)

## Detailed Description

A video sink presents a stream of video frames. QVideoFrameFormat describes the type of the frames and determines how they should be presented.

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

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 scanLineDirection(), frameRate() and the yCrCbColorSpace().

## Member Type Documentation

### enum QVideoFrameFormat::ColorRange

Describes the color range used by the video data. Video data usually comes in either full color range, where all values are being used, or a more limited range traditionally used in YUV video formats, where a subset of all values is being used.

Constant | Value | Description
--- | --- | ---
`QVideoFrameFormat::ColorRange_Unknown` | `0` | The color range of the video is unknown.
`QVideoFrameFormat::ColorRange_Video` | `1` |

The color range traditionally used by most YUV video formats. For 8 bit formats, the Y component is limited to values between 16 and 235. The U and V components are limited to values between 16 and 240

For higher bit depths multiply these values with 2^(depth-8).

Constant | Value
--- | ---
`QVideoFrameFormat::ColorRange_Full` | `2`

Full color range. All values from 0 to 2^depth - 1 are valid.

### enum QVideoFrameFormat::ColorSpace

Enumerates the color space of video frames.

Constant | Value | Description
--- | --- | ---
`QVideoFrameFormat::ColorSpace_Undefined` | `0` | No color space is specified.
`QVideoFrameFormat::ColorSpace_BT601` | `1` | A 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 mostly by older videos that were targeting CRT displays.
`QVideoFrameFormat::ColorSpace_BT709` | `2` | A color space defined by ITU-R BT.709 with the same values range as ColorSpace_BT601. The most commonly used color space today.
`QVideoFrameFormat::ColorSpace_AdobeRgb` | `5` | The full range YUV color space used in most JPEG files.
`QVideoFrameFormat::ColorSpace_BT2020` | `6` | The color space defined by ITU-R BT.2020. Used mainly for HDR videos.

### enum QVideoFrameFormat::ColorTransfer

Constant | Value | Description
--- | --- | ---
`QVideoFrameFormat::ColorTransfer_Unknown` | `0` | The color transfer function is unknown.
`QVideoFrameFormat::ColorTransfer_BT709` | `1` | Color values are encoded according to BT709. See also https://www.itu.int/rec/R-REC-BT.709/en. This is close to, but not identical to a gamma curve of 2.2, and the same transfer curve as is used in sRGB.
`QVideoFrameFormat::ColorTransfer_BT601` | `2` | Color values are encoded according to BT601. See also https://www.itu.int/rec/R-REC-BT.601/en.
`QVideoFrameFormat::ColorTransfer_Linear` | `3` | Color values are linear
`QVideoFrameFormat::ColorTransfer_Gamma22` | `4` | Color values are encoded with a gamma of 2.2
`QVideoFrameFormat::ColorTransfer_Gamma28` | `5` | Color values are encoded with a gamma of 2.8
`QVideoFrameFormat::ColorTransfer_ST2084` | `6` | Color values are encoded using STME ST 2084. This transfer function is the most common HDR transfer function and often called the 'perceptual quantizer'. See also https://www.itu.int/rec/R-REC-BT.2100 and https://en.wikipedia.org/wiki/Perceptual_quantizer.
`QVideoFrameFormat::ColorTransfer_STD_B67` | `7` | Color values are encoded using ARIB STD B67. This transfer function is also often referred to as 'hybrid log gamma'. See also https://www.itu.int/rec/R-REC-BT.2100 and https://en.wikipedia.org/wiki/Hybrid_log–gamma.

### enum QVideoFrameFormat::Direction

Enumerates the layout direction of video scan lines.

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

### enum QVideoFrameFormat::PixelFormat

Enumerates video data types.

Constant | Value | Description
--- | --- | ---
`QVideoFrameFormat::Format_Invalid` | `0` | The frame is invalid.
`QVideoFrameFormat::Format_ARGB8888` | `1` | The frame is stored using a ARGB format with 8 bits per component.
`QVideoFrameFormat::Format_ARGB8888_Premultiplied` | `2` | The frame stored using a premultiplied ARGB format with 8 bits per component.
`QVideoFrameFormat::Format_XRGB8888` | `3` | The frame stored using a 32 bits per pixel RGB format (0xff, R, G, B).
`QVideoFrameFormat::Format_BGRA8888` | `4` | The frame is stored using a 32-bit BGRA format (0xBBGGRRAA).
`QVideoFrameFormat::Format_BGRA8888_Premultiplied` | `5` | The frame is stored using a premultiplied 32bit BGRA format.
`QVideoFrameFormat::Format_ABGR8888` | `7` | The frame is stored using a 32-bit ABGR format (0xAABBGGRR).
`QVideoFrameFormat::Format_XBGR8888` | `8` | The frame is stored using a 32-bit BGR format (0xffBBGGRR).
`QVideoFrameFormat::Format_RGBA8888` | `9` | The frame is stored in memory as the bytes R, G, B, A/X, with R at the lowest address and A/X at the highest address.
`QVideoFrameFormat::Format_BGRX8888` | `6` | The frame is stored in format 32-bit BGRx format, [31:0] B:G:R:x 8:8:8:8 little endian
`QVideoFrameFormat::Format_RGBX8888` | `10` | The frame is stored in memory as the bytes R, G, B, A/X, with R at the lowest address and A/X at the highest address.
`QVideoFrameFormat::Format_AYUV` | `11` | The frame is stored using a packed 32-bit AYUV format (0xAAYYUUVV).
`QVideoFrameFormat::Format_AYUV_Premultiplied` | `12` | The frame is stored using a packed premultiplied 32-bit AYUV format (0xAAYYUUVV).
`QVideoFrameFormat::Format_YUV420P` | `13` | The frame is stored using an 8-bit per component planar YUV format with the U and V planes horizontally and vertically sub-sampled, i.e. the height and width of the U and V planes are half that of the Y plane.
`QVideoFrameFormat::Format_YUV422P` | `14` | The frame is stored using an 8-bit per component planar YUV format with the U and V planes horizontally sub-sampled, i.e. the width of the U and V planes are half that of the Y plane, and height of U and V planes is the same as Y.
`QVideoFrameFormat::Format_YV12` | `15` | The frame is stored using an 8-bit per component planar YVU format with the V and U planes horizontally and vertically sub-sampled, i.e. the height and width of the V and U planes are half that of the Y plane.
`QVideoFrameFormat::Format_UYVY` | `16` | The frame is stored using an 8-bit per component packed YUV format with the U and V planes horizontally sub-sampled (U-Y-V-Y), i.e. two horizontally adjacent pixels are stored as a 32-bit macropixel which has a Y value for each pixel and common U and V values.
`QVideoFrameFormat::Format_YUYV` | `17` | The frame is stored using an 8-bit per component packed YUV format with the U and V planes horizontally sub-sampled (Y-U-Y-V), i.e. two horizontally adjacent pixels are stored as a 32-bit macropixel which has a Y value for each pixel and common U and V values.
`QVideoFrameFormat::Format_NV12` | `18` | The frame is stored using an 8-bit per component semi-planar YUV format with a Y plane (Y) followed by a horizontally and vertically sub-sampled, packed UV plane (U-V).
`QVideoFrameFormat::Format_NV21` | `19` | The frame is stored using an 8-bit per component semi-planar YUV format with a Y plane (Y) followed by a horizontally and vertically sub-sampled, packed VU plane (V-U).
`QVideoFrameFormat::Format_IMC1` | `20` | The frame is stored using an 8-bit per component planar YUV format with the U and V planes horizontally and vertically sub-sampled. This is similar to the Format_YUV420P type, except that the bytes per line of the U and V planes are padded out to the same stride as the Y plane.
`QVideoFrameFormat::Format_IMC2` | `21` | The frame is stored using an 8-bit per component planar YUV format with the U and V planes horizontally and vertically sub-sampled. This is similar to the Format_YUV420P type, except that the lines of the U and V planes are interleaved, i.e. each line of U data is followed by a line of V data creating a single line of the same stride as the Y data.
`QVideoFrameFormat::Format_IMC3` | `22` | The frame is stored using an 8-bit per component planar YVU format with the V and U planes horizontally and vertically sub-sampled. This is similar to the Format_YV12 type, except that the bytes per line of the V and U planes are padded out to the same stride as the Y plane.
`QVideoFrameFormat::Format_IMC4` | `23` | The frame is stored using an 8-bit per component planar YVU format with the V and U planes horizontally and vertically sub-sampled. This is similar to the Format_YV12 type, except that the lines of the V and U planes are interleaved, i.e. each line of V data is followed by a line of U data creating a single line of the same stride as the Y data.
`QVideoFrameFormat::Format_P010` | `26` | The frame is stored using a 16bit per component semi-planar YUV format with a Y plane (Y) followed by a horizontally and vertically sub-sampled, packed UV plane (U-V). Only the 10 most significant bits of each component are being used.
`QVideoFrameFormat::Format_P016` | `27` | The frame is stored using a 16bit per component semi-planar YUV format with a Y plane (Y) followed by a horizontally and vertically sub-sampled, packed UV plane (U-V).
`QVideoFrameFormat::Format_Y8` | `24` | The frame is stored using an 8-bit greyscale format.
`QVideoFrameFormat::Format_Y16` | `25` | The frame is stored using a 16-bit linear greyscale format. Little endian.
`QVideoFrameFormat::Format_Jpeg` | `29` | The frame is stored in compressed Jpeg format.
`QVideoFrameFormat::Format_SamplerExternalOES` | `28` | The frame is stored in external OES texture format. This is currently only being used on Android.
`QVideoFrameFormat::Format_SamplerRect` | `30` | The frame is stored in rectangle texture format (GL_TEXTURE_RECTANGLE). This is only being used on macOS with an OpenGL based Rendering Hardware interface. The underlying pixel format stored in the texture is Format_BRGA8888.
`QVideoFrameFormat::Format_YUV420P10` | `31` | Similar to YUV420, but uses 16bits per component, 10 of those significant.

## Member Function Documentation

### QVideoFrameFormat::QVideoFrameFormat()

Constructs a null video stream format.

### QVideoFrameFormat::QVideoFrameFormat(const QSize &size, QVideoFrameFormat::PixelFormat format)

Constructs a video stream with the given frame size and pixel format.

### QVideoFrameFormat::QVideoFrameFormat(const QVideoFrameFormat &other)

Constructs a copy of other.

### `[constexpr noexcept default]` QVideoFrameFormat::QVideoFrameFormat(QVideoFrameFormat &&other)

Constructs a QVideoFrameFormat by moving from other.

### `[noexcept]` QVideoFrameFormat::~QVideoFrameFormat()

Destroys a video stream description.

### QVideoFrameFormat::ColorRange QVideoFrameFormat::colorRange() const

Returns the color range that should be used to render the video stream.

See also setColorRange().

### QVideoFrameFormat::ColorSpace QVideoFrameFormat::colorSpace() const

Returns the color space of a video stream.

See also setColorSpace().

### QVideoFrameFormat::ColorTransfer QVideoFrameFormat::colorTransfer() const

Returns the color transfer function that should be used to render the video stream.

See also setColorTransfer().

### int QVideoFrameFormat::frameHeight() const

Returns the height of frame in a video stream.

### qreal QVideoFrameFormat::frameRate() const

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

See also setFrameRate().

### QSize QVideoFrameFormat::frameSize() const

Returns the dimensions of frames in a video stream.

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

### int QVideoFrameFormat::frameWidth() const

Returns the width of frames in a video stream.

See also frameSize() and frameHeight().

### `[static]` QImage::Format QVideoFrameFormat::imageFormatFromPixelFormat(QVideoFrameFormat::PixelFormat format)

Returns an image format equivalent to a video frame pixel format. If there is no equivalent format QImage::Format_Invalid is returned instead.

Note: In general QImage does not handle YUV formats.

### bool QVideoFrameFormat::isMirrored() const

Returns `true` if the surface is mirrored around its vertical axis.

Transformations of `QVideoFrameFormat`, specifically, rotation and mirroring, can be determined by the orientation of the camera sensor, camera settings, or the orientation of the video stream.

Mirroring is applied after rotation.

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

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

### QVideoFrameFormat::PixelFormat QVideoFrameFormat::pixelFormat() const

Returns the pixel format of frames in a video stream.

### `[static]` QVideoFrameFormat::PixelFormat QVideoFrameFormat::pixelFormatFromImageFormat(QImage::Format format)

Returns a video pixel format equivalent to an image format. If there is no equivalent format QVideoFrameFormat::Format_Invalid is returned instead.

Note: In general QImage does not handle YUV formats.

### `[static]` QString QVideoFrameFormat::pixelFormatToString(QVideoFrameFormat::PixelFormat pixelFormat)

Returns a string representation of the given pixelFormat.

### int QVideoFrameFormat::planeCount() const

Returns the number of planes used. This number is depending on the pixel format and is 1 for RGB based formats, and a number between 1 and 3 for YUV based formats.

### QtVideo::Rotation QVideoFrameFormat::rotation() const

Returns the angle by which the surface is rotated clockwise.

Transformations of `QVideoFrameFormat`, specifically, rotation and mirroring, can be determined by the orientation of the camera sensor, camera settings, or the orientation of the video stream.

Rotation is applied before mirroring.

See also setRotation().

### QVideoFrameFormat::Direction QVideoFrameFormat::scanLineDirection() const

Returns the direction of scan lines.

See also setScanLineDirection().

### void QVideoFrameFormat::setColorRange(QVideoFrameFormat::ColorRange range)

Sets the color transfer range that should be used to render the video stream to range.

See also colorRange().

### void QVideoFrameFormat::setColorSpace(QVideoFrameFormat::ColorSpace colorSpace)

Sets the colorSpace of a video stream.

See also colorSpace().

### void QVideoFrameFormat::setColorTransfer(QVideoFrameFormat::ColorTransfer colorTransfer)

Sets the color transfer function that should be used to render the video stream to colorTransfer.

See also colorTransfer().

### void QVideoFrameFormat::setFrameRate(qreal rate)

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

See also frameRate().

### void QVideoFrameFormat::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 QVideoFrameFormat::setFrameSize(int width, int height)

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

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

This is an overloaded function.

### void QVideoFrameFormat::setMaxLuminance(float lum)

Sets the maximum luminance to the given value, lum.

### void QVideoFrameFormat::setMirrored(bool mirrored)

Sets if the surface is mirrored around its vertical axis.

Transformations of `QVideoFrameFormat`, specifically, rotation and mirroring, can be determined by the orientation of the camera sensor, camera settings, or the orientation of the video stream.

Mirroring is applied after rotation.

Default value is `false`.

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

See also isMirrored().

### void QVideoFrameFormat::setRotation(QtVideo::Rotation angle)

Sets the angle by which the surface is rotated clockwise.

Transformations of `QVideoFrameFormat`, specifically, rotation and mirroring, can be determined by the orientation of the camera sensor, camera settings, or the orientation of the video stream.

Rotation is applied before mirroring.

Default value is `QtVideo::Rotation::None`.

See also rotation().

### void QVideoFrameFormat::setScanLineDirection(QVideoFrameFormat::Direction direction)

Sets the direction of scan lines.

See also scanLineDirection().

### void QVideoFrameFormat::setStreamFrameRate(qreal rate)

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

See also streamFrameRate().

### void QVideoFrameFormat::setViewport(const QRect &viewport)

Sets the viewport of a video stream to viewport.

See also viewport().

### qreal QVideoFrameFormat::streamFrameRate() const

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

See also setStreamFrameRate().

### `[noexcept]` void QVideoFrameFormat::swap(QVideoFrameFormat &other)

Swaps the current video frame format with the other.

### QRect QVideoFrameFormat::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().

### bool QVideoFrameFormat::operator!=(const QVideoFrameFormat &other) const

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

### `[noexcept]` QVideoFrameFormat &QVideoFrameFormat::operator=(QVideoFrameFormat &&other)

Moves other into this QVideoFrameFormat.

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

Assigns the values of other to this object.

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

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