QVideoFrameFormat Class
QVideoFrameFormat 类指定了视频呈现区域的流格式。更多内容...
| 头文件： | #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^深度 - 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 小端序 |
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 值。 |
QVideoFrameFormat::Format_YUYV | 17 | 该帧采用每分量 8 位的打包 YUV 格式存储，其中 U 和 V 平面经过水平子采样（Y-U-Y-V），即两个水平相邻的像素被存储为一个 32 位的大像素，该大像素包含每个像素的 Y 值以及共用的 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 纹理格式存储。目前仅在 Android 系统上使用。 |
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 的副本。
[constexpr noexcept default] 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。
© 2026 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.
