QVideoFrame Class▲
-
Header: QVideoFrame
-
CMake:
find_package(Qt6 REQUIRED COMPONENTS Multimedia)
target_link_libraries(mytarget PRIVATE Qt6::Multimedia)
-
qmake: QT += multimedia
-
Group: QVideoFrame is part of multimedia, multimedia_video
Detailed Description▲
A QVideoFrame encapsulates the pixel data of a video frame, and information about the frame.
Video frames can come from several places - decoded media, a 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.
Member Type Documentation▲
enum QVideoFrame::HandleType▲
Identifies the type of a video buffers handle.
|
Constant |
Value |
Description |
|---|---|---|
|
QVideoFrame::NoHandle |
0 |
The buffer has no handle, its data can only be accessed by mapping the buffer. |
|
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. |
See Also▲
See also handleType()
enum QVideoFrame::MapMode▲
Enumerates how a video buffer's data is mapped to system memory.
|
Constant |
Value |
Description |
|---|---|---|
|
QVideoFrame::NotMapped |
0x00 |
The video buffer is not mapped to memory. |
|
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. |
See Also▲
enum QVideoFrame::RotationAngle▲
The angle of the clockwise rotation that should be applied to a video frame before displaying.
|
Constant |
Value |
Description |
|---|---|---|
|
QVideoFrame::Rotation0 |
0 |
No rotation required, the frame has correct orientation |
|
QVideoFrame::Rotation90 |
90 |
The frame should be rotated by 90 degrees |
|
QVideoFrame::Rotation180 |
180 |
The frame should be rotated by 180 degrees |
|
QVideoFrame::Rotation270 |
270 |
The frame should be rotated by 270 degrees |
Member Function Documentation▲
QVideoFrame::QVideoFrame()▲
Constructs a null video frame.
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.
QVideoFrame::QVideoFrame(QVideoFrame &&other)▲
Constructs a QVideoFrame by moving from other.
QVideoFrame::~QVideoFrame()▲
Destroys a video frame.
uchar *QVideoFrame::bits(int plane)▲
Returns a pointer to the start of the frame data buffer for a plane.
This value is only valid while the frame data is mapped.
Changes made to data accessed via this pointer (when mapped with write access) are only guaranteed to have been persisted when unmap() is called and when the buffer has been mapped for writing.
See Also▲
See also map(), mappedBytes(), bytesPerLine(), planeCount()
const uchar *QVideoFrame::bits(int plane) const▲
Returns a pointer to the start of the frame data buffer for a plane.
This value is only valid while the frame data is mapped.
If the buffer was not mapped with read access, the contents of this buffer will initially be uninitialized.
See Also▲
See also map(), mappedBytes(), bytesPerLine(), planeCount()
int QVideoFrame::bytesPerLine(int plane) const▲
Returns the number of bytes in a scan line of a plane.
This value is only valid while the frame data is mapped.
See Also▲
See also bits(), map(), mappedBytes(), planeCount()
qint64 QVideoFrame::endTime() const▲
Returns the presentation time (in microseconds) when a frame should stop being displayed.
An invalid time is represented as -1.
See Also▲
See also setEndTime()
QVideoFrame::HandleType QVideoFrame::handleType() const▲
Returns the type of a video frame's handle.
The handle type could either be NoHandle, meaning that the frame is memory based, or a RHI texture.
int QVideoFrame::height() const▲
Returns the height of a video frame.
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.
See Also▲
See also 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.
This is a convenience function which checks if the MapMode contains the QVideoFrame::WriteOnly flag.
Returns true if the contents of the mapped memory were read from the video frame, and false otherwise.
See Also▲
See also mapMode(), QVideoFrame::MapMode
bool QVideoFrame::isValid() const▲
Identifies whether a video frame is valid.
An invalid frame has no video buffer associated with it.
Returns true if the frame is valid, and false if it is not.
bool QVideoFrame::isWritable() const▲
Identifies if the mapped contents of a video frame will be persisted when the frame is unmapped.
This is a convenience function which checks if the MapMode contains the QVideoFrame::WriteOnly flag.
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.
See Also▲
See also mapMode(), QVideoFrame::MapMode
bool QVideoFrame::map(QVideoFrame::MapMode mode)▲
Maps the contents of a video frame to system (CPU addressable) memory.
In some cases the video frame data might be stored in video memory or otherwise inaccessible memory, so it is necessary to map a frame before accessing the pixel data. This may involve copying the contents around, so avoid mapping and unmapping unless required.
The map mode indicates whether the contents of the mapped memory should be read from and/or written to the frame. If the map mode includes the QVideoFrame::ReadOnly flag the mapped memory will be populated with the content of the video frame when initially mapped. If the map mode includes the QVideoFrame::WriteOnly flag the content of the possibly modified mapped memory will be written back to the frame when unmapped.
While mapped the contents of a video frame can be accessed directly through the pointer returned by the bits() function.
When access to the data is no longer needed, be sure to call the unmap() function to release the mapped memory and possibly update the video frame contents.
If the video frame has been mapped in read only mode, it is permissible to map it multiple times in read only mode (and unmap it a corresponding number of times). In all other cases it is necessary to unmap the frame first before mapping a second time.
Writing to memory that is mapped as read-only is undefined, and may result in changes to shared data or crashes.
Returns true if the frame was mapped to memory in the given mode and false otherwise.
See Also▲
QVideoFrame::MapMode QVideoFrame::mapMode() const▲
Returns the mode a video frame was mapped to system memory in.
See Also▲
See also map(), QVideoFrame::MapMode
int QVideoFrame::mappedBytes(int plane) const▲
Returns the number of bytes occupied by plane plane of the mapped frame data.
This value is only valid while the frame data is mapped.
See Also▲
See also map()
bool QVideoFrame::mirrored() const▲
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▲
QVideoFrame::RotationAngle QVideoFrame::rotationAngle() const▲
Returns the angle the frame should be rotated clockwise before displaying.
See Also▲
See also setRotationAngle()
void QVideoFrame::setEndTime(qint64 time)▲
Sets the presentation time (in microseconds) when a frame should stop being displayed.
An invalid time is represented as -1.
See Also▲
See also endTime()
void QVideoFrame::setMirrored(bool mirrored)▲
void QVideoFrame::setRotationAngle(QVideoFrame::RotationAngle angle)▲
Sets the angle the frame should be rotated clockwise before displaying.
See Also▲
See also rotationAngle()
void QVideoFrame::setStartTime(qint64 time)▲
Sets the presentation time (in microseconds) when the frame should initially be displayed.
An invalid time is represented as -1.
See Also▲
See also startTime()
void QVideoFrame::setSubtitleText(const QString &text)▲
Sets the subtitle text that should be rendered together with this video frame to text.
See Also▲
See also subtitleText()
QSize QVideoFrame::size() const▲
Returns the dimensions of a video frame.
qint64 QVideoFrame::startTime() const▲
Returns the presentation time (in microseconds) when the frame should be displayed.
An invalid time is represented as -1.
See Also▲
See also setStartTime()
QString QVideoFrame::subtitleText() const▲
Returns the subtitle text that should be rendered together with this video frame.
See Also▲
See also setSubtitleText()
QVideoFrameFormat QVideoFrame::surfaceFormat() const▲
Returns the surface format of this video frame.
void QVideoFrame::swap(QVideoFrame &other)▲
Swaps the current video frame with other.
QImage QVideoFrame::toImage() const▲
Based on the pixel format converts current video frame to image.
void QVideoFrame::unmap()▲
Releases the memory mapped by the map() function.
If the MapMode included the QVideoFrame::WriteOnly flag this will persist the current content of the mapped memory to the video frame.
unmap() should not be called if map() function failed.
See Also▲
See also map()
int QVideoFrame::width() const▲
Returns the width of a video frame.
bool QVideoFrame::operator!=(const QVideoFrame &other) const▲
Returns true if this QVideoFrame and other do not reflect the same frame.
QVideoFrame &QVideoFrame::operator=(QVideoFrame &&other)▲
Moves other into this 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▲
Returns true if this QVideoFrame and other reflect the same frame.