GstBufferList: GStreamer Core Reference Manual

## GstBufferList GstBufferList — Lists of buffers for data-passing |

## Functions

GstBufferList * | gst_buffer_list_new ()
GstBufferList * | gst_buffer_list_new_sized ()
guint | gst_buffer_list_length ()
#define | gst_buffer_list_add()
void | gst_buffer_list_insert ()
void | gst_buffer_list_remove ()
GstBufferList * | gst_buffer_list_ref ()
void | gst_buffer_list_unref ()
void | gst_clear_buffer_list ()
GstBufferList * | gst_buffer_list_copy ()
GstBufferList * | gst_buffer_list_copy_deep ()
#define | gst_buffer_list_is_writable()
#define | gst_buffer_list_make_writable()
gboolean | gst_buffer_list_replace ()
gboolean | gst_buffer_list_take ()
gboolean | (*GstBufferListFunc) ()
gboolean | gst_buffer_list_foreach ()
GstBuffer * | gst_buffer_list_get ()
GstBuffer * | gst_buffer_list_get_writable ()
gsize | gst_buffer_list_calculate_size ()

## Types and Values

| GstBufferList

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