PySide6.QtMultimedia.QVideoFrame

class QVideoFrame

QVideoFrame 类表示视频数据的一帧。More_…

概要

方法

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

一个 QVideoFrame 封装了视频帧的像素数据以及关于该帧的信息。

视频帧可以来自多个地方 - 解码的media，camera，或以编程方式生成。这些帧中像素的描述方式可能大不相同，一些像素格式提供了更大的压缩机会，但以易用性为代价。

视频帧的像素内容可以使用map()函数映射到内存中。成功调用map()后，可以通过各种函数访问视频数据。一些YUV像素格式在多个平面中提供数据。planeCount()方法将返回正在使用的平面数量。

在映射时，每个平面的视频数据可以使用bits()函数访问，该函数返回指向缓冲区的指针。此缓冲区的大小由mappedBytes()函数给出，每行的大小由bytesPerLine()给出。handle()函数的返回值也可以用于通过内部缓冲区的本地API（例如 - OpenGL纹理句柄）访问帧数据。

视频帧也可以有与之相关的时间戳信息。这些时间戳可以用来确定何时开始和停止显示帧。

QVideoFrame 对象可能会消耗大量内存或系统资源，不应在应用程序所需的时间之外长时间持有。

注意

由于视频帧的复制可能成本较高，QVideoFrame 是显式共享的，因此对视频帧所做的任何更改也将适用于任何副本。

另请参阅

QAbstractVideoBuffer QVideoFrameFormat MapMode

class HandleType

识别视频缓冲区句柄的类型。

常量

描述

QVideoFrame.NoHandle

缓冲区没有句柄，其数据只能通过映射缓冲区来访问。

QVideoFrame.RhiTextureHandle

缓冲区的句柄由Qt渲染硬件接口（RHI）定义。RHI是Qt内部用于3D API的图形抽象，如OpenGL、Vulkan、Metal和Direct 3D。

另请参阅

handleType()

class MapMode

枚举视频缓冲区的数据如何映射到系统内存。

常量

描述

QVideoFrame.NotMapped

视频缓冲区未映射到内存。

QVideoFrame.ReadOnly

映射的内存在被映射时填充了来自视频缓冲区的数据，但在取消映射时，映射内存的内容可能会被丢弃。

QVideoFrame.WriteOnly

映射的内存在被映射时未初始化，但在取消映射时，可能修改的内容将用于填充视频缓冲区。

QVideoFrame.ReadWrite

映射的内存填充了来自视频缓冲区的数据，并且在取消映射时，视频缓冲区会重新填充映射内存的内容。

另请参阅

mapMode() map()

在版本6.1中添加。

class RotationAngle

请使用Rotation代替。

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

常量

描述

QVideoFrame.Rotation0

无需旋转，帧具有正确的方向

QVideoFrame.Rotation90

帧应旋转90度

QVideoFrame.Rotation180

帧应旋转180度

QVideoFrame.Rotation270

该帧应旋转270度

在版本6.2.3中添加。

__init__()

构造一个空的视频帧。

__init__(image)
Parameters:

图像 – QImage

从QImage构造一个QVideoFrame。

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

否则，如果QImage::Format与任何视频格式都不匹配，图像将首先使用QImage::convertedTo()函数和Qt::AutoColor标志转换为支持的(A)RGB格式。这可能会导致性能损失。

如果输入QImage的QImage::isNull()评估为真，QVideoFrame将无效，且isValid()将返回false。

另请参阅

pixelFormatFromImageFormat() isNull()

__init__(other)
Parameters:

其他 – QVideoFrame

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

__init__(format)
Parameters:

format – QVideoFrameFormat

构造一个具有给定像素format的视频帧。

__init__(buffer, format)
Parameters:

注意

此函数已弃用。

bytesPerLine(plane)
Parameters:

plane – int

Return type:

整数

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

此值仅在帧数据mapped时有效。

另请参阅

bits() map() mappedBytes() planeCount()

endTime()
Return type:

整数

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

无效时间表示为-1。

另请参阅

setEndTime()

handleType()
Return type:

HandleType

返回视频帧句柄的类型。

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

height()
Return type:

整数

返回视频帧的高度。

isMapped()
Return type:

布尔

识别视频帧的内容是否当前映射到系统内存。

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

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

另请参阅

mapMode() MapMode

isReadable()
Return type:

布尔

识别视频帧的映射内容是否在映射时从帧中读取。

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

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

另请参阅

mapMode() MapMode

isValid()
Return type:

布尔

识别视频帧是否有效。

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

如果框架有效则返回true，如果无效则返回false。

isWritable()
Return type:

布尔

标识当视频帧未映射时，映射的内容是否会被持久化。

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

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

注意

在只读模式下映射的帧数据更改的结果是未定义的。根据缓冲区的实现，更改可能会被持久化，或者更糟糕的是，可能会更改共享缓冲区。

另请参阅

mapMode() MapMode

map(mode)
Parameters:

mode – MapMode

Return type:

布尔

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

在某些情况下，视频帧数据可能存储在视频内存或其他不可访问的内存中，因此在访问像素数据之前需要映射帧。这可能涉及复制内容，因此除非必要，否则避免映射和取消映射。

地图模式 mode 指示映射内存的内容是否应从帧中读取和/或写入帧。如果地图模式包括 QVideoFrame::ReadOnly 标志，则在最初映射时，映射内存将填充视频帧的内容。如果地图模式包括 QVideoFrame::WriteOnly 标志，则在取消映射时，可能修改的映射内存的内容将写回帧。

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

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

如果视频帧以只读模式映射，则允许以只读模式多次映射（并相应次数地取消映射）。在所有其他情况下，必须在第二次映射之前先取消映射帧。

注意

写入映射为只读的内存是未定义的，可能会导致共享数据的更改或崩溃。

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

另请参阅

unmap() mapMode() bits()

mapMode()
Return type:

MapMode

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

另请参阅

map() MapMode

mappedBytes(plane)
Parameters:

plane – int

Return type:

整数

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

此值仅在帧数据mapped时有效。

另请参阅

map()

mirrored()
Return type:

布尔

返回在显示之前是否应该围绕其垂直轴镜像帧。

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

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

另请参阅

setMirrored()

__ne__(other)
Parameters:

其他 – QVideoFrame

Return type:

布尔

如果此QVideoFrame和other不反映相同的帧，则返回true。

__eq__(other)
Parameters:

其他 – QVideoFrame

Return type:

布尔

如果此QVideoFrame和other反映的是同一帧，则返回true。

paint(painter, rect, options)
Parameters:

使用一个QPainter，painter，将此QVideoFrame渲染到rect。PaintOptions options可以用来指定背景颜色以及如何用视频填充rect。

注意

使用此方法时，渲染通常不会使用硬件加速。

pixelFormat()
Return type:

PixelFormat

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

planeCount()
Return type:

整数

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

另请参阅

map()

rotation()
Return type:

Rotation

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

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

另请参阅

setRotation()

rotationAngle()
Return type:

RotationAngle

注意

此函数已弃用。

请使用 QVideoFrame::rotation 代替。

返回在显示之前框架应顺时针旋转的角度。

另请参阅

setRotationAngle()

setEndTime(time)
Parameters:

时间 – int

设置表示time（以微秒为单位）当一帧应停止显示时。

无效时间表示为-1。

另请参阅

endTime()

setMirrored(mirrored)
Parameters:

mirrored – 布尔值

设置是否在显示前将帧绕其垂直轴镜像。

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

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

默认值为 false。

另请参阅

mirrored()

setRotation(angle)
Parameters:

angle – 旋转

设置angle，在显示前将帧顺时针旋转。

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

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

另请参阅

rotation()

setRotationAngle(angle)
Parameters:

角度 – RotationAngle

注意

此函数已弃用。

请使用QVideoFrame::setRotation代替。

设置angle，在显示前将帧顺时针旋转。

另请参阅

rotationAngle()

setStartTime(time)
Parameters:

时间 – int

设置帧最初应显示时的演示时间（以微秒为单位）。

无效时间表示为-1。

另请参阅

startTime()

setStreamFrameRate(rate)
Parameters:

rate – 浮点数

设置视频流的帧率，单位为每秒帧数。

另请参阅

streamFrameRate()

setSubtitleText(text)
Parameters:

文本 – str

设置应与该视频帧一起呈现的字幕文本为text。

另请参阅

subtitleText()

size()
Return type:

QSize

返回视频帧的尺寸。

startTime()
Return type:

整数

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

无效时间表示为-1。

另请参阅

setStartTime()

streamFrameRate()
Return type:

浮点数

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

另请参阅

setStreamFrameRate()

subtitleText()
Return type:

字符串

返回应与该视频帧一起呈现的字幕文本。

另请参阅

setSubtitleText()

surfaceFormat()
Return type:

QVideoFrameFormat

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

swap(other)
Parameters:

其他 – QVideoFrame

将当前视频帧与 other 交换。

toImage()
Return type:

QImage

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

转换基于当前的像素数据和QVideoFrame::surfaceFormat。帧的变换不会影响结果，因为它们仅用于展示。

unmap()

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

如果MapMode包含了WriteOnly标志，这将把映射内存的当前内容持久化到视频帧中。

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

另请参阅

map()

videoBuffer()
Return type:

QAbstractVideoBuffer

注意

此函数已弃用。

width()
Return type:

整数

返回视频帧的宽度。

class PaintOptions

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

class PaintFlag
PySide6.QtMultimedia.QVideoFrame.PaintOptions.backgroundColor
PySide6.QtMultimedia.QVideoFrame.PaintOptions.aspectRatioMode
PySide6.QtMultimedia.QVideoFrame.PaintOptions.paintFlags