GstBufferList

GstBufferList — Lists of buffers for data-passing

Functions

Types and Values

Object Hierarchy

    GBoxed
    ╰── GstBufferList

Includes

#include <gst/gst.h>

Description

Buffer lists are an object containing a list of buffers.

Buffer lists are created with gst_buffer_list_new() and filled with data using a gst_buffer_list_insert().

Buffer lists can be pushed on a srcpad with gst_pad_push_list(). This is interesting when multiple buffers need to be pushed in one go because it can reduce the amount of overhead for pushing each buffer individually.

Functions

gst_buffer_list_new ()

GstBufferList *
gst_buffer_list_new (void);

Creates a new, empty GstBufferList. The caller is responsible for unreffing the returned GstBufferList.

Free-function: gst_buffer_list_unref

Returns

the new GstBufferList. gst_buffer_list_unref() after usage.

[transfer full]


gst_buffer_list_new_sized ()

GstBufferList *
gst_buffer_list_new_sized (guint size);

Creates a new, empty GstBufferList. The caller is responsible for unreffing the returned GstBufferList. The list will have size space preallocated so that memory reallocations can be avoided.

Free-function: gst_buffer_list_unref

Parameters

size

an initial reserved size

 

Returns

the new GstBufferList. gst_buffer_list_unref() after usage.

[transfer full]


gst_buffer_list_length ()

guint
gst_buffer_list_length (GstBufferList *list);

Returns the number of buffers in list .

Parameters

list

a GstBufferList

 

Returns

the number of buffers in the buffer list


gst_buffer_list_add()

#define gst_buffer_list_add(l,b) gst_buffer_list_insert((l),-1,(b));

Append b at the end of l .

Parameters

l

a GstBufferList

 

b

a GstBuffer

 

gst_buffer_list_insert ()

void
gst_buffer_list_insert (GstBufferList *list,
                        gint idx,
                        GstBuffer *buffer);

Insert buffer at idx in list . Other buffers are moved to make room for this new buffer.

A -1 value for idx will append the buffer at the end.

Parameters

list

a GstBufferList

 

idx

the index

 

buffer

a GstBuffer.

[transfer full]

gst_buffer_list_remove ()

void
gst_buffer_list_remove (GstBufferList *list,
                        guint idx,
                        guint length);

Remove length buffers starting from idx in list . The following buffers are moved to close the gap.

Parameters

list

a GstBufferList

 

idx

the index

 

length

the amount to remove

 

gst_buffer_list_ref ()

GstBufferList *
gst_buffer_list_ref (GstBufferList *list);

Increases the refcount of the given buffer list by one.

Note that the refcount affects the writability of list and its data, see gst_buffer_list_make_writable(). It is important to note that keeping additional references to GstBufferList instances can potentially increase the number of memcpy operations in a pipeline.

Parameters

list

a GstBufferList

 

Returns

list .

[transfer full]


gst_buffer_list_unref ()

void
gst_buffer_list_unref (GstBufferList *list);

Decreases the refcount of the buffer list. If the refcount reaches 0, the buffer list will be freed.

Parameters

list

a GstBufferList.

[transfer full]

gst_clear_buffer_list ()

void
gst_clear_buffer_list (GstBufferList **list_ptr);

Clears a reference to a GstBufferList.

list_ptr must not be NULL.

If the reference is NULL then this function does nothing. Otherwise, the reference count of the list is decreased and the pointer is set to NULL.

[skip]

Parameters

list_ptr

a pointer to a GstBufferList reference

 

Since: 1.16


gst_buffer_list_copy ()

GstBufferList *
gst_buffer_list_copy (const GstBufferList *list);

Create a shallow copy of the given buffer list. This will make a newly allocated copy of the source list with copies of buffer pointers. The refcount of buffers pointed to will be increased by one.

Parameters

list

a GstBufferList

 

Returns

a new copy of list .

[transfer full]


gst_buffer_list_copy_deep ()

GstBufferList *
gst_buffer_list_copy_deep (const GstBufferList *list);

Create a copy of the given buffer list. This will make a newly allocated copy of the buffer that the source buffer list contains.

Parameters

list

a GstBufferList

 

Returns

a new copy of list .

[transfer full]

Since: 1.6


gst_buffer_list_is_writable()

#define gst_buffer_list_is_writable(list) gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (list))

Tests if you can safely add buffers and groups into a buffer list.

Parameters

list

a GstBufferList

 

gst_buffer_list_make_writable()

#define gst_buffer_list_make_writable(list) GST_BUFFER_LIST_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (list)))

Makes a writable buffer list from the given buffer list. If the source buffer list is already writable, this will simply return the same buffer list. A copy will otherwise be made using gst_buffer_list_copy().

Parameters

list

a GstBufferList.

[transfer full]

Returns

a writable list, which may or may not be the same as list .

[transfer full]


gst_buffer_list_replace ()

gboolean
gst_buffer_list_replace (GstBufferList **old_list,
                         GstBufferList *new_list);

Modifies a pointer to a GstBufferList to point to a different GstBufferList. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old buffer list is unreffed, the new is reffed).

Either new_list or the GstBufferList pointed to by old_list may be NULL.

Parameters

old_list

pointer to a pointer to a GstBufferList to be replaced.

[inout][transfer full][nullable]

new_list

pointer to a GstBufferList that will replace the buffer list pointed to by old_list .

[transfer none][allow-none]

Returns

TRUE if new_list was different from old_list

Since: 1.16


gst_buffer_list_take ()

gboolean
gst_buffer_list_take (GstBufferList **old_list,
                      GstBufferList *new_list);

Modifies a pointer to a GstBufferList to point to a different GstBufferList. This function is similar to gst_buffer_list_replace() except that it takes ownership of new_list .

Parameters

old_list

pointer to a pointer to a GstBufferList to be replaced.

[inout][transfer full]

new_list

pointer to a GstBufferList that will replace the bufferlist pointed to by old_list .

[transfer full][allow-none]

Returns

TRUE if new_list was different from old_list

Since: 1.16


GstBufferListFunc ()

gboolean
(*GstBufferListFunc) (GstBuffer **buffer,
                      guint idx,
                      gpointer user_data);

A function that will be called from gst_buffer_list_foreach(). The buffer field will point to a the reference of the buffer at idx .

When this function returns TRUE, the next buffer will be returned. When FALSE is returned, gst_buffer_list_foreach() will return.

When buffer is set to NULL, the item will be removed from the bufferlist. When buffer has been made writable, the new buffer reference can be assigned to buffer . This function is responsible for unreffing the old buffer when removing or modifying.

Parameters

buffer

pointer the buffer.

[out][nullable]

idx

the index of buffer

 

user_data

user data passed to gst_buffer_list_foreach()

 

Returns

FALSE when gst_buffer_list_foreach() should stop


gst_buffer_list_foreach ()

gboolean
gst_buffer_list_foreach (GstBufferList *list,
                         GstBufferListFunc func,
                         gpointer user_data);

Call func with data for each buffer in list .

func can modify the passed buffer pointer or its contents. The return value of func define if this function returns or if the remaining buffers in the list should be skipped.

Parameters

list

a GstBufferList

 

func

a GstBufferListFunc to call.

[scope call]

user_data

user data passed to func .

[closure]

Returns

TRUE when func returned TRUE for each buffer in list or when list is empty.


gst_buffer_list_get ()

GstBuffer *
gst_buffer_list_get (GstBufferList *list,
                     guint idx);

Get the buffer at idx .

You must make sure that idx does not exceed the number of buffers available.

Parameters

list

a GstBufferList

 

idx

the index

 

Returns

the buffer at idx in group or NULL when there is no buffer. The buffer remains valid as long as list is valid and buffer is not removed from the list.

[transfer none][nullable]


gst_buffer_list_get_writable ()

GstBuffer *
gst_buffer_list_get_writable (GstBufferList *list,
                              guint idx);

Gets the buffer at idx , ensuring it is a writable buffer.

You must make sure that idx does not exceed the number of buffers available.

Parameters

list

a (writable) GstBufferList

 

idx

the index

 

Returns

the buffer at idx in group . The returned buffer remains valid as long as list is valid and the buffer is not removed from the list.

[transfer none][nullable]

Since: 1.14


gst_buffer_list_calculate_size ()

gsize
gst_buffer_list_calculate_size (GstBufferList *list);

Calculates the size of the data contained in buffer list by adding the size of all buffers.

Parameters

list

a GstBufferList

 

Returns

the size of the data contained in buffer list in bytes.

Since: 1.14

Types and Values

GstBufferList

typedef struct _GstBufferList GstBufferList;

Opaque list of grouped buffers.

See Also

GstPad, GstMiniObject