QVideoFrame Class

成员函数文档

QVideoFrame::QVideoFrame()

构建一个空视频帧。

[explicit, since 6.8] QVideoFrame::QVideoFrame(const QImage &image)

根据QImage 构建一个QVideoFrame。

如果QImage::Format 与QVideoFrameFormat::PixelFormat 中的某种格式匹配，则QVideoFrame将包含image 的实例，并直接采用该格式，无需进行任何像素格式转换。在此情况下，只有当您在调用QVideoFrame::map 时同时启用WriteOnly 标志并保留原始图像时，才会复制像素数据。

否则，如果QImage::Format 与任何视频格式均不匹配，则会先使用QImage::convertedTo()并带上Qt::AutoColor 标志，将图像转换为受支持的(A)RGB格式。这可能会导致性能开销。

如果对于输入的QImage ，QImage::isNull() 的评估结果为 true，则 QVideoFrame 将失效，且QVideoFrameFormat::isValid() 将返回 false。

该函数在 Qt 6.8 中引入。

另请参阅 QVideoFrameFormat::pixelFormatFromImageFormat()、QImage::convertedTo() 和QImage::isNull()。

QVideoFrame::QVideoFrame(const QVideoFrameFormat &format)

根据给定的像素format 构建一个视频帧。

[explicit, since 6.8] QVideoFrame::QVideoFrame(std::unique_ptr<QAbstractVideoBuffer> videoBuffer)

根据QAbstractVideoBuffer 实例构建一个QVideoFrame。

指定的videoBuffer 指代一个重写了QAbstractVideoBuffer 的实例。该实例应包含一个预分配的自定义视频缓冲区，并且必须为GPU内容实现QAbstractVideoBuffer::format 、QAbstractVideoBuffer::map 和QAbstractVideoBuffer::unmap 。

如果 `videoBuffer ` 为空或获取了一个无效的 `QVideoFrameFormat`，则构造函数将创建一个无效的视频帧。

创建的帧在其生命周期内将持有指定视频缓冲区的所有权。鉴于 QVideoFrame 是通过一个共享的私有对象实现的，当创建的视频帧的最后一份副本被销毁时，指定的视频缓冲区也将被销毁。

请注意，如果视频帧已被传递给 `QMediaRecorder ` 或渲染管道，则该帧的生命周期未定义，媒体记录器可能会在另一个线程中销毁它。

QVideoFrame 将包含其自身的QVideoFrameFormat 实例。调用setStreamFrameRate 、setMirrored 或setRotation 时，可以修改内部格式，而surfaceFormat 将返回一个已分离的实例。

该函数在 Qt 6.8 中引入。

另请参阅 QAbstractVideoBuffer 和QVideoFrameFormat 。

QVideoFrame::QVideoFrame(const QVideoFrame &other)

创建other 的浅拷贝。由于QVideoFrame是显式共享的，这两个实例将反映同一帧。

[constexpr noexcept default] QVideoFrame::QVideoFrame(QVideoFrame &&other)

通过从other 开始构建一个QVideoFrame。

[noexcept] QVideoFrame::~QVideoFrame()

销毁一个视频帧。

uchar *QVideoFrame::bits(int plane)

返回指向plane 的帧数据缓冲区起始位置的指针。

该值仅在帧数据处于mapped 状态时有效。

通过该指针访问的数据（当以写入权限映射时）所做的更改，仅在调用unmap() 且缓冲区已映射为可写时，才保证已被持久化。

另请参见 map()、mappedBytes()、bytesPerLine() 和planeCount()。

const uchar *QVideoFrame::bits(int plane) const

返回指向plane 的帧数据缓冲区起始位置的指针。

该值仅在帧数据处于mapped 状态时有效。

如果该缓冲区未以可读方式映射，则该缓冲区的初始内容将为未初始化状态。

另请参阅 map()、mappedBytes()、bytesPerLine() 和planeCount()。

int QVideoFrame::bytesPerLine(int plane) const

返回plane 中一条扫描线的字节数。

该值仅在帧数据为mapped 时有效。

另请参阅 bits()、map()、mappedBytes() 以及planeCount()。

qint64 QVideoFrame::endTime() const

返回帧应停止显示时的呈现时间（单位为微秒）。

无效的时间值表示为 -1。

另请参阅 setEndTime()。

QVideoFrame::HandleType QVideoFrame::handleType() const

返回视频帧句柄的类型。

该句柄类型可以是NoHandle ，表示该帧基于内存，也可以是 RHI 纹理。

int QVideoFrame::height() const

返回视频帧的高度。

bool QVideoFrame::isMapped() const

用于判断视频帧的内容当前是否已映射到系统内存中。

这是一个便捷函数，用于检查帧的MapMode 是否不等于QVideoFrame::NotMapped 。

如果视频帧的内容已映射到系统内存，则返回 true；否则返回 false。

另请参阅 mapMode() 和QVideoFrame::MapMode 。

bool QVideoFrame::isReadable() const

用于判断视频帧的映射内容是否是在该帧被映射时从帧中读取的。

这是一个便捷函数，用于检查MapMode 是否包含QVideoFrame::WriteOnly 标志。

如果映射内存的内容是从视频帧中读取的，则返回 true；否则返回 false。

另请参阅 mapMode() 和QVideoFrame::MapMode 。

bool QVideoFrame::isValid() const

用于判断视频帧是否有效。

无效帧没有与其关联的视频缓冲区。

如果帧有效，则返回 true；如果无效，则返回 false。

bool QVideoFrame::isWritable() const

用于确定视频帧的映射内容在帧被解除映射时是否会被保留。

这是一个便捷函数，用于检查MapMode 是否包含QVideoFrame::WriteOnly 标志。

如果视频帧在解除映射时将被更新，则返回 true；否则返回 false。

另请参阅 mapMode() 和QVideoFrame::MapMode 。

bool QVideoFrame::map(QVideoFrame::MapMode mode)

将视频帧的内容映射到系统（CPU 可寻址）内存中。

在某些情况下，视频帧数据可能存储在视频内存或其他无法直接访问的内存中，因此在访问像素数据之前，必须先对帧进行映射。这可能涉及数据复制操作，因此除非必要，否则应避免进行映射和取消映射。

映射函数 `mode ` 用于指定映射内存的内容应从帧中读取和/或写入帧。如果映射模式包含 `QVideoFrame::ReadOnly ` 标志，则在初始映射时，映射内存将被视频帧的内容填充。如果映射模式包含 `QVideoFrame::WriteOnly ` 标志，则在解除映射时，可能已被修改的映射内存内容将被写回帧中。

在映射期间，可通过bits()函数返回的指针直接访问视频帧的内容。

当不再需要访问数据时，请务必调用unmap() 函数以释放映射的内存，并可能更新视频帧的内容。

如果视频帧是在只读模式下映射的，则允许以只读模式多次映射它（并相应地取消映射相同次数）。在所有其他情况下，必须先取消帧的映射，然后才能进行第二次映射。

如果帧已映射到给定的mode 中的内存，则返回true；否则返回false。

另请参阅 unmap()、mapMode() 和bits()。

QVideoFrame::MapMode QVideoFrame::mapMode() const

返回视频帧映射到系统内存时的模式。

另请参阅 map() 和QVideoFrame::MapMode 。

int QVideoFrame::mappedBytes(int plane) const

返回映射帧数据中平面plane 所占用的字节数。

该值仅在帧数据处于mapped 状态时有效。

另请参阅 map()。

bool QVideoFrame::mirrored() const

返回在显示帧之前是否应将其沿垂直轴进行镜像。

QVideoFrame 的变换（特别是旋转和镜像）仅用于显示视频帧，且在由QVideoFrameFormat 确定的表面变换之上应用。镜像操作在旋转之后进行。

通常，来自移动设备前置摄像头的视频帧需要进行镜像处理。

另请参阅 setMirrored()。

void QVideoFrame::paint(QPainter *painter, const QRectF &rect, const QVideoFrame::PaintOptions &options)

使用QPainter （painter ）将QVideoFrame 渲染为rect 。可通过PaintOptions（options ）指定背景色，并设定rect 应如何填充视频内容。

QVideoFrameFormat::PixelFormat QVideoFrame::pixelFormat() const

返回该视频帧的像素格式。

int QVideoFrame::planeCount() const

返回视频帧中的平面数量。

另请参阅 map()。

QtVideo::Rotation QVideoFrame::rotation() const

返回视频帧在显示前应顺时针旋转的角度。

QVideoFrame 的变换（特别是旋转和镜像）仅用于显示视频帧，且在由QVideoFrameFormat 确定的表面变换之上应用。旋转操作在镜像操作之前进行。

另请参阅 setRotation()。

void QVideoFrame::setEndTime(qint64 time)

设置渲染time （单位为微秒），表示帧应停止显示的时间。

无效的时间值表示为 -1。

另请参阅 endTime()。

void QVideoFrame::setMirrored(bool mirrored)

设置视频帧在显示前是否应围绕其垂直轴进行mirrored 。

QVideoFrame 中的变换（特别是旋转和镜像）仅用于显示视频帧，且在由QVideoFrameFormat 确定的表面变换之上应用。镜像操作在旋转之后进行。

对于来自移动设备前置摄像头的视频帧，通常需要进行镜像处理。

默认值为 `false`。

另请参阅 mirrored()。

void QVideoFrame::setRotation(QtVideo::Rotation angle)

设置angle ，指定在显示帧之前应将其顺时针旋转。

QVideoFrame 的变换（特别是旋转和镜像）仅用于显示视频帧，且在表面变换之上应用，而表面变换由QVideoFrameFormat 决定。旋转操作在镜像操作之前进行。

默认值为QtVideo::Rotation::None 。

另请参阅 rotation()。

void QVideoFrame::setStartTime(qint64 time)

设置帧应首次显示时的呈现时间time （单位为微秒）。

无效的时间值表示为 -1。

另请参阅 startTime()。

void QVideoFrame::setStreamFrameRate(qreal rate)

将视频流的帧rate 设置为每秒帧数。

另请参阅 streamFrameRate()。

void QVideoFrame::setSubtitleText(const QString &text)

将应与该视频帧一同渲染的字幕文本设置为text 。

另请参阅 subtitleText()。

QSize QVideoFrame::size() const

返回视频帧的尺寸。

qint64 QVideoFrame::startTime() const

返回应显示该帧时的呈现时间（单位为微秒）。

无效的时间表示为 -1。

另请参阅 setStartTime()。

qreal QVideoFrame::streamFrameRate() const

返回视频流的帧率（单位为每秒帧数）。

另请参阅 setStreamFrameRate()。

QString QVideoFrame::subtitleText() const

返回应与该视频帧一同渲染的字幕文本。

另请参阅 ` setSubtitleText()`。

QVideoFrameFormat QVideoFrame::surfaceFormat() const

返回该视频帧的表面格式。

[noexcept] void QVideoFrame::swap(QVideoFrame &other)

将当前视频帧与other 互换。

QImage QVideoFrame::toImage() const

将当前视频帧转换为图像。

该转换基于当前像素数据和surface format 。帧的变换不会影响结果，因为这些变换仅用于呈现。

void QVideoFrame::unmap()

释放由map()函数映射的内存。

如果MapMode 函数中包含QVideoFrame::WriteOnly 标志，则会将映射内存的当前内容保留到视频帧中。

如果map()函数调用失败，则不应调用unmap()。

另请参阅 map()。

int QVideoFrame::width() const

返回视频帧的宽度。

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

如果QVideoFrame 和other 指向的不同帧，则返回true 。

[noexcept] QVideoFrame &QVideoFrame::operator=(QVideoFrame &&other)

将other 移动到此处：QVideoFrame 。

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

将other 的内容赋值给此视频帧。由于QVideoFrame 被显式共享，这两个实例将反映同一帧。

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

如果此QVideoFrame 和other 指向同一帧，则返回true 。