QVideoFrame Class

Member Function Documentation

QVideoFrame::QVideoFrame()

Constructs a null video frame.

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

Constructs a QVideoFrame from a QImage.

If the 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() with the Qt::AutoColor flag. This may incur a performance penalty.

If QImage::isNull() evaluates to true for the input QImage, the QVideoFrame will be invalid and QVideoFrameFormat::isValid() will return false.

This function was introduced in Qt 6.8.

See also QVideoFrameFormat::pixelFormatFromImageFormat(), QImage::convertedTo(), and QImage::isNull().

QVideoFrame::QVideoFrame(const QVideoFrameFormat &format)

Constructs a video frame of the given pixel format.

[explicit, since 6.8] QVideoFrame::QVideoFrame(std::unique_ptr<QAbstractVideoBuffer> videoBuffer)

Constructs a QVideoFrame from a QAbstractVideoBuffer.

The specified 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, and QAbstractVideoBuffer::unmap for GPU content.

If 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, or setRotation, the inner format can be modified, and surfaceFormat will return a detached instance.

This function was introduced in Qt 6.8.

See also QAbstractVideoBuffer and QVideoFrameFormat.

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()

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 map(), mappedBytes(), bytesPerLine(), and 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 map(), mappedBytes(), bytesPerLine(), and 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 bits(), map(), mappedBytes(), and 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 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 mapMode() and 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 mapMode() and 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.

See also mapMode() and 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.

Returns true if the frame was mapped to memory in the given mode and false otherwise.

See also unmap(), mapMode(), and bits().

QVideoFrame::MapMode QVideoFrame::mapMode() const

Returns the mode a video frame was mapped to system memory in.

See also map() and 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 map().

bool QVideoFrame::mirrored() const

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.

See also 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.

QVideoFrameFormat::PixelFormat QVideoFrame::pixelFormat() const

Returns the pixel format of this video frame.

int QVideoFrame::planeCount() const

Returns the number of planes in the video frame.

See also map().

QtVideo::Rotation QVideoFrame::rotation() const

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.

See also setRotation().

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 endTime().

void QVideoFrame::setMirrored(bool mirrored)

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.

See also mirrored().

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

Sets 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.

Default value is QtVideo::Rotation::None.

See also rotation().

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 startTime().

void QVideoFrame::setStreamFrameRate(qreal rate)

Sets the frame rate of a video stream in frames per second.

See also streamFrameRate().

void QVideoFrame::setSubtitleText(const QString &text)

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

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 setStartTime().

qreal QVideoFrame::streamFrameRate() const

Returns the frame rate of a video stream in frames per second.

See also setStreamFrameRate().

QString QVideoFrame::subtitleText() const

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

See also 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

Converts current video frame to image.

The consversion is based on the current pixel data and the QVideoFrame::surfaceFormat. Transformations of the frame don't impact the result since they are applied for presentation only.

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 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.

[noexcept] 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.