QVideoFrame 类

QVideoFrame 类表示视频数据帧。更多...

头：	#include <QVideoFrame>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Multimedia) target_link_libraries(mytarget PRIVATE Qt6::Multimedia)
qmake:	QT += multimedia

公共类型

enum	HandleType { NoHandle, RhiTextureHandle }
enum	MapMode { NotMapped, ReadOnly, WriteOnly, ReadWrite }

公共函数

	QVideoFrame ()
	QVideoFrame (const QVideoFrameFormat & format )
	QVideoFrame (const QVideoFrame & other )
	QVideoFrame (QVideoFrame && other )
	~QVideoFrame ()
uchar *	bits (int plane )
const uchar *	bits (int plane ) const
int	bytesPerLine (int plane ) const
qint64	endTime () const
QVideoFrame::HandleType	handleType () const
int	height () const
bool	isMapped () const
bool	isReadable () const
bool	isValid () const
bool	isWritable () const
bool	map (QVideoFrame::MapMode mode )
QVideoFrame::MapMode	mapMode () const
int	mappedBytes (int plane ) const
bool	mirrored () const
void	paint (QPainter * painter , const QRectF & rect , const QVideoFrame::PaintOptions & options )
QVideoFrameFormat::PixelFormat	pixelFormat () const
int	planeCount () const
QtVideo::Rotation	rotation () const
void	setEndTime (qint64 time )
void	setMirrored (bool mirrored )
void	setRotation (QtVideo::Rotation angle )
void	setStartTime (qint64 time )
void	setSubtitleText (const QString & text )
QSize	size () const
qint64	startTime () const
QString	subtitleText () const
QVideoFrameFormat	surfaceFormat () const
void	swap (QVideoFrame & other )
QImage	toImage () const
void	unmap ()
int	width () const
bool	operator!= (const QVideoFrame & other ) const
QVideoFrame &	operator= (QVideoFrame && other )
QVideoFrame &	operator= (const QVideoFrame & other )
bool	operator== (const QVideoFrame & other ) const

详细描述

QVideoFrame 封装视频帧的像素数据，及帧有关信息。

Video frames can come from several places - decoded media ， camera , or generated programmatically. The way pixels are described in these frames can vary greatly, and some pixel formats offer greater compression opportunities at the expense of ease of use.

The pixel contents of a video frame can be mapped to memory using the map () function. After a successful call to map (), the video data can be accessed through various functions. Some of the YUV pixel formats provide the data in several planes. The planeCount () method will return the amount of planes that being used.

While mapped, the video data of each plane can accessed using the bits () function, which returns a pointer to a buffer. The size of this buffer is given by the mappedBytes () function, and the size of each line is given by bytesPerLine (). The return value of the handle() function may also be used to access frame data using the internal buffer's native APIs (for example - an OpenGL texture handle).

A video frame can also have timestamp information associated with it. These timestamps can be used to determine when to start and stop displaying the frame.

QVideoFrame objects can consume a significant amount of memory or system resources and should not be held for longer than required by the application.

注意： Since video frames can be expensive to copy, QVideoFrame is explicitly shared, so any change made to a video frame will also apply to any copies.

成员类型文档编制

enum QVideoFrame:: HandleType

标识视频缓冲句柄的类型。

常量	值	描述
`QVideoFrame::NoHandle`	`0`	缓冲没有句柄，只能通过映射缓冲访问其数据。
`QVideoFrame::RhiTextureHandle`	`1`	The handle of the buffer is defined by The Qt Rendering Hardware Interface (RHI). RHI is Qt's internal graphics abstraction for 3D APIs, such as OpenGL, Vulkan, Metal, and Direct 3D.

另请参阅 handleType ().

enum QVideoFrame:: MapMode

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

常量	值	描述
`QVideoFrame::NotMapped`	`0x00`	不把视频缓冲映射到内存。
`QVideoFrame::ReadOnly`	`0x01`	The mapped memory is populated with data from the video buffer when mapped, but the content of the mapped memory may be discarded when unmapped.
`QVideoFrame::WriteOnly`	`0x02`	The mapped memory is uninitialized when mapped, but the possibly modified content will be used to populate the video buffer when unmapped.
`QVideoFrame::ReadWrite`	`ReadOnly \| WriteOnly`	The mapped memory is populated with data from the video buffer, and the video buffer is repopulated with the content of the mapped memory when it is unmapped.

另请参阅 mapMode () 和 map ().

成员函数文档编制

QVideoFrame:: QVideoFrame ()

构造 null 视频帧。

QVideoFrame:: QVideoFrame (const QVideoFrameFormat & format )

Constructs a video frame of the given pixel format .

QVideoFrame:: QVideoFrame (const QVideoFrame & other )

Constructs a shallow copy of other . Since QVideoFrame is explicitly shared, these two instances will reflect the same frame.

`[noexcept]` QVideoFrame:: QVideoFrame ( QVideoFrame && other )

Constructs a QVideoFrame by moving from other .

`[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

Returns the number of bytes in a scan line of a plane .

此值才有效当帧数据为 mapped .

另请参阅 bits (), map (), mappedBytes ()，和 planeCount ().

qint64 QVideoFrame:: endTime () const

Returns the presentation time (in microseconds) when a frame should stop being displayed.

无效时间表示为 -1。

另请参阅 setEndTime ().

QVideoFrame::HandleType QVideoFrame:: handleType () const

返回视频帧的句柄类型。

The handle type could either be NoHandle , meaning that the frame is memory based, or a RHI texture.

int QVideoFrame:: height () const

返回视频帧的高度。

bool QVideoFrame:: isMapped () const

Identifies if a video frame's contents are currently mapped to system memory.

This is a convenience function which checks that the MapMode of the frame is not equal to QVideoFrame::NotMapped .

Returns true if the contents of the video frame are mapped to system memory, and false otherwise.

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

bool QVideoFrame:: isReadable () const

Identifies if the mapped contents of a video frame were read from the frame when it was mapped.

这是方便校验函数若 MapMode 包含 QVideoFrame::WriteOnly 标志。

Returns true if the contents of the mapped memory were read from the video frame, and false otherwise.

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

bool QVideoFrame:: isValid () const

标识视频帧是否有效。

无效帧没有关联它的视频缓冲。

返回 true 若帧有效，和 false 若帧无效。

bool QVideoFrame:: isWritable () const

Identifies if the mapped contents of a video frame will be persisted when the frame is unmapped.

这是方便校验函数若 MapMode 包含 QVideoFrame::WriteOnly 标志。

Returns true if the video frame will be updated when unmapped, and false otherwise.

注意： The result of altering the data of a frame that is mapped in read-only mode is undefined. Depending on the buffer implementation the changes may be persisted, or worse alter a shared buffer.

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

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

把视频帧的内容映射到系统 (CPU 可寻址) 内存。

在某些情况下，视频帧数据可能被存储在视频内存或其它不可访问内存中，因此有必要映射帧在访问像素数据之前。这可能涉及围绕内容的拷贝，因此，应避免映射和取消映射 (除非要求)。

映射 mode 指示映射内存内容是否应读取自和/或写入帧。若映射模式包括 QVideoFrame::ReadOnly 标志将采用视频帧内容填充映射内存当初始映射时。若映射模式包括 QVideoFrame::WriteOnly 标志可能将修改映射内存内容写回到帧当取消映射时。

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

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

若视频帧已映射在只读模式下，以只读模式多次映射它 (且取消映射它相应次数) 是准许的。在所有其它情况下，有必要先取消帧映射，在映射第二次之前。

注意： 作为只读的写入映射内存是未定义的，并可能导致共享数据改变或崩溃。

返回 true 若帧被映射到内存按给定 mode 和 false 否则。

另请参阅 unmap (), mapMode ()，和 bits ().

QVideoFrame::MapMode QVideoFrame:: mapMode () const

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

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

int QVideoFrame:: mappedBytes ( int plane ) const

Returns the number of bytes occupied by plane plane of the mapped frame data.

此值才有效当帧数据为 mapped .

另请参阅 map ().

bool QVideoFrame:: mirrored () const

Returns whether the frame should be mirrored before displaying.

另请参阅 setMirrored ().

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

Uses a QPainter , painter , to render this QVideoFrame to rect . The PaintOptions options can be used to specify a background color and how rect should be filled with the video.

注意： that rendering will usually happen without hardware acceleration when using this method.

QVideoFrameFormat::PixelFormat QVideoFrame:: pixelFormat () const

Returns the pixel format of this video frame.

int QVideoFrame:: planeCount () const

返回视频帧中的平面数。

另请参阅 map ().

QtVideo::Rotation QVideoFrame:: rotation () const

Returns the angle the frame should be rotated clockwise before displaying.

另请参阅 setRotation ().

void QVideoFrame:: setEndTime ( qint64 time )

设置呈现 time (以微秒为单位) 当帧应停止显示时。

无效时间表示为 -1。

另请参阅 endTime ().

void QVideoFrame:: setMirrored ( bool mirrored )

设置 mirrored flag for the frame and sets the flag to the underlying surfaceFormat .

另请参阅 mirrored ().

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

设置 angle the frame should be rotated clockwise before displaying.

另请参阅 rotation ().

void QVideoFrame:: setStartTime ( qint64 time )

设置呈现 time (以微秒为单位) 当帧应该被初始显示时。

无效时间表示为 -1。

另请参阅 startTime ().

void QVideoFrame:: setSubtitleText (const QString & text )

Sets the subtitle text that should be rendered together with this video frame to text .

另请参阅 subtitleText ().

QSize QVideoFrame:: size () const

返回视频帧尺度。

qint64 QVideoFrame:: startTime () const

返回呈现时间 (以微秒为单位) 当帧应该被显示时。

无效时间表示为 -1。

另请参阅 setStartTime ().

QString QVideoFrame:: subtitleText () const

Returns the subtitle text that should be rendered together with this video frame.

另请参阅 setSubtitleText ().

QVideoFrameFormat QVideoFrame:: surfaceFormat () const

Returns the surface format of this video frame.

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

Swaps the current video frame with other .

QImage QVideoFrame:: toImage () const

基于像素格式将当前视频帧转换成图像。

void QVideoFrame:: unmap ()

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

若 MapMode 包括 QVideoFrame::WriteOnly 标志，则这会把映射内存当前内容坚持到视频帧。

unmap() 不应被调用，若 map () 函数失败。

另请参阅 map ().

int QVideoFrame:: width () const

返回视频帧的宽度。

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

返回 true 若此 QVideoFrame and other 不反射相同帧。

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

移动 other 到此 QVideoFrame .

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

Assigns the contents of other to this video frame. Since QVideoFrame is explicitly shared, these two instances will reflect the same frame.

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

返回 true 若此 QVideoFrame and other 反射相同帧。

QVideoFrame 类

公共类型

公共函数

详细描述

成员类型文档编制

enum QVideoFrame:: HandleType

enum QVideoFrame:: MapMode

成员函数文档编制

QVideoFrame:: QVideoFrame ()

QVideoFrame:: QVideoFrame (const QVideoFrameFormat & format )

QVideoFrame:: QVideoFrame (const QVideoFrame & other )

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

[noexcept] QVideoFrame:: ~QVideoFrame ()

uchar *QVideoFrame:: bits ( int plane )

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

int QVideoFrame:: bytesPerLine ( int plane ) const

qint64 QVideoFrame:: endTime () const

QVideoFrame::HandleType QVideoFrame:: handleType () const

int QVideoFrame:: height () const

bool QVideoFrame:: isMapped () const

bool QVideoFrame:: isReadable () const

bool QVideoFrame:: isValid () const

bool QVideoFrame:: isWritable () const

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

QVideoFrame::MapMode QVideoFrame:: mapMode () const

int QVideoFrame:: mappedBytes ( int plane ) const

bool QVideoFrame:: mirrored () const

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

QVideoFrameFormat::PixelFormat QVideoFrame:: pixelFormat () const

int QVideoFrame:: planeCount () const

QtVideo::Rotation QVideoFrame:: rotation () const

void QVideoFrame:: setEndTime ( qint64 time )

void QVideoFrame:: setMirrored ( bool mirrored )

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

void QVideoFrame:: setStartTime ( qint64 time )

void QVideoFrame:: setSubtitleText (const QString & text )

QSize QVideoFrame:: size () const

qint64 QVideoFrame:: startTime () const

QString QVideoFrame:: subtitleText () const

QVideoFrameFormat QVideoFrame:: surfaceFormat () const

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

QImage QVideoFrame:: toImage () const

void QVideoFrame:: unmap ()

int QVideoFrame:: width () const

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

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

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

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

内容

`[noexcept]` QVideoFrame:: QVideoFrame ( QVideoFrame && other )

`[noexcept]` QVideoFrame:: ~QVideoFrame ()

uchar QVideoFrame:: bits ( int plane* )

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

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

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