A video frame. More...

#include "vdo-map.h"
#include "vdo-types.h"
#include <unistd.h>
#include <glib-object.h>

Include dependency graph for vdo-frame.h:

This graph shows which files directly or indirectly include this file:

Functions
VdoFrameType	vdo_frame_get_frame_type (VdoFrame *self)
	Return the type of this frame. More...

gboolean	vdo_frame_is_key (VdoFrame *self)
	Determine whether the frame is a keyframe. More...

gboolean	vdo_frame_shown (VdoFrame *self)
	Return whether this frame is shown. More...

guint	vdo_frame_get_sequence_nbr (VdoFrame *self)
	Return the sequence number of this frame. More...

guint64	vdo_frame_get_timestamp (VdoFrame *self)
	Return the capture timestamp of this frame. More...

guint64	vdo_frame_get_utc_timestamp (VdoFrame *self)
	Return the capture utc timestamp of this frame. More...

gint64	vdo_frame_get_custom_timestamp (VdoFrame *self)
	Return a custom timestamp for this frame. More...

gsize	vdo_frame_get_size (VdoFrame *self)
	Return the size of this frame. More...

gssize	vdo_frame_get_header_size (VdoFrame *self)
	Return the size of any H264/H265/AV1 headers contained in this frame. More...

VdoMap *	vdo_frame_get_extra_info (VdoFrame *self)
	Return a file descriptor for this frame. More...

gboolean	vdo_frame_get_is_last_buffer (VdoFrame *self)
	Return a pointer to the opaque data of this frame. More...

void	vdo_frame_set_size (VdoFrame *self, gsize size)
	Set the size of this frame. More...

void	vdo_frame_set_frame_type (VdoFrame *self, VdoFrameType type)
	Set the type of this frame. More...

void	vdo_frame_set_sequence_nbr (VdoFrame *self, guint seqnum)
	Set the sequence number of this frame. More...

void	vdo_frame_set_timestamp (VdoFrame *self, guint64 timestamp)
	Set the timestamp of this frame. More...

void	vdo_frame_set_custom_timestamp (VdoFrame *self, gint64 timestamp)
	Return a custom timestamp of this frame. More...

void	vdo_frame_set_is_last_buffer (VdoFrame *self, gboolean is_last_buffer)
	Mark this frame as the last buffer. More...

void	vdo_frame_set_extra_info (VdoFrame self, VdoMap extra_info)
	Set the extra info of this frame. More...

void	vdo_frame_set_header_size (VdoFrame *self, gssize size)
	Set the header size of this frame, normally used for H26x frames. More...

gpointer	vdo_frame_memmap (VdoFrame *self)
	A convenience function that maps the frame into current process memory. More...

void	vdo_frame_unmap (VdoFrame *self)
	Unmaps the frame from current process memory. More...

VdoChunk	vdo_frame_take_chunk (VdoFrame self, GError *error)
	Iterate buffer contents by chunks (with mmap). More...

VdoChunk	vdo_frame_take_chunk_ex (VdoFrame self, VdoChunkOption options, GError *error)
	Iterate buffer contents by chunks (optional mmap) More...

Detailed Description

A video frame.

This class represents a video frame. It can be used to obtained frame metadata. A VdoFrame can be obtained from a VdoBuffer, via vdo_buffer_get_frame(). The data for a frame is usually obtained via vdo_buffer_get_data(), from the buffer containing the VdoFrame object.

Function Documentation

◆ vdo_frame_get_custom_timestamp()

gint64 vdo_frame_get_custom_timestamp ( VdoFrame * self )

Return a custom timestamp for this frame.

By default, this is equivalent to gettimeofday, with the key difference that the result is converted to a single µs counter. Please consult the operating system documentation for further details.

It is possible to chose different timestamp formats, see VdoStreamTimestamp.

g_autoptr(VdoMap) settings = vdo_map_new();
 
vdo_map_set_uint32(settings, "timestamp.type", VDO_TIMESTAMP_MONO_SERVER);
 
g_autoptr(VdoStream) stream = vdo_stream_new(settings, NULL, &error);
if (!stream)
  return;

Parameters

self	A VdoFrame.

Returns: The timestamp of this frame in µs.

◆ vdo_frame_get_extra_info()

VdoMap* vdo_frame_get_extra_info ( VdoFrame * self )

Return a file descriptor for this frame.

Deprecated:: Use vdo_buffer_get_fd

Parameters

self	A VdoFrame.

Returns: A unix file descriptor referring to the content of this frame.

Return the extra info of this frame.

Parameters

self	A VdoFrame.

Returns: The extra info of this frame as VdoMap.

◆ vdo_frame_get_frame_type()

VdoFrameType vdo_frame_get_frame_type ( VdoFrame * self )

Return the type of this frame.

For H.26x the following VdoFrameType are in use:

VDO_FRAME_TYPE_H264_IDR, VDO_FRAME_TYPE_H264_P, VDO_FRAME_TYPE_H264_B.
VDO_FRAME_TYPE_H265_IDR, VDO_FRAME_TYPE_H265_P, VDO_FRAME_TYPE_H265_B.

Parameters

self	A VdoFrame.

Returns: The type of this frame as VdoFrameType.

◆ vdo_frame_get_header_size()

gssize vdo_frame_get_header_size ( VdoFrame * self )

Return the size of any H264/H265/AV1 headers contained in this frame.

This can be used as an offset into the frame data buffer to get the frame data without headers.

Parameters

self	A VdoFrame.

Returns: The combined size of the H264/H265/AV1 headers, or -1 if the header size is unknown.

◆ vdo_frame_get_is_last_buffer()

gboolean vdo_frame_get_is_last_buffer ( VdoFrame * self )

Return a pointer to the opaque data of this frame.

Deprecated:: Use vdo_buffer_get_opaque

Parameters

self	A VdoFrame.

Returns: A pointer to the opaque data of this frame.

Check whether this frame is the last buffer.

Deprecated:: Prefer vdo_buffer_is_complete

Parameters

self	A VdoFrame.

Returns: TRUE if this frame is the last buffer, otherwise FALSE.

◆ vdo_frame_get_sequence_nbr()

guint vdo_frame_get_sequence_nbr ( VdoFrame * self )

Return the sequence number of this frame.

The returned sequence number is represented as an unsigned integer and starts at 0. The point where the sequence number counter wraps around is undefined.

Parameters

self	A VdoFrame.

Returns: The sequence number of this frame as a guint.

◆ vdo_frame_get_size()

gsize vdo_frame_get_size ( VdoFrame * self )

Return the size of this frame.

Parameters

self	A VdoFrame.

Returns: The size of this frame in bytes.

◆ vdo_frame_get_timestamp()

guint64 vdo_frame_get_timestamp ( VdoFrame * self )

Return the capture timestamp of this frame.

This is equivalent to clock_gettime with CLOCK_MONOTONIC, with the key difference that the result is converted to a single µs counter. Please consult the operating system documentation for further details.

Parameters

self	A VdoFrame.

Returns: The timestamp of this frame in µs.

Examples: vdo-example-blocking.cc, vdo-example-nv12.cc, vdo-example-rgb.cc, and vdo-example.cc.

◆ vdo_frame_get_utc_timestamp()

guint64 vdo_frame_get_utc_timestamp ( VdoFrame * self )

Return the capture utc timestamp of this frame.

This is equivalent to gettimeofday, with the key difference that the result is converted to a single µs counter. Please consult the operating system documentation for further details.

Parameters

self	A VdoFrame.

Returns: The timestamp of this frame in µs.

◆ vdo_frame_is_key()

gboolean vdo_frame_is_key ( VdoFrame * self )

Determine whether the frame is a keyframe.

For motion-encoded formats, such as H.26x and AV1, this function returns TRUE only for IDR / KEY frames. For simpler formats like JPEG / YUV, this function always returns TRUE.

Parameters

self	A VdoFrame.

Returns: TRUE if this is a keyframe, otherwise FALSE.

◆ vdo_frame_memmap()

gpointer vdo_frame_memmap ( VdoFrame * self )

A convenience function that maps the frame into current process memory.

This function will map the full buffer size as opposed to the current frame size. This is due to the requirement of mapping complete buffer size when the frame buffers are backed by AXIS' vcrfs which is the case for monolith cache.

Parameters

self	A VdoFrame.

Returns: A pointer to the mapped memory buffer.

Deprecated:: Prefer vdo_buffer_get_data

◆ vdo_frame_set_custom_timestamp()

void vdo_frame_set_custom_timestamp	(	VdoFrame *	self,
		gint64	timestamp
	)

Return a custom timestamp of this frame.

Parameters

self	A VdoFrame.
timestamp	The new custom timestamp for this frame.

◆ vdo_frame_set_extra_info()

void vdo_frame_set_extra_info	(	VdoFrame *	self,
		VdoMap *	extra_info
	)

Set the extra info of this frame.

Parameters

self	A VdoFrame.
extra_info	The new extra info for this frame.

◆ vdo_frame_set_frame_type()

void vdo_frame_set_frame_type	(	VdoFrame *	self,
		VdoFrameType	type
	)

Set the type of this frame.

Parameters

self	A VdoFrame.
type	The new type for this frame.

◆ vdo_frame_set_header_size()

void vdo_frame_set_header_size	(	VdoFrame *	self,
		gssize	size
	)

Set the header size of this frame, normally used for H26x frames.

The headers size can be used as an offset into the frame data buffer to get the frame data without headers. A size set to -1 indicates that the header size is unknown.

Parameters

self	A VdoFrame.
size	The combined size of the H264/H265 headers.

◆ vdo_frame_set_is_last_buffer()

void vdo_frame_set_is_last_buffer	(	VdoFrame *	self,
		gboolean	is_last_buffer
	)

Mark this frame as the last buffer.

Parameters

self	A VdoFrame.
is_last_buffer	If TRUE, marks the frame as last buffer.

◆ vdo_frame_set_sequence_nbr()

void vdo_frame_set_sequence_nbr	(	VdoFrame *	self,
		guint	seqnum
	)

Set the sequence number of this frame.

Parameters

self	A VdoFrame.
seqnum	The new sequence number for this frame.

◆ vdo_frame_set_size()

void vdo_frame_set_size	(	VdoFrame *	self,
		gsize	size
	)

Set the size of this frame.

Parameters

self	A VdoFrame.
size	The new size in bytes for this frame.

◆ vdo_frame_set_timestamp()

void vdo_frame_set_timestamp	(	VdoFrame *	self,
		guint64	timestamp
	)

Set the timestamp of this frame.

Parameters

self	A VdoFrame.
timestamp	The new timestamp for this frame.

◆ vdo_frame_shown()

gboolean vdo_frame_shown ( VdoFrame * self )

Return whether this frame is shown.

For most formats this will always be TRUE, one notable exception is AV1 where it corresponds to the 'show_frame' bit.

Parameters

self	A VdoFrame.

Returns: TRUE if this frame is shown, otherwise FALSE.

◆ vdo_frame_take_chunk()

VdoChunk vdo_frame_take_chunk	(	VdoFrame *	self,
		GError **	error
	)

Iterate buffer contents by chunks (with mmap).

while (1) {
  VdoChunk chunk = vdo_frame_take_chunk(frame, NULL);
  if (!chunk.size)
    break;
}

Parameters

self	A VdoFrame.
error	A location to return an error.

Returns: New chunks until VdoChunk.size equals 0.

◆ vdo_frame_take_chunk_ex()

VdoChunk vdo_frame_take_chunk_ex	(	VdoFrame *	self,
		VdoChunkOption	options,
		GError **	error
	)

Iterate buffer contents by chunks (optional mmap)

Unlike vdo_frame_take_chunk(), this function will not mmap any buffers by default, instead the VdoChunk can be directly forwarded to copy_file_range, sendfile, splice or similar functions.

while (1) {
  VdoChunk chunk = vdo_frame_take_chunk_ex(frame, VDO_CHUNK_OPTION_NONE, NULL);
  if (!chunk.size)
    break;
}

Parameters

self	A VdoFrame.
options	A VdoChunkOption.
error	A location to return an error.

Returns: New chunks until VdoChunk.size equals 0.

◆ vdo_frame_unmap()

void vdo_frame_unmap ( VdoFrame * self )

Unmaps the frame from current process memory.

Parameters

self	A VdoFrame

Deprecated:: Not needed when using vdo_buffer_get_data

Functions

Detailed Description

Function Documentation

◆ vdo_frame_get_custom_timestamp()

◆ vdo_frame_get_extra_info()

◆ vdo_frame_get_frame_type()

◆ vdo_frame_get_header_size()

◆ vdo_frame_get_is_last_buffer()

◆ vdo_frame_get_sequence_nbr()

◆ vdo_frame_get_size()

◆ vdo_frame_get_timestamp()

◆ vdo_frame_get_utc_timestamp()

◆ vdo_frame_is_key()

◆ vdo_frame_memmap()

◆ vdo_frame_set_custom_timestamp()

◆ vdo_frame_set_extra_info()

◆ vdo_frame_set_frame_type()

◆ vdo_frame_set_header_size()

◆ vdo_frame_set_is_last_buffer()

◆ vdo_frame_set_sequence_nbr()

◆ vdo_frame_set_size()

◆ vdo_frame_set_timestamp()

◆ vdo_frame_shown()

◆ vdo_frame_take_chunk()

◆ vdo_frame_take_chunk_ex()

◆ vdo_frame_unmap()