class QVideoFrame¶

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

Synopsis¶

Methods¶

def __init__()
def bytesPerLine()
def endTime()
def handleType()
def height()
def isMapped()
def isReadable()
def isValid()
def isWritable()
def map()
def mapMode()
def mappedBytes()
def mirrored()
def __ne__()
def __eq__()
def paint()
def pixelFormat()
def planeCount()
def rotation()
def rotationAngle()
def setEndTime()
def setMirrored()
def setRotation()
def setRotationAngle()
def setStartTime()
def setStreamFrameRate()
def setSubtitleText()
def size()
def startTime()
def streamFrameRate()
def subtitleText()
def surfaceFormat()
def swap()
def toImage()
def unmap()
def videoBuffer()
def width()

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

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.

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.

class HandleType¶

Identifies the type of a video buffers handle.

Constant

Description

QVideoFrame.NoHandle

The buffer has no handle, its data can only be accessed by mapping the buffer.

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

Constant	Description
QVideoFrame.NoHandle	The buffer has no handle, its data can only be accessed by mapping the buffer.
QVideoFrame.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.

class MapMode¶

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

Constant

Description

QVideoFrame.NotMapped

The video buffer is not mapped to memory.

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

QVideoFrame.WriteOnly

The mapped memory is uninitialized when mapped, but the possibly modified content will be used to populate the video buffer when unmapped.

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

Constant	Description
QVideoFrame.NotMapped	The video buffer is not mapped to memory.
QVideoFrame.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.
QVideoFrame.WriteOnly	The mapped memory is uninitialized when mapped, but the possibly modified content will be used to populate the video buffer when unmapped.
QVideoFrame.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.

Added in version 6.1.

class RotationAngle¶

Use Rotation instead.

The angle of the clockwise rotation that should be applied to a video frame before displaying.

Constant

Description

QVideoFrame.Rotation0

No rotation required, the frame has correct orientation

QVideoFrame.Rotation90

The frame should be rotated by 90 degrees

QVideoFrame.Rotation180

The frame should be rotated by 180 degrees

QVideoFrame.Rotation270

The frame should be rotated by 270 degrees

Constant	Description
QVideoFrame.Rotation0	No rotation required, the frame has correct orientation
QVideoFrame.Rotation90	The frame should be rotated by 90 degrees
QVideoFrame.Rotation180	The frame should be rotated by 180 degrees
QVideoFrame.Rotation270	The frame should be rotated by 270 degrees

Added in version 6.2.3.

__init__()¶

Constructs a null video frame.

__init__(image)

Parameters:: image – QImage

Constructs a QVideoFrame from a QImage.

If the QImage::Format matches one of the formats in 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 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 isValid() will return false.

See also

pixelFormatFromImageFormat() isNull()

__init__(other)

Parameters:: other – QVideoFrame

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

__init__(format)

Parameters:: format – QVideoFrameFormat

Constructs a video frame of the given pixel format.

__init__(buffer, format)

Parameters:

buffer – QAbstractVideoBuffer
format – QVideoFrameFormat

Note

This function is deprecated.

bytesPerLine(plane)¶

Parameters:: plane – int
Return type:: int

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

endTime()¶

Return type:: int

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

An invalid time is represented as -1.

See also

setEndTime()

handleType()¶

Return type:: HandleType

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.

height()¶

Return type:: int

Returns the height of a video frame.

isMapped()¶

Return type:: bool

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

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

See also

mapMode() MapMode

isReadable()¶

Return type:: bool

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

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

See also

mapMode() MapMode

isValid()¶

Return type:: bool

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.

isWritable()¶

Return type:: bool

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