QVideoFrame Class

成员函数文档

QVideoFrame::QVideoFrame()

构建一个空视频帧。

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

从QImage 构建一个 QVideoFrame。

如果QImage::Format 与QVideoFrameFormat::PixelFormat 中的格式之一相匹配，则 QVideoFrame 将持有image 的一个实例，并使用该格式而不进行任何像素格式转换。在这种情况下，只有在调用带有WriteOnly 标记的QVideoFrame::map 时才会复制像素数据，同时保留原始图像。

否则，如果QImage::Format 与任何视频格式都不匹配，则首先使用带有Qt::AutoColor 标志的QImage::convertedTo() 将图像转换为受支持的 (A)RGB 格式。这可能会影响性能。

如果QImage::isNull() 对输入QImage 评估为 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 实例。该实例预计将包含一个预分配的自定义视频缓冲区，并且必须实现QAbstractVideoBuffer::format 、QAbstractVideoBuffer::map 和QAbstractVideoBuffer::unmap 以获取 GPU 内容。

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

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

请注意，如果视频帧已传送到QMediaRecorder 或渲染流水线，则该帧的生命周期是未定义的，媒体记录器可以在不同的线程中销毁它。

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

此函数在 Qt 6.8 中引入。

另请参阅 QAbstractVideoBuffer 和QVideoFrameFormat 。

QVideoFrame::QVideoFrame(const QVideoFrame &other)

构造other 的浅层副本。由于 QVideoFrame 是显式共享的，这两个实例将反映相同的帧。

[noexcept] 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 。可使用 PaintOptionsoptions 指定背景颜色以及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 。