CopperSpice API  1.7.2
QVideoFrame Class Reference

The QVideoFrame class provides a representation of a frame of video data. More...

Public Types

enum  FieldType
 
enum  PixelFormat
 

Public Methods

 QVideoFrame ()
 
 QVideoFrame (const QImage &image)
 
 QVideoFrame (const QVideoFrame &other)
 
 QVideoFrame (int bytes, const QSize &size, int bytesPerLine, PixelFormat format)
 
 QVideoFrame (QAbstractVideoBuffer *buffer, const QSize &size, PixelFormat format)
 
 ~QVideoFrame ()
 
QVariantMap availableMetaData () const
 
ucharbits ()
 
const ucharbits () const
 
ucharbits (int plane)
 
const ucharbits (int plane) const
 
int bytesPerLine () const
 
int bytesPerLine (int plane) const
 
qint64 endTime () const
 
FieldType fieldType () const
 
QVariant handle () const
 
QAbstractVideoBuffer::HandleType handleType () const
 
int height () const
 
bool isMapped () const
 
bool isReadable () const
 
bool isValid () const
 
bool isWritable () const
 
bool map (QAbstractVideoBuffer::MapMode mode)
 
QAbstractVideoBuffer::MapMode mapMode () const
 
int mappedBytes () const
 
QVariant metaData (const QString &key) const
 
bool operator!= (const QVideoFrame &other) const
 
QVideoFrame & operator= (const QVideoFrame &other)
 
bool operator== (const QVideoFrame &other) const
 
PixelFormat pixelFormat () const
 
int planeCount () const
 
void setEndTime (qint64 time)
 
void setFieldType (FieldType)
 
void setMetaData (const QString &key, const QVariant &value)
 
void setStartTime (qint64 time)
 
QSize size () const
 
qint64 startTime () const
 
void unmap ()
 
int width () const
 

Static Public Methods

static QImage::Format imageFormatFromPixelFormat (PixelFormat format)
 
static PixelFormat pixelFormatFromImageFormat (QImage::Format format)
 

Detailed Description

The QVideoFrame class provides a representation of a frame of video data.

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

The contents of a video frame can be mapped to memory using the map() function. While mapped the video data can accessed using the bits() function which returns a pointer to a buffer, the total size of which is given by the mappedBytes(), and the size of each line is given by bytesPerLine(). The return value of the handle() function may be used to access frame data using the internal buffer's native APIs.

The video data in a QVideoFrame is encapsulated in a QAbstractVideoBuffer. A QVideoFrame may be constructed from any buffer type by subclassing the QAbstractVideoBuffer class.

Note
QVideoFrame is explicitly shared, any change made to video frame will also apply to any copies.
See also
pixelFormatFromImageFormat()

Member Enumeration Documentation

Specifies the field an interlaced video frame belongs to.

ConstantValueDescription
QVideoFrame::ProgressiveFrame0The frame is not interlaced.
QVideoFrame::TopField1The frame contains a top field.
QVideoFrame::BottomField2The frame contains a bottom field.
QVideoFrame::InterlacedFrame3The frame contains a merged top and bottom field.

Enumerates video data types.

ConstantValueDescription
QVideoFrame::Format_Invalid0 The frame is invalid.
QVideoFrame::Format_ARGB321 The frame is stored using a 32-bit ARGB format (0xAARRGGBB). Equivalent to QImage::Format_ARGB32.
QVideoFrame::Format_ARGB32_Premultiplied2 The frame stored using a premultiplied 32-bit ARGB format (0xAARRGGBB). Equivalent to QImage::Format_ARGB32_Premultiplied.
QVideoFrame::Format_RGB323 The frame stored using a 32-bit RGB format (0xffRRGGBB). Equivalent to QImage::Format_RGB32
QVideoFrame::Format_RGB244 The frame is stored using a 24-bit RGB format (8-8-8). Equivalent to QImage::Format_RGB888
QVideoFrame::Format_RGB5655 The frame is stored using a 16-bit RGB format (5-6-5). Equivalent to QImage::Format_RGB16.
QVideoFrame::Format_RGB5556 The frame is stored using a 16-bit RGB format (5-5-5). Equivalent to QImage::Format_RGB555.
QVideoFrame::Format_ARGB8565_Premultiplied7 The frame is stored using a 24-bit premultiplied ARGB format (8-6-6-5).
QVideoFrame::Format_BGRA328 The frame is stored using a 32-bit ARGB format (0xBBGGRRAA).
QVideoFrame::Format_BGRA32_Premultiplied9 The frame is stored using a premultiplied 32bit BGRA format.
QVideoFrame::Format_BGR3210 The frame is stored using a 32-bit BGR format (0xBBGGRRff).
QVideoFrame::Format_BGR2411 The frame is stored using a 24-bit BGR format (0xBBGGRR).
QVideoFrame::Format_BGR56512 The frame is stored using a 16-bit BGR format (5-6-5).
QVideoFrame::Format_BGR55513 The frame is stored using a 16-bit BGR format (5-5-5).
QVideoFrame::Format_BGRA5658_Premultiplied14The frame is stored using a 24-bit premultiplied BGRA format (5-6-5-8).
QVideoFrame::Format_AYUV44415 The frame is stored using a packed 32-bit AYUV format (0xAAYYUUVV).
QVideoFrame::Format_AYUV444_Premultiplied 16The frame is stored using a packed premultiplied 32-bit AYUV format (0xAAYYUUVV).
QVideoFrame::Format_YUV44417 The frame is stored using a 24-bit packed YUV format (8-8-8).
QVideoFrame::Format_YUV420P18 The frame is stored using an 8-bit per component planar YUV format with the U and V planes horizontally and vertically sub-sampled, i.e. the height and width of the U and V planes are half that of the Y plane.
QVideoFrame::Format_YV1219 The frame is stored using an 8-bit per component planar YVU format with the V and U planes horizontally and vertically sub-sampled, i.e. the height and width of the V and U planes are half that of the Y plane.
QVideoFrame::Format_UYVY20 The frame is stored using an 8-bit per component packed YUV format with the U and V planes horizontally sub-sampled (U-Y-V-Y), i.e. two horizontally adjacent pixels are stored as a 32-bit macropixel which has a Y value for each pixel and common U and V values.
QVideoFrame::Format_YUYV21 The frame is stored using an 8-bit per component packed YUV format with the U and V planes horizontally sub-sampled (Y-U-Y-V), i.e. two horizontally adjacent pixels are stored as a 32-bit macropixel which has a Y value for each pixel and common U and V values.
QVideoFrame::Format_NV1222 The frame is stored using an 8-bit per component semi-planar YUV format with a Y plane (Y) followed by a horizontally and vertically sub-sampled, packed UV plane (U-V).
QVideoFrame::Format_NV2123 The frame is stored using an 8-bit per component semi-planar YUV format with a Y plane (Y) followed by a horizontally and vertically sub-sampled, packed VU plane (V-U).
QVideoFrame::Format_IMC124 The frame is stored using an 8-bit per component planar YUV format with the U and V planes horizontally and vertically sub-sampled. This is similar to the Format_YUV420P type, except that the bytes per line of the U and V planes are padded out to the same stride as the Y plane.
QVideoFrame::Format_IMC225 The frame is stored using an 8-bit per component planar YUV format with the U and V planes horizontally and vertically sub-sampled. This is similar to the Format_YUV420P type, except that the lines of the U and V planes are interleaved, i.e. each line of U data is followed by a line of V data creating a single line of the same stride as the Y data.
QVideoFrame::Format_IMC326 The frame is stored using an 8-bit per component planar YVU format with the V and U planes horizontally and vertically sub-sampled. This is similar to the Format_YV12 type, except that the bytes per line of the V and U planes are padded out to the same stride as the Y plane.
QVideoFrame::Format_IMC427 The frame is stored using an 8-bit per component planar YVU format with the V and U planes horizontally and vertically sub-sampled. This is similar to the Format_YV12 type, except that the lines of the V and U planes are interleaved, i.e. each line of V data is followed by a line of U data creating a single line of the same stride as the Y data.
QVideoFrame::Format_Y828 The frame is stored using an 8-bit greyscale format.
QVideoFrame::Format_Y1629 The frame is stored using a 16-bit linear greyscale format. Little endian.
QVideoFrame::Format_User1000 Start value for user defined pixel formats.

Constructor & Destructor Documentation

QVideoFrame::QVideoFrame ( )

Constructs a null video frame.

QVideoFrame::QVideoFrame ( QAbstractVideoBuffer buffer,
const QSize size,
PixelFormat  format 
)

Constructs a video frame from a buffer of the given pixel format and size in pixels.

Note
This does not increment the reference count of the video buffer.
QVideoFrame::QVideoFrame ( int  bytes,
const QSize size,
int  bytesPerLine,
PixelFormat  format 
)

Constructs a video frame of the given pixel format and size in pixels.

The bytesPerLine (stride) is the length of each scan line in bytes, and bytes is the total number of bytes that must be allocated for the frame.

QVideoFrame::QVideoFrame ( const QImage image)

Constructs a video frame from an image.

Note
This will construct an invalid video frame if there is no frame type equivalent to the image format.
See also
pixelFormatFromImageFormat()
QVideoFrame::QVideoFrame ( const QVideoFrame &  other)

Constructs a copy of other.

QVideoFrame::~QVideoFrame ( )

Destroys a video frame.

Method Documentation

QVariantMap QVideoFrame::availableMetaData ( ) const

Returns any extra metadata associated with this frame.

uchar * QVideoFrame::bits ( )

Returns a pointer to the start of the frame data buffer. This value is only valid while the frame data is mapped.

See also
map(), mappedBytes(), bytesPerLine()
const uchar * QVideoFrame::bits ( ) const

Returns a const pointer to the start of the frame data buffer. This value is only valid while the frame data is mapped.

See also
map(), mappedBytes(), bytesPerLine()
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.

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

See also
map(), mappedBytes(), bytesPerLine(), planeCount()
const uchar * QVideoFrame::bits ( int  plane) const

Returns a const 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(), planeCount()
int QVideoFrame::bytesPerLine ( ) const

Returns the number of bytes in a scan line. This value is only valid while the frame data is mapped.

Note
This is the bytes per line of the first plane only. The bytes per line of subsequent planes should be calculated as per the frame type.
See also
bits(), map(), mappedBytes()
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(), planeCount()
qint64 QVideoFrame::endTime ( ) const

Returns the presentation time when a frame should stop being displayed.

See also
setEndTime()
FieldType QVideoFrame::fieldType ( ) const

Returns the field an interlaced video frame belongs to. If the video is not interlaced this will return WholeFrame.

See also
setFieldType()
QVariant QVideoFrame::handle ( ) const

Returns a type specific handle to a video frame's buffer. For an OpenGL texture this would be the texture ID.

See also
QAbstractVideoBuffer::handle()
QAbstractVideoBuffer::HandleType QVideoFrame::handleType ( ) const

Returns the type of a video frame's handle.

int QVideoFrame::height ( ) const

Returns the height of a video frame.

QImage::Format QVideoFrame::imageFormatFromPixelFormat ( PixelFormat  format)
static

Returns an image format equivalent to a video frame pixel format. If there is no equivalent format QImage::Format_Invalid is returned instead.

bool QVideoFrame::isMapped ( ) const

Identifies if a video frame's contents are currently mapped to system memory. Returns true if the contents of the video frame are mapped to system memory and false otherwise.

This is a convenience function which checks that the MapMode of the frame is not equal to QAbstractVideoBuffer::NotMapped.

See also
mapMode(), QAbstractVideoBuffer::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 QAbstractVideoBuffer::WriteOnly flag.

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

See also
mapMode(), QAbstractVideoBuffer::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 QAbstractVideoBuffer::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(), QAbstractVideoBuffer::MapMode
bool QVideoFrame::map ( QAbstractVideoBuffer::MapMode  mode)

Maps the contents of a video frame to memory.

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 QAbstractVideoBuffer::ReadOnly flag the mapped memory will be populated with the content of the video frame when mapped. If the map mode includes the QAbstractVideoBuffer::WriteOnly flag the content of the mapped memory will be persisted in 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.

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

See also
unmap(), mapMode(), bits()
QAbstractVideoBuffer::MapMode QVideoFrame::mapMode ( ) const

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

See also
map(), QAbstractVideoBuffer::MapMode
int QVideoFrame::mappedBytes ( ) const

Returns the number of bytes occupied by the mapped frame data.

This value is only valid while the frame data is mapped.

See also
map()
QVariant QVideoFrame::metaData ( const QString key) const

Returns any metadata for this frame for the given key. This might include frame specific information from a camera, or subtitles from a decoded video stream.

Refer to the documentation for the relevant video frame producer for further information about available metadata.

See also
setMetaData()
bool QVideoFrame::operator!= ( const QVideoFrame &  other) const

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

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

Assigns the contents of other to a video frame.

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

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

PixelFormat QVideoFrame::pixelFormat ( ) const

Returns the color format of a video frame.

PixelFormat QVideoFrame::pixelFormatFromImageFormat ( QImage::Format  format)
static

Returns an video pixel format equivalent to an image format. If there is no equivalent format QVideoFrame::InvalidType is returned instead.

int QVideoFrame::planeCount ( ) const

Returns the number of planes in the video frame. This value is only valid while the frame data is mapped.

See also
map()
void QVideoFrame::setEndTime ( qint64  time)

Sets the presentation time when a frame should stop being displayed.

See also
endTime()
void QVideoFrame::setFieldType ( FieldType  field)

Sets the field an interlaced video frame belongs to.

See also
fieldType()
void QVideoFrame::setMetaData ( const QString key,
const QVariant value 
)

Sets the metadata for the given key to value. If value is a null variant, any metadata for this key will be removed.

The producer of the video frame might use this to associate certain data with this frame, or for an intermediate processor to add information for a consumer of this frame.

See also
metaData()
void QVideoFrame::setStartTime ( qint64  time)

Sets the presentation time when the frame should be displayed.

See also
startTime()
QSize QVideoFrame::size ( ) const

Returns the size of a video frame.

qint64 QVideoFrame::startTime ( ) const

Returns the presentation time when the frame should be displayed.

See also
setStartTime()
void QVideoFrame::unmap ( )

Releases the memory mapped by the map() function.

If the MapMode included the QAbstractVideoBuffer::WriteOnly flag this will persist the current content of the mapped memory to the video frame.

See also
map()
int QVideoFrame::width ( ) const

Returns the width of a video frame.