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 () | |
(从 6.8 起)
|
QVideoFrame (const QImage & image ) |
| QVideoFrame (const QVideoFrameFormat & format ) | |
(从 6.8 起)
|
QVideoFrame (std::unique_ptr<QAbstractVideoBuffer> videoBuffer ) |
| 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 | setStreamFrameRate (qreal rate ) |
| void | setSubtitleText (const QString & text ) |
| QSize | size () const |
| qint64 | startTime () const |
| qreal | streamFrameRate () 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 封装视频帧的像素数据，及帧的有关信息。
视频帧可以来自几个地方 - 解码的 media ， camera ，或以编程方式生成。在这些帧中描述像素的方式可能有很大不同，且一些像素格式以易用性为代价提供更大压缩机会。
视频帧的像素内容映射到内存可以使用 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 () 函数，和每行大小的给定是通过 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.
注意： 由于 QVideoFrame 是明确共享的，要拷贝的视频帧可能很昂贵，所以对视频帧所做的任何改变也将应用于任何副本。
另请参阅 QAbstractVideoBuffer , QVideoFrameFormat ，和 QVideoFrame::MapMode .
标识视频缓冲句柄的类型。
| 常量 | 值 | 描述 |
|---|---|---|
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 ().
枚举如何把视频缓冲数据映射到系统内存。
| 常量 | 值 | 描述 |
|---|---|---|
QVideoFrame::NotMapped
|
0x00
|
不把视频缓冲映射到内存。 |
QVideoFrame::ReadOnly
|
0x01
|
采用来自视频缓冲的数据填充映射内存当映射时，但可能丢弃所映射内存的内容当取消映射时。 |
QVideoFrame::WriteOnly
|
0x02
|
映射内存未初始化当映射时，但可能修改的内容将用于填充视频缓冲当取消映射时。 |
QVideoFrame::ReadWrite
|
ReadOnly | WriteOnly
|
采用来自视频缓冲的数据填充映射内存，并采用映射内存的内容重新填充视频缓冲当取消映射时。 |
构造 null 视频帧。
[explicit, since 6.8]
QVideoFrame::
QVideoFrame
(const
QImage
&
image
)
Constructs a QVideoFrame from a QImage .
若
QImage::Format
matches one of the formats in
QVideoFrameFormat::PixelFormat
, the QVideoFrame will hold an instance of the
image
and use that format without any pixel format conversion. In this case, pixel data will be copied only if you call
QVideoFrame::map
with
WriteOnly
flag while keeping the original image.
Otherwise, if the QImage::Format matches none of video formats, the image is first converted to a supported (A)RGB format using QImage::convertedTo () 采用 Qt::AutoColor flag. This may incur a performance penalty.
若 QImage::isNull () evaluates to true for the input QImage , the QVideoFrame will be invalid and QVideoFrameFormat::isValid () 将返回 false。
该函数在 Qt 6.8 引入。
另请参阅 QVideoFrameFormat::pixelFormatFromImageFormat (), QImage::convertedTo ()，和 QImage::isNull ().
构造视频帧采用给定像素 format .
[explicit, since 6.8]
QVideoFrame::
QVideoFrame
(
std::unique_ptr
<
QAbstractVideoBuffer
>
videoBuffer
)
Constructs a QVideoFrame from a QAbstractVideoBuffer .
指定 videoBuffer refers to an instance a reimplemented QAbstractVideoBuffer . The instance is expected to contain a preallocated custom video buffer and must implement QAbstractVideoBuffer::format , QAbstractVideoBuffer::map ，和 QAbstractVideoBuffer::unmap for GPU content.
若 videoBuffer is null or gets an invalid QVideoFrameFormat , the constructors creates an invalid video frame.
The created frame will hold ownership of the specified video buffer for its lifetime. Considering that QVideoFrame is implemented via a shared private object, the specified video buffer will be destroyed upon destruction of the last copy of the created video frame.
Note, if a video frame has been passed to QMediaRecorder or a rendering pipeline, the lifetime of the frame is undefined, and the media recorder can destroy it in a different thread.
QVideoFrame will contain own instance of QVideoFrameFormat . Upon invoking setStreamFrameRate , setMirrored ，或 setRotation , the inner format can be modified, and surfaceFormat will return a detached instance.
该函数在 Qt 6.8 引入。
另请参阅 QAbstractVideoBuffer and QVideoFrameFormat .
构造浅拷贝为 other 。由于 QVideoFrame 是明确共享的，所以这 2 实例将反射相同帧。
[noexcept]
QVideoFrame::
QVideoFrame
(
QVideoFrame
&&
other
)
Constructs a QVideoFrame by moving from other .
[noexcept]
QVideoFrame::
~QVideoFrame
()
销毁视频帧。
返回指针指向帧数据缓冲的开始为 plane .
此值才有效当帧数据为 mapped .
凭借此指针访问数据做出的改变 (当采用写入访问映射时) 只保证有持久化当 unmap () 被调用和当缓冲已被映射以供写入。
另请参阅 map (), mappedBytes (), bytesPerLine ()，和 planeCount ().
返回指针指向帧数据缓冲的开始为 plane .
此值才有效当帧数据为 mapped .
若缓冲未采用读取访问被映射，此缓冲的内容将被初始为未被初始化。
另请参阅 map (), mappedBytes (), bytesPerLine ()，和 planeCount ().
Returns the number of bytes in a scan line of a plane .
此值才有效当帧数据为 mapped .
另请参阅 bits (), map (), mappedBytes ()，和 planeCount ().
返回要显示的呈现时间 (以微秒为单位)，当帧应停止时。
无效时间表示为 -1。
另请参阅 setEndTime ().
返回视频帧的句柄类型。
The handle type could either be NoHandle , meaning that the frame is memory based, or a RHI texture.
返回视频帧的高度。
标识目前是否把视频帧内容，映射到系统内存。
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 .
标识视频帧映射内容，是否是从帧读取当映射时。
这是方便校验函数若 MapMode 包含 QVideoFrame::WriteOnly 标志。
返回 true 若从视频帧读取映射内存内容，和 false 否则。
另请参阅 mapMode () 和 QVideoFrame::MapMode .
标识视频帧是否有效。
无效帧没有关联它的视频缓冲。
返回 true 若帧有效，和 false 若帧无效。
标识视频帧的映射内容是否会持久化，当取消帧映射时。
这是方便校验函数若 MapMode 包含 QVideoFrame::WriteOnly 标志。
返回 true 若将更新视频帧当取消映射时，否则返回 false。
注意： 更改以只读方式映射帧数据的结果未定义。从属缓冲实现，改变可能持久化，或更糟更改共享缓冲。
另请参阅 mapMode () 和 QVideoFrame::MapMode .
把视频帧的内容映射到系统 (CPU 可寻址) 内存。
在某些情况下，视频帧数据可能存储在视频内存 (或其它不可访问内存) 中，因此有必要映射帧在访问像素数据前。这可能涉及围绕内容的拷贝，所以，应避免映射和取消映射 (除非要求)。
映射
mode
指示映射内存内容是否应读取自和/或写入帧。若映射模式包括
QVideoFrame::ReadOnly
标志将采用视频帧内容填充映射内存当初始映射时。若映射模式包括
QVideoFrame::WriteOnly
标志可能将修改映射内存内容写回到帧当取消映射时。
当映射时，可以直接访问视频帧内容透过指针返回通过 bits () 函数。
当访问数据不再需要时，确保调用 unmap () 函数以释放映射内存且可能更新视频帧内容。
若已以只读方式映射视频帧，则以只读方式多次映射 (且取消映射它相应次数) 是准许的。在所有其它情况下，有必要先取消帧映射，在第 2 次映射前。
注意： 由于只读写入映射内存未定义，且可能导致共享数据改变 (或崩溃)。
返回 true 若映射帧到内存按给定 mode 和 false 否则。
另请参阅 unmap (), mapMode ()，和 bits ().
返回将视频帧映射到系统内存中的模式。
另请参阅 map () 和 QVideoFrame::MapMode .
Returns the number of bytes occupied by plane plane of the mapped frame data.
此值才有效当帧数据为 mapped .
另请参阅 map ().
Returns whether the frame should be mirrored around its vertical axis before displaying.
Transformations of
QVideoFrame
, specifically rotation and mirroring, are used only for displaying the video frame and are applied on top of the surface transformation, which is determined by
QVideoFrameFormat
. Mirroring is applied after rotation.
Mirroring is typically needed for video frames coming from a front camera of a mobile device.
另请参阅 setMirrored ().
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.
Returns the pixel format of this video frame.
返回视频帧中的平面数。
另请参阅 map ().
Returns the angle the frame should be rotated clockwise before displaying.
Transformations of
QVideoFrame
, specifically rotation and mirroring, are used only for displaying the video frame and are applied on top of the surface transformation, which is determined by
QVideoFrameFormat
. Rotation is applied before mirroring.
另请参阅 setRotation ().
设置呈现 time (以微秒为单位) 当帧应停止显示时。
无效时间表示为 -1。
另请参阅 endTime ().
Sets whether the frame should be mirrored around its vertical axis before displaying.
Transformations of
QVideoFrame
, specifically rotation and mirroring, are used only for displaying the video frame and are applied on top of the surface transformation, which is determined by
QVideoFrameFormat
. Mirroring is applied after rotation.
Mirroring is typically needed for video frames coming from a front camera of a mobile device.
Default value is
false
.
另请参阅 mirrored ().
设置 angle the frame should be rotated clockwise before displaying.
Transformations of
QVideoFrame
, specifically rotation and mirroring, are used only for displaying the video frame and are applied on top of the surface transformation, which is determined by
QVideoFrameFormat
. Rotation is applied before mirroring.
Default value is
QtVideo::Rotation::None
.
另请参阅 rotation ().
设置呈现 time (以微秒为单位) 当帧应该被初始显示时。
无效时间表示为 -1。
另请参阅 startTime ().
Sets the frame rate of a video stream in frames per second.
另请参阅 streamFrameRate ().
Sets the subtitle text that should be rendered together with this video frame to text .
另请参阅 subtitleText ().
返回视频帧尺度。
返回呈现时间 (以微秒为单位) 当帧应该被显示时。
无效时间表示为 -1。
另请参阅 setStartTime ().
Returns the frame rate of a video stream in frames per second.
另请参阅 setStreamFrameRate ().
Returns the subtitle text that should be rendered together with this video frame.
另请参阅 setSubtitleText ().
Returns the surface format of this video frame.
[noexcept]
void
QVideoFrame::
swap
(
QVideoFrame
&
other
)
Swaps the current video frame with other .
Converts current video frame to image.
The conversion is based on the current pixel data and the surface format . Transformations of the frame don't impact the result since they are applied for presentation only.
释放内存映射通过 map () 函数。
若 MapMode 包括 QVideoFrame::WriteOnly 标志，则这会把映射内存当前内容坚持到视频帧。
unmap() 不应被调用，若 map () 函数失败。
另请参阅 map ().
返回视频帧的宽度。
返回
true
若此
QVideoFrame
and
other
不反射相同帧。
[noexcept]
QVideoFrame
&QVideoFrame::
operator=
(
QVideoFrame
&&
other
)
移动 other 到此 QVideoFrame .
赋值内容对于 other 到此视频帧。由于 QVideoFrame 是明确共享的，这 2 实例将反射相同帧。
返回
true
若此
QVideoFrame
and
other
反射相同帧。