A memory buffer. More...

#include "vdo-frame.h"

Include dependency graph for vdo-buffer.h:

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

Functions
VdoBuffer *	vdo_buffer_new (gint fd, gsize capacity, guint64 offset, gpointer opaque)
	Create a buffer which is owned by an external framework. More...

VdoBuffer *	vdo_buffer_new_full (gint fd, gsize capacity, guint64 offset, gpointer opaque, VdoMap *settings)
	Create a buffer with custom buffer properties. More...

guint32	vdo_buffer_get_id (VdoBuffer *self)
	Return an id representing the VdoBuffer. More...

gint	vdo_buffer_get_fd (VdoBuffer *self)
	Return a file descriptor representing the VdoBuffer. More...

gint64	vdo_buffer_get_offset (VdoBuffer *self)
	Return file offset to the VdoBuffer. More...

gsize	vdo_buffer_get_capacity (VdoBuffer *self)
	Returns the entire buffer capacity of the VdoBuffer. More...

gboolean	vdo_buffer_is_complete (VdoBuffer *self)
	Indicates whether the TemporalUnit is complete after this frame. More...

gboolean	vdo_buffer_is_contiguous (VdoBuffer *self)
	Indicates whether the buffer is contiguous or sparse. More...

gpointer	vdo_buffer_get_opaque (VdoBuffer *self)
	Get a pointer to an opaque, containing user provided custom information. More...

gpointer	vdo_buffer_get_data (VdoBuffer *self)
	Return a pointer to the underlying buffer. More...

VdoFrame *	vdo_buffer_get_frame (VdoBuffer *self)
	Return a pointer to the underlying frame. More...

Detailed Description

A memory buffer.

Function Documentation

◆ vdo_buffer_get_capacity()

gsize vdo_buffer_get_capacity ( VdoBuffer * self )

Returns the entire buffer capacity of the VdoBuffer.

For alignment purposes the buffer may be larger than requested.

Parameters

self	A VdoBuffer.

Returns: Capacity of the buffer in bytes.

◆ vdo_buffer_get_data()

gpointer vdo_buffer_get_data ( VdoBuffer * self )

Return a pointer to the underlying buffer.

Beware this pointer is only valid for as long as the VdoBuffer itself is valid.

The layout of the data depends on the VdoFormat and VdoFrameType. For H.26x this is always Annex B with long start-code 0x00000001.

For example a single VdoBuffer with format VDO_FRAME_TYPE_H265_IDR might contain [NAL_VPS][NAL_SPS][NAL_PPS][IDR-Slice].

In the above example vdo_frame_get_header_size is the byte offset to the IDR-Slice.

Parameters

self	A VdoBuffer.

Returns: A pointer to the buffer data or NULL if allocation failed.

◆ vdo_buffer_get_fd()

gint vdo_buffer_get_fd ( VdoBuffer * self )

Return a file descriptor representing the VdoBuffer.

Parameters

self	A VdoBuffer.

Returns: A file descriptor or -1 on error.

◆ vdo_buffer_get_frame()

VdoFrame* vdo_buffer_get_frame ( VdoBuffer * self )

Return a pointer to the underlying frame.

Beware this pointer is only valid for as long as the VdoBuffer itself is valid.

while (1) {
    VdoBuffer *buffer = vdo_stream_get_buffer(stream, &error);
    VdoFrame  *frame  = vdo_buffer_get_frame(buffer);
    if (!frame) { // An error occurred
        // Only log unexpected errors (ignore server maintenance etc.)
        if (!vdo_error_is_expected(&error))
            fprintf(stderr, "%s\n", err->message);
        // Exit and try to create a new stream
        break;
    }
 
    // Extract the timestamp from the frame
    uint64_t timestamp = vdo_frame_get_timestamp(frame);
 
    g_object_unref(buffer); // Both 'buffer' and 'frame' are now invalid
}

Parameters

self	A VdoBuffer, or NULL.

Returns: A pointer to the frame, or NULL if self was NULL.

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

◆ vdo_buffer_get_id()

guint32 vdo_buffer_get_id ( VdoBuffer * self )

Return an id representing the VdoBuffer.

The id is not guaranteed to be globally unique.

Parameters

self	A VdoBuffer.

Returns: The id.

◆ vdo_buffer_get_offset()

gint64 vdo_buffer_get_offset ( VdoBuffer * self )

Return file offset to the VdoBuffer.

Parameters

self	A VdoBuffer.

Returns: The file offset.

◆ vdo_buffer_get_opaque()

gpointer vdo_buffer_get_opaque ( VdoBuffer * self )

Get a pointer to an opaque, containing user provided custom information.

The opaque pointer has no predefined meaning inside the vdo framework itself, it is meant to facilitate interoperability with other existing frameworks as well as caching the buffer data pointer(see vdo_buffer_get_data).

typedef struct {
  gpointer buffer_data;
  size_t   framework_data;
} external_framework_t;
 
// Allocate and Enqueue a Buffer
external_framework_t *opaque_in = g_new0(external_framework_t, 1);
VdoBuffer *buffer_in = vdo_stream_buffer_alloc(stream, opaque_in, NULL);
opaque_in->buffer_data = vdo_buffer_get_data(buffer_in);
opaque_in->framework_data = 0x12345678;
vdo_stream_buffer_enqueue(stream, buffer_in);
 
// Retrieve filled Buffer
VdoBuffer *buffer_out = vdo_stream_get_buffer(stream, NULL);
external_framework_t *opaque_out = vdo_frame_get_opaque(buffer_out);
 
assert(opaque_in == opaque_out);

Parameters

self	A VdoBuffer.

Returns: A pointer to the opaque user provided information.

◆ vdo_buffer_is_complete()

gboolean vdo_buffer_is_complete ( VdoBuffer * self )

Indicates whether the TemporalUnit is complete after this frame.

This is only relevant for AV1 as other formats are complete.

Parameters

self	A VdoBuffer.

Returns: TRUE means complete, FALSE means incomplete.

◆ vdo_buffer_is_contiguous()

gboolean vdo_buffer_is_contiguous ( VdoBuffer * self )

Indicates whether the buffer is contiguous or sparse.

By default all buffers are contiguous unless the stream option "frame.chunks" is true, enabling chunks is necessary for zero-copy on some platforms.

Contiguous buffers have trivial layout (■■■). They can be accessed with vdo_buffer_get_data().

Sparse buffers are spread over multiple chunks with gaps in between (■□■□■). They must be accessed with vdo_frame_take_chunk() or vdo_frame_take_chunk_ex().

Parameters

self	A VdoBuffer.

Returns: TRUE means contiguous, FALSE means sparse.

◆ vdo_buffer_new()

VdoBuffer* vdo_buffer_new	(	gint	fd,
		gsize	capacity,
		guint64	offset,
		gpointer	opaque
	)

Create a buffer which is owned by an external framework.

Default: VDO_BUFFER_ACCESS_CPU_RD (suitable for normal consumers) The fd will not be closed by g_object_unref.

Parameters

fd	A mmap compatible file descriptor
capacity	The buffer capacity
offset	The offset to the start of the buffer
opaque	The opaque custom information associated with the buffer

Returns: A VdoBuffer. Free with g_object_unref().

◆ vdo_buffer_new_full()

VdoBuffer* vdo_buffer_new_full	(	gint	fd,
		gsize	capacity,
		guint64	offset,
		gpointer	opaque,
		VdoMap *	settings
	)

Create a buffer with custom buffer properties.

Default: VDO_BUFFER_ACCESS_ANY_RW (suitable for producers) The fd will not be closed by g_object_unref.

VdoMap *settings = vdo_map_new();
vdo_map_set_uint32(settings, "buffer.access", VDO_BUFFER_ACCESS_ANY_RW);
 
VdoBuffer *buffer = vdo_buffer_new_full(fd, capacity, 0, NULL, settings);

Parameters

fd	A mmap compatible file descriptor
capacity	The buffer capacity
offset	The offset to the start of the buffer
opaque	The opaque custom information associated with the buffer
settings	Override default buffer properties such as VdoBufferAccess

Returns: A VdoBuffer. Free with g_object_unref().

Functions

Detailed Description

Function Documentation

◆ vdo_buffer_get_capacity()

◆ vdo_buffer_get_data()

◆ vdo_buffer_get_fd()

◆ vdo_buffer_get_frame()

◆ vdo_buffer_get_id()

◆ vdo_buffer_get_offset()

◆ vdo_buffer_get_opaque()

◆ vdo_buffer_is_complete()

◆ vdo_buffer_is_contiguous()

◆ vdo_buffer_new()

◆ vdo_buffer_new_full()