GStreamer 1.0 Core Reference Manual: GstBufferList

## 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 ()
GstBufferList * | gst_buffer_list_copy ()
#define | gst_buffer_list_is_writable()
#define | gst_buffer_list_make_writable()
gboolean | (*GstBufferListFunc) ()
gboolean | gst_buffer_list_foreach ()
GstBuffer * | gst_buffer_list_get ()

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

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

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

[transfer none][nullable]

## Types and Values

### GstBufferList

    typedef struct _GstBufferList GstBufferList;

Opaque list of grouped buffers.

## See Also

GstPad, GstMiniObject