QVideoFrameFormat Class
QVideoFrameFormat 类指定了视频演示界面的流格式。更多
| Header： | #include <QVideoFrameFormat> |
| CMake： | find_package(Qt6 REQUIRED COMPONENTS Multimedia)target_link_libraries(mytarget PRIVATE Qt6::Multimedia) |
| qmake： | QT += multimedia |
公共类型
| 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 } |
公共函数
| 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 |
静态公共成员
| QImage::Format | imageFormatFromPixelFormat(QVideoFrameFormat::PixelFormat format) |
| QVideoFrameFormat::PixelFormat | pixelFormatFromImageFormat(QImage::Format format) |
| QString | pixelFormatToString(QVideoFrameFormat::PixelFormat pixelFormat) |
详细说明
视频汇呈现的是视频帧流。QVideoFrameFormat 描述了帧的类型，并决定了帧的呈现方式。
设置视频汇所需的视频流核心属性是pixelFormat() 中给出的像素格式和frameSize() 中给出的帧尺寸。
视频表面实际显示的帧区域由viewport() 给出。视频流的视口可能小于帧的整个区域，以便播放小于视频帧最佳尺寸的视频。例如，可以扩展帧的宽度，使每条扫描线的起点都是 8 字节对齐。
其他常用属性包括scanLineDirection(),frameRate() 和 yCrCbColorSpace()。
成员类型文档
enum QVideoFrameFormat::ColorRange
描述视频数据使用的色彩范围。视频数据通常有两种颜色范围，一种是全色范围，即使用所有数值；另一种是传统 YUV 视频格式中使用的更有限的范围，即使用所有数值的子集。
| 常量 | 值 | 说明 |
|---|---|---|
QVideoFrameFormat::ColorRange_Unknown | 0 | 视频的色彩范围未知。 |
QVideoFrameFormat::ColorRange_Video | 1 |
大多数 YUV 视频格式传统上使用的色彩范围。对于 8 位格式，Y 分量仅限于 16 至 235 之间的值。U 分量和 V 分量仅限于 16 至 240 之间的值。
对于更高的比特深度，这些值乘以 2^（深度-8）。
| 常数 | 值 |
|---|---|
QVideoFrameFormat::ColorRange_Full | 2 |
全色彩范围。从 0 到 2^depth - 1 的所有值均有效。
enum QVideoFrameFormat::ColorSpace
枚举视频帧的色彩空间。
| 常数 | 值 | 说明 |
|---|---|---|
QVideoFrameFormat::ColorSpace_Undefined | 0 | 未指定色彩空间。 |
QVideoFrameFormat::ColorSpace_BT601 | 1 | 由 ITU-R 建议 BT.601 定义的色彩空间，Y 值范围为 16 至 235，Cb/Cr 值范围为 16 至 240。主要用于针对 CRT 显示器的旧版视频。 |
QVideoFrameFormat::ColorSpace_BT709 | 2 | 由 ITU-R BT.709 定义的色彩空间，其数值范围与 ColorSpace_BT601 相同。目前最常用的色彩空间。 |
QVideoFrameFormat::ColorSpace_AdobeRgb | 5 | 大多数 JPEG 文件中使用的全范围 YUV 色彩空间。 |
QVideoFrameFormat::ColorSpace_BT2020 | 6 | ITU-R BT.2020 定义的色彩空间。主要用于 HDR 视频。 |
enum QVideoFrameFormat::ColorTransfer
| 常数 | 值 | 说明 |
|---|---|---|
QVideoFrameFormat::ColorTransfer_Unknown | 0 | 色彩传递函数未知。 |
QVideoFrameFormat::ColorTransfer_BT709 | 1 | 颜色值根据 BT709 编码。另请参阅 https://www.itu.int/rec/R-REC-BT.709/en。这接近但不等同于伽玛曲线 2.2，与 sRGB 中使用的转移曲线相同。 |
QVideoFrameFormat::ColorTransfer_BT601 | 2 | 色值根据 BT601 编码。另请参见 https://www.itu.int/rec/R-REC-BT.601/en。 |
QVideoFrameFormat::ColorTransfer_Linear | 3 | 色彩值是线性的 |
QVideoFrameFormat::ColorTransfer_Gamma22 | 4 | 色彩值按 2.2 的伽玛曲线编码 |
QVideoFrameFormat::ColorTransfer_Gamma28 | 5 | 色彩值的伽玛值为 2.8 |
QVideoFrameFormat::ColorTransfer_ST2084 | 6 | 色彩值使用 STME ST 2084 编码。这种传递函数是最常见的 HDR 传递函数，通常被称为 "感知量化器"。另请参阅 https://www.itu.int/rec/R-REC-BT.2100 和 https://en.wikipedia.org/wiki/Perceptual_quantizer。 |
QVideoFrameFormat::ColorTransfer_STD_B67 | 7 | 色彩值使用 ARIB STD B67 编码。这种传递函数也常被称为 "混合对数伽玛"。另请参阅 https://www.itu.int/rec/R-REC-BT.2100 和 https://en.wikipedia.org/wiki/Hybrid_log-gamma。 |
enum QVideoFrameFormat::Direction
枚举视频扫描线的布局方向。
| 常数 | 值 | 说明 |
|---|---|---|
QVideoFrameFormat::TopToBottom | 0 | 扫描线从帧的顶部向底部排列。 |
QVideoFrameFormat::BottomToTop | 1 | 扫描线从画面底部向顶部排列。 |
enum QVideoFrameFormat::PixelFormat
枚举视频数据类型。
| 常数 | 值 | 说明 |
|---|---|---|
QVideoFrameFormat::Format_Invalid | 0 | 帧无效。 |
QVideoFrameFormat::Format_ARGB8888 | 1 | 帧使用 ARGB 格式存储，每个分量 8 位。 |
QVideoFrameFormat::Format_ARGB8888_Premultiplied | 2 | 帧使用预乘法 ARGB 格式存储，每个分量 8 位。 |
QVideoFrameFormat::Format_XRGB8888 | 3 | 帧使用每像素 32 位的 RGB 格式（0xff、R、G、B）存储。 |
QVideoFrameFormat::Format_BGRA8888 | 4 | 使用 32 位 BGRA 格式（0xBBGGRRAA）存储的图像。 |
QVideoFrameFormat::Format_BGRA8888_Premultiplied | 5 | 帧使用预乘法 32 位 BGRA 格式存储。 |
QVideoFrameFormat::Format_ABGR8888 | 7 | 帧使用 32 位 ABGR 格式 (0xAABBGGRR) 存储。 |
QVideoFrameFormat::Format_XBGR8888 | 8 | 帧使用 32 位 BGR 格式 (0xffBBGGRR) 存储。 |
QVideoFrameFormat::Format_RGBA8888 | 9 | 帧以 R、G、B、A/X 字节形式存储在内存中，其中 R 位于最低地址，A/X 位于最高地址。 |
QVideoFrameFormat::Format_BGRX8888 | 6 | 帧以 32 位 BGRx 格式存储，[31:0] B:G:R:x 8:8:8:8 little endian。 |
QVideoFrameFormat::Format_RGBX8888 | 10 | 帧以 R、G、B、A/X 的字节形式存储在内存中，R 位于最低地址，A/X 位于最高地址。 |
QVideoFrameFormat::Format_AYUV | 11 | 帧使用打包的 32 位 AYUV 格式（0xAAYYUUVV）存储。 |
QVideoFrameFormat::Format_AYUV_Premultiplied | 12 | 帧使用打包预乘法 32 位 AYUV 格式（0xAAYYUUVV）存储。 |
QVideoFrameFormat::Format_YUV420P | 13 | 帧使用每分量 8 位的平面 YUV 格式存储，其中 U 平面和 V 平面在水平和垂直方向上都经过子采样，即 U 平面和 V 平面的高度和宽度是 Y 平面的一半。 |
QVideoFrameFormat::Format_YUV422P | 14 | 使用每分量 8 位的平面 YUV 格式存储图像，对 U 平面和 V 平面进行水平子采样，即 U 平面和 V 平面的宽度为 Y 平面的一半，U 平面和 V 平面的高度与 Y 平面相同。 |
QVideoFrameFormat::Format_YV12 | 15 | 帧使用每个分量 8 位的平面 YVU 格式存储，其中 V 平面和 U 平面在水平和垂直方向上进行了子采样，即 V 平面和 U 平面的高度和宽度均为 Y 平面的一半。 |
QVideoFrameFormat::Format_UYVY | 16 | 帧使用每分量 8 位的打包 YUV 格式存储，U 平面和 V 平面水平分采样（U-Y-V-Y），即两个水平相邻的像素作为一个 32 位的宏像素存储，每个像素有一个 Y 值，U 平面和 V 平面有共同的 U 值和 V 值。 |
QVideoFrameFormat::Format_YUYV | 17 | 帧使用每分量 8 位的打包 YUV 格式存储，U 平面和 V 平面水平分采样（Y-U-Y-V），即两个水平相邻的像素作为一个 32 位宏像素存储，每个像素有一个 Y 值，U 平面和 V 平面有共同的 U 值和 V 值。 |
QVideoFrameFormat::Format_NV12 | 18 | 帧使用每个分量 8 位的半平面 YUV 格式存储，Y 平面（Y）之后是水平和垂直分采样、打包的 UV 平面（U-V）。 |
QVideoFrameFormat::Format_NV21 | 19 | 帧的存储采用每分量 8 位的半平面 YUV 格式，Y 平面（Y）后跟一个水平和垂直分采样的打包 VU 平面（V-U）。 |
QVideoFrameFormat::Format_IMC1 | 20 | 帧使用每分量 8 位的平面 YUV 格式存储，U 平面和 V 平面在水平和垂直方向上都经过子采样。这与 Format_YUV420P 类型相似，但 U 平面和 V 平面的每行字节数填充为与 Y 平面相同的步长。 |
QVideoFrameFormat::Format_IMC2 | 21 | 帧使用每分量 8 位的平面 YUV 格式存储，U 平面和 V 平面在水平和垂直方向上进行子采样。这与 Format_YUV420P 类型相似，但 U 平面和 V 平面的行数是交错的，即每行 U 数据后紧跟一行 V 数据，形成与 Y 数据相同步长的单行。 |
QVideoFrameFormat::Format_IMC3 | 22 | 帧使用每分量 8 位的平面 YVU 格式存储，其中 V 平面和 U 平面在水平和垂直方向上进行了子采样。这与 Format_YV12 类型类似，只是 V 平面和 U 平面的每行字节数填充为与 Y 平面相同的步长。 |
QVideoFrameFormat::Format_IMC4 | 23 | 帧使用每分量 8 位的平面 YVU 格式存储，其中 V 平面和 U 平面在水平和垂直方向上进行了子采样。这与 Format_YV12 类型相似，但 V 平面和 U 平面的行数是交错的，即每行 V 数据后紧跟一行 U 数据，形成与 Y 数据相同步长的单行。 |
QVideoFrameFormat::Format_P010 | 26 | 帧的存储采用每个分量 16 位的半平面 YUV 格式，Y 平面（Y）之后是水平和垂直的子采样、打包的 UV 平面（U-V）。每个分量只使用 10 个最有效位。 |
QVideoFrameFormat::Format_P016 | 27 | 帧使用每个分量 16 位的半平面 YUV 格式存储，Y 平面 (Y) 后跟一个水平和垂直分采样的打包 UV 平面 (U-V)。 |
QVideoFrameFormat::Format_Y8 | 24 | 帧使用 8 位灰度格式存储。 |
QVideoFrameFormat::Format_Y16 | 25 | 帧使用 16 位线性灰度格式存储。小端格式。 |
QVideoFrameFormat::Format_Jpeg | 29 | 图像以压缩 Jpeg 格式存储。 |
QVideoFrameFormat::Format_SamplerExternalOES | 28 | 帧以外部 OES 纹理格式存储。目前仅在安卓系统中使用。 |
QVideoFrameFormat::Format_SamplerRect | 30 | 帧以矩形纹理格式（GL_TEXTURE_RECTANGLE）存储。这种格式仅用于配备基于 OpenGL 的渲染硬件接口的 macOS。纹理中存储的基础像素格式是 Format_BRGA8888。 |
QVideoFrameFormat::Format_YUV420P10 | 31 | 与 YUV420 相似，但每个分量使用 16 位，其中 10 位有效。 |
成员函数文档
QVideoFrameFormat::QVideoFrameFormat()
构造一个空视频流格式。
QVideoFrameFormat::QVideoFrameFormat(const QSize &size, QVideoFrameFormat::PixelFormat format)
用给定的帧size 和像素format 构建视频流。
QVideoFrameFormat::QVideoFrameFormat(const QVideoFrameFormat &other)
构造other 的副本。
[noexcept] QVideoFrameFormat::QVideoFrameFormat(QVideoFrameFormat &&other)
从other 开始构建 QVideoFrameFormat。
[noexcept] QVideoFrameFormat::~QVideoFrameFormat()
销毁视频流描述。
QVideoFrameFormat::ColorRange QVideoFrameFormat::colorRange() const
返回用于渲染视频流的颜色范围。
另请参阅 setColorRange()。
QVideoFrameFormat::ColorSpace QVideoFrameFormat::colorSpace() const
返回视频流的色彩空间。
另请参阅 setColorSpace()。
QVideoFrameFormat::ColorTransfer QVideoFrameFormat::colorTransfer() const
返回用于渲染视频流的色彩转换函数。
另请参阅 setColorTransfer()。
int QVideoFrameFormat::frameHeight() const
返回视频流中帧的高度。
qreal QVideoFrameFormat::frameRate() const
以每秒帧数为单位返回视频流的帧速率。
另请参阅 setFrameRate()。
QSize QVideoFrameFormat::frameSize() const
返回视频流中帧的尺寸。
另请参阅 setFrameSize()、frameWidth() 和frameHeight()。
int QVideoFrameFormat::frameWidth() const
返回视频流中帧的宽度。
另请参阅 frameSize() 和frameHeight()。
[static] QImage::Format QVideoFrameFormat::imageFormatFromPixelFormat(QVideoFrameFormat::PixelFormat format)
返回等同于视频帧像素的图像格式format 。如果没有等效格式，则返回QImage::Format_Invalid 。
注： 一般情况下，QImage 不处理 YUV 格式。
bool QVideoFrameFormat::isMirrored() const
如果曲面绕其垂直轴镜像，则返回true 。
QVideoFrameFormat 的变换，特别是旋转和镜像，可由摄像机传感器的方向、摄像机设置或视频流的方向决定。
镜像应用于旋转之后。
注： 这里的镜像与QImage::mirrored 不同，垂直镜像的QImage 将绕其 x 轴镜像。
bool QVideoFrameFormat::isValid() const
识别视频表面格式的像素格式和帧大小是否有效。
如果格式有效，则返回 true，否则返回 false。
QVideoFrameFormat::PixelFormat QVideoFrameFormat::pixelFormat() const
返回视频流中帧的像素格式。
[static] QVideoFrameFormat::PixelFormat QVideoFrameFormat::pixelFormatFromImageFormat(QImage::Format format)
返回等同于图像format 的视频像素格式。如果没有等效格式，则返回QVideoFrameFormat::Format_Invalid 。
注： 一般情况下，QImage 不处理 YUV 格式。
[static] QString QVideoFrameFormat::pixelFormatToString(QVideoFrameFormat::PixelFormat pixelFormat)
返回给定pixelFormat 的字符串表示。
int QVideoFrameFormat::planeCount() const
返回使用的平面数。该数字取决于像素格式，对于基于 RGB 的格式，该数字为 1；对于基于 YUV 的格式，该数字介于 1 和 3 之间。
QtVideo::Rotation QVideoFrameFormat::rotation() const
返回曲面顺时针旋转的角度。
QVideoFrameFormat 的变换，特别是旋转和镜像，可由摄像机传感器的方向、摄像机设置或视频流的方向决定。
旋转在镜像之前进行。
另请参阅 setRotation() 。
QVideoFrameFormat::Direction QVideoFrameFormat::scanLineDirection() const
返回扫描线的方向。
另请参见 setScanLineDirection()。
void QVideoFrameFormat::setColorRange(QVideoFrameFormat::ColorRange range)
设置用于将视频流渲染到range 的色彩传输范围。
另请参阅 colorRange() 。
void QVideoFrameFormat::setColorSpace(QVideoFrameFormat::ColorSpace colorSpace)
设置视频流的colorSpace 。
另请参阅 colorSpace()。
void QVideoFrameFormat::setColorTransfer(QVideoFrameFormat::ColorTransfer colorTransfer)
设置用于将视频流渲染为colorTransfer 的色彩转换函数。
另请参阅 colorTransfer() 。
void QVideoFrameFormat::setFrameRate(qreal rate)
设置视频流的帧数rate ，单位为每秒帧数。
另请参阅 frameRate()。
void QVideoFrameFormat::setFrameSize(const QSize &size)
将视频流中帧的大小设置为size 。
这将重置viewport() 以填充整个帧。
另请参阅 frameSize()。
void QVideoFrameFormat::setFrameSize(int width, int height)
这是一个重载函数。
设置视频流中帧的width 和height 。
这将重置viewport() 以填充整个帧。
void QVideoFrameFormat::setMaxLuminance(float lum)
将最大亮度设置为给定值lum 。
void QVideoFrameFormat::setMirrored(bool mirrored)
设置曲面是否绕其垂直轴mirrored 。
QVideoFrameFormat 的变换，特别是旋转和镜像，可由摄像机传感器的方向、摄像机设置或视频流的方向决定。
镜像应用于旋转之后。
默认值为false 。
注： 此处的镜像与QImage::mirrored 不同，因为垂直镜像的QImage 将围绕其 x 轴进行镜像。
另请参阅 isMirrored()。
void QVideoFrameFormat::setRotation(QtVideo::Rotation angle)
设置曲面顺时针旋转的angle 。
QVideoFrameFormat 的变换，特别是旋转和镜像，可由摄像机传感器的方向、摄像机设置或视频流的方向决定。
旋转先于镜像应用。
默认值为QtVideo::Rotation::None 。
另请参阅 rotation() 。
void QVideoFrameFormat::setScanLineDirection(QVideoFrameFormat::Direction direction)
设置direction 的扫描行数。
另请参阅 scanLineDirection().
void QVideoFrameFormat::setStreamFrameRate(qreal rate)
设置视频流的帧数rate ，单位为每秒帧数。
另请参阅 streamFrameRate()。
void QVideoFrameFormat::setViewport(const QRect &viewport)
将视频流的视口设置为viewport 。
另请参阅 viewport() 。
qreal QVideoFrameFormat::streamFrameRate() const
以每秒帧数为单位返回视频流的帧速率。
另请参阅 setStreamFrameRate()。
[noexcept] void QVideoFrameFormat::swap(QVideoFrameFormat &other)
将当前视频帧格式与other 互换。
QRect QVideoFrameFormat::viewport() const
返回视频流的视口。
视口是实际显示的视频帧区域。
默认情况下，视口覆盖整个帧。
另请参阅 setViewport()。
bool QVideoFrameFormat::operator!=(const QVideoFrameFormat &other) const
如果other 与此视频格式不同，则返回 true；如果相同，则返回 false。
[noexcept] QVideoFrameFormat &QVideoFrameFormat::operator=(QVideoFrameFormat &&other)
将other 移至QVideoFrameFormat 。
QVideoFrameFormat &QVideoFrameFormat::operator=(const QVideoFrameFormat &other)
将other 的值赋值给该对象。
bool QVideoFrameFormat::operator==(const QVideoFrameFormat &other) const
如果other 与此视频格式相同，则返回 true；如果不同，则返回 false。
© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
