The QVideoFrame class represents a frame of video data. More...

#include <qvideoframe.h>

Collaboration diagram for QVideoFrame:

Classes
struct	PaintOptions

Public Types
enum	HandleType { NoHandle , RhiTextureHandle }
	Identifies the type of a video buffers handle. More...
enum	MapMode { NotMapped = 0x00 , ReadOnly = 0x01 , WriteOnly = 0x02 , ReadWrite = ReadOnly \| WriteOnly }
	Enumerates how a video buffer's data is mapped to system memory. More...

Public Member Functions
	QVideoFrame ()
	Constructs a null video frame.
	QVideoFrame (const QVideoFrameFormat &format)
	Constructs a video frame of the given pixel format.
	QVideoFrame (const QImage &image)
	Constructs a QVideoFrame from a QImage.
	QVideoFrame (std::unique_ptr< QAbstractVideoBuffer > videoBuffer)
	Constructs a QVideoFrame from a \l QAbstractVideoBuffer.
	QVideoFrame (const QVideoFrame &other)
	Constructs a shallow copy of other.
	~QVideoFrame ()
	Destroys a video frame.
	QVideoFrame (QVideoFrame &&other) noexcept=default
	Constructs a QVideoFrame by moving from other.
void	swap (QVideoFrame &other) noexcept
	Swaps the current video frame with other.
QVideoFrame &	operator= (const QVideoFrame &other)
	Moves other into this QVideoFrame.
bool	operator== (const QVideoFrame &other) const
bool	operator!= (const QVideoFrame &other) const
bool	isValid () const
	Identifies whether a video frame is valid.
QVideoFrameFormat::PixelFormat	pixelFormat () const
	Returns the pixel format of this video frame.
QVideoFrameFormat	surfaceFormat () const
	Returns the surface format of this video frame.
QVideoFrame::HandleType	handleType () const
	Returns the type of a video frame's handle.
QSize	size () const
	Returns the dimensions of a video frame.
int	width () const
	Returns the width of a video frame.
int	height () const
	Returns the height of a video frame.
bool	isMapped () const
	Identifies if a video frame's contents are currently mapped to system memory.
bool	isReadable () const
	Identifies if the mapped contents of a video frame were read from the frame when it was mapped.
bool	isWritable () const
	Identifies if the mapped contents of a video frame will be persisted when the frame is unmapped.
QVideoFrame::MapMode	mapMode () const
	Returns the mode a video frame was mapped to system memory in.
bool	map (QVideoFrame::MapMode mode)
	Maps the contents of a video frame to system (CPU addressable) memory.
void	unmap ()
	Releases the memory mapped by the map() function.
int	bytesPerLine (int plane) const
	Returns the number of bytes in a scan line of a plane.
uchar *	bits (int plane)
	Returns a pointer to the start of the frame data buffer for a plane.
const uchar *	bits (int plane) const
	Returns a pointer to the start of the frame data buffer for a plane.
int	mappedBytes (int plane) const
	Returns the number of bytes occupied by plane plane of the mapped frame data.
int	planeCount () const
	Returns the number of planes in the video frame.
qint64	startTime () const
	Returns the presentation time (in microseconds) when the frame should be displayed.
void	setStartTime (qint64 time)
	Sets the presentation time (in microseconds) when the frame should initially be displayed.
qint64	endTime () const
	Returns the presentation time (in microseconds) when a frame should stop being displayed.
void	setEndTime (qint64 time)
	Sets the presentation time (in microseconds) when a frame should stop being displayed.
void	setRotation (QtVideo::Rotation angle)
	Sets the angle the frame should be rotated clockwise before displaying.
QtVideo::Rotation	rotation () const
	Returns the angle the frame should be rotated clockwise before displaying.
void	setMirrored (bool)
	Sets whether the frame should be mirrored around its vertical axis before displaying.
bool	mirrored () const
	Returns whether the frame should be mirrored around its vertical axis before displaying.
void	setStreamFrameRate (qreal rate)
	Sets the frame rate of a video stream in frames per second.
qreal	streamFrameRate () const
	Returns the frame rate of a video stream in frames per second.
QImage	toImage () const
	Converts current video frame to image.
QString	subtitleText () const
	Returns the subtitle text that should be rendered together with this video frame.
void	setSubtitleText (const QString &text)
	Sets the subtitle text that should be rendered together with this video frame to text.
void	paint (QPainter *painter, const QRectF &rect, const PaintOptions &options)
	Uses a QPainter, {painter}, to render this QVideoFrame to rect.

Friends
class	QVideoFramePrivate

Detailed Description

The QVideoFrame class represents a frame of video data.

\inmodule QtMultimedia

A QVideoFrame encapsulates the pixel data of a video frame, and information about the frame.

Video frames can come from several places - decoded \l {QMediaPlayer}{media}, a \l {QCamera}{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.

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

See also: QAbstractVideoBuffer, QVideoFrameFormat, QVideoFrame::MapMode

Definition at line 26 of file qvideoframe.h.

Member Enumeration Documentation

◆ HandleType

enum QVideoFrame::HandleType

Identifies the type of a video buffers handle.

\value NoHandle The buffer has no handle, its data can only be accessed by mapping the buffer. \value RhiTextureHandle 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: handleType()

Enumerator
NoHandle
RhiTextureHandle

Definition at line 31 of file qvideoframe.h.

◆ MapMode

enum QVideoFrame::MapMode

Enumerates how a video buffer's data is mapped to system memory.

\value NotMapped The video buffer is not mapped to memory. \value ReadOnly 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. \value WriteOnly The mapped memory is uninitialized when mapped, but the possibly modified content will be used to populate the video buffer when unmapped. \value ReadWrite 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: mapMode(), map()

Enumerator
NotMapped
ReadOnly
WriteOnly
ReadWrite

Definition at line 37 of file qvideoframe.h.

Constructor & Destructor Documentation

◆ QVideoFrame() [1/6]

QVideoFrame::QVideoFrame ( )

Constructs a null video frame.

Definition at line 83 of file qvideoframe.cpp.

◆ QVideoFrame() [2/6]

QVideoFrame::QVideoFrame ( const QVideoFrameFormat & format )

Constructs a video frame of the given pixel format.

Definition at line 114 of file qvideoframe.cpp.

◆ QVideoFrame() [3/6]

QVideoFrame::QVideoFrame ( const QImage & image )

explicit

Constructs a QVideoFrame from a QImage.

Since: 6.8

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 \l{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.

See also: QVideoFrameFormat::pixelFormatFromImageFormat(); QImage::convertedTo(); QImage::isNull()

Definition at line 153 of file qvideoframe.cpp.

◆ QVideoFrame() [4/6]

QVideoFrame::QVideoFrame ( std::unique_ptr< QAbstractVideoBuffer > videoBuffer )

explicit

Constructs a QVideoFrame from a \l QAbstractVideoBuffer.

Since: 6.8

The specified videoBuffer refers to an instance a reimplemented \l QAbstractVideoBuffer. The instance is expected to contain a preallocated custom video buffer and must implement \l QAbstractVideoBuffer::format, \l QAbstractVideoBuffer::map, and \l QAbstractVideoBuffer::unmap for GPU content.

If videoBuffer is null or gets an invalid \l 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 \l 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 \l setStreamFrameRate, \l setMirrored, or \l setRotation, the inner format can be modified, and \l surfaceFormat will return a detached instance.

See also: QAbstractVideoBuffer, QVideoFrameFormat

Definition at line 204 of file qvideoframe.cpp.

◆ QVideoFrame() [5/6]

QVideoFrame::QVideoFrame ( const QVideoFrame & other )

default

Constructs a shallow copy of other.

Since QVideoFrame is explicitly shared, these two instances will reflect the same frame.

◆ ~QVideoFrame()

QVideoFrame::~QVideoFrame ( )

default

Destroys a video frame.

◆ QVideoFrame() [6/6]

QVideoFrame::QVideoFrame ( QVideoFrame && other )

defaultnoexcept

Constructs a QVideoFrame by moving from other.

Member Function Documentation

◆ bits() [1/2]

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 \l {map()}{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(), planeCount()

Since: 5.4

Definition at line 629 of file qvideoframe.cpp.

◆ bits() [2/2]

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 \l {map()}{mapped}.

If the buffer was not mapped with read access, the contents of this buffer will initially be uninitialized.

See also: map(), mappedBytes(), bytesPerLine(), planeCount()

Since: 5.4

Definition at line 647 of file qvideoframe.cpp.

◆ bytesPerLine()

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 \l {map()}{mapped}.

See also: bits(), map(), mappedBytes(), planeCount()

Since: 5.4

Definition at line 610 of file qvideoframe.cpp.

◆ endTime()

qint64 QVideoFrame::endTime ( ) const

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

An invalid time is represented as -1.

Definition at line 714 of file qvideoframe.cpp.

◆ handleType()

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.

Definition at line 304 of file qvideoframe.cpp.

◆ height()

int QVideoFrame::height ( ) const

Returns the height of a video frame.

Definition at line 328 of file qvideoframe.cpp.

◆ isMapped()

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 \l {QVideoFrame::MapMode}{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(), QVideoFrame::MapMode

Definition at line 345 of file qvideoframe.cpp.

◆ isReadable()

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 \l {QVideoFrame::MapMode}{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(), QVideoFrame::MapMode

Definition at line 380 of file qvideoframe.cpp.

◆ isValid()

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.

Definition at line 277 of file qvideoframe.cpp.

◆ isWritable()

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 \l {QVideoFrame::MapMode}{MapMode} contains the QVideoFrame::WriteOnly flag.

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

Note: 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: mapMode(), QVideoFrame::MapMode

Definition at line 364 of file qvideoframe.cpp.

◆ map()

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.

Note: 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: unmap(), mapMode(), bits()

Definition at line 446 of file qvideoframe.cpp.

◆ mapMode()

QVideoFrame::MapMode QVideoFrame::mapMode ( ) const

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

See also: map(), QVideoFrame::MapMode

Definition at line 411 of file qvideoframe.cpp.

◆ mappedBytes()

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 \l {map()}{mapped}.

See also: map()

Definition at line 661 of file qvideoframe.cpp.

◆ mirrored()

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 \l QVideoFrameFormat. Mirroring is applied after rotation.

Mirroring is typically needed for video frames coming from a front camera of a mobile device.

Definition at line 822 of file qvideoframe.cpp.

◆ operator!=()

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

Returns: true if this QVideoFrame and other do not reflect the same frame.

Definition at line 260 of file qvideoframe.cpp.

◆ operator=()

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

default

Moves other into this QVideoFrame.

Assigns the contents of other to this video frame.

Since QVideoFrame is explicitly shared, these two instances will reflect the same frame.

◆ operator==()

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

Returns: true if this QVideoFrame and other reflect the same frame.

Definition at line 251 of file qvideoframe.cpp.

◆ paint()

void QVideoFrame::paint	(	QPainter *	painter,
		const QRectF &	rect,
		const 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.

Note: that rendering will usually happen without hardware acceleration when using this method.

Definition at line 893 of file qvideoframe.cpp.

◆ pixelFormat()

QVideoFrameFormat::PixelFormat QVideoFrame::pixelFormat ( ) const

Returns the pixel format of this video frame.

Definition at line 285 of file qvideoframe.cpp.

◆ planeCount()

int QVideoFrame::planeCount ( ) const

Returns the number of planes in the video frame.

See also: map()

Since: 5.4

Definition at line 675 of file qvideoframe.cpp.

◆ rotation()

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 \l QVideoFrameFormat. Rotation is applied before mirroring.

Definition at line 789 of file qvideoframe.cpp.

◆ setEndTime()

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.

Definition at line 727 of file qvideoframe.cpp.

◆ setMirrored()

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

Definition at line 806 of file qvideoframe.cpp.

◆ setRotation()

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 \l QVideoFrameFormat. Rotation is applied before mirroring.

Default value is QtVideo::Rotation::None.

Definition at line 775 of file qvideoframe.cpp.

◆ setStartTime()

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.

Definition at line 701 of file qvideoframe.cpp.

◆ setStreamFrameRate()

void QVideoFrame::setStreamFrameRate ( qreal rate )

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

Definition at line 830 of file qvideoframe.cpp.

◆ setSubtitleText()

void QVideoFrame::setSubtitleText ( const QString & text )

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

Definition at line 878 of file qvideoframe.cpp.

◆ size()

QSize QVideoFrame::size ( ) const

Returns the dimensions of a video frame.

Definition at line 312 of file qvideoframe.cpp.

◆ startTime()

qint64 QVideoFrame::startTime ( ) const

Returns the presentation time (in microseconds) when the frame should be displayed.

An invalid time is represented as -1.

Definition at line 688 of file qvideoframe.cpp.

◆ streamFrameRate()

qreal QVideoFrame::streamFrameRate ( ) const

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

Definition at line 839 of file qvideoframe.cpp.

◆ subtitleText()

QString QVideoFrame::subtitleText ( ) const

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

Definition at line 870 of file qvideoframe.cpp.

◆ surfaceFormat()

QVideoFrameFormat QVideoFrame::surfaceFormat ( ) const

Returns the surface format of this video frame.

Definition at line 293 of file qvideoframe.cpp.

◆ swap()

void QVideoFrame::swap ( QVideoFrame & other )

inlinenoexcept

Swaps the current video frame with other.

Definition at line 65 of file qvideoframe.h.

◆ toImage()

QImage QVideoFrame::toImage ( ) const

Converts current video frame to image.

The conversion is based on the current pixel data and the \l {QVideoFrame::surfaceFormat}{surface format}. Transformations of the frame don't impact the result since they are applied for presentation only.

Since: 5.15

Definition at line 854 of file qvideoframe.cpp.

◆ unmap()

void QVideoFrame::unmap ( )

Releases the memory mapped by the map() function.

If the \l {QVideoFrame::MapMode}{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()

Definition at line 580 of file qvideoframe.cpp.

◆ width()

int QVideoFrame::width ( ) const

Returns the width of a video frame.

Definition at line 320 of file qvideoframe.cpp.

◆ QVideoFramePrivate

friend class QVideoFramePrivate

friend

Definition at line 148 of file qvideoframe.h.

The documentation for this class was generated from the following files:

qtmultimedia/src/multimedia/video/qvideoframe.h (f9ad0153f8cbe01eb986c6bb0c307ee10807ff94)
qtmultimedia/src/multimedia/video/qvideoframe.cpp (b3a89f7196dd054118e16786e5a88dd83e61c25a)

Classes

Public Types

Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ HandleType

◆ MapMode

Constructor & Destructor Documentation

◆ QVideoFrame() [1/6]

◆ QVideoFrame() [2/6]

◆ QVideoFrame() [3/6]

◆ QVideoFrame() [4/6]

◆ QVideoFrame() [5/6]

◆ ~QVideoFrame()

◆ QVideoFrame() [6/6]

Member Function Documentation

◆ bits() [1/2]

◆ bits() [2/2]

◆ bytesPerLine()

◆ endTime()

◆ handleType()

◆ height()

◆ isMapped()

◆ isReadable()

◆ isValid()

◆ isWritable()

◆ map()

◆ mapMode()

◆ mappedBytes()

◆ mirrored()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ paint()

◆ pixelFormat()

◆ planeCount()

◆ rotation()

◆ setEndTime()

◆ setMirrored()

◆ setRotation()

◆ setStartTime()

◆ setStreamFrameRate()

◆ setSubtitleText()

◆ size()

◆ startTime()

◆ streamFrameRate()

◆ subtitleText()

◆ surfaceFormat()

◆ swap()

◆ toImage()

◆ unmap()

◆ width()

Friends And Related Symbol Documentation

◆ QVideoFramePrivate