GstBufferList

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

## Synopsis

    #include <gst/gst.h>

                        GstBufferList;
    GstBufferList *     gst_buffer_list_new                 (void);
    GstBufferList *     gst_buffer_list_new_sized           (guint size);
    guint               gst_buffer_list_length              (GstBufferList *list);
    #define             gst_buffer_list_add                 (l,
                                                             b)
    void                gst_buffer_list_insert              (GstBufferList *list,
                                                             gint idx,
                                                             GstBuffer *buffer);
    void                gst_buffer_list_remove              (GstBufferList *list,
                                                             guint idx,
                                                             guint length);
    GstBufferList *     gst_buffer_list_ref                 (GstBufferList *list);
    void                gst_buffer_list_unref               (GstBufferList *list);
    GstBufferList *     gst_buffer_list_copy                (const GstBufferList *list);
    #define             gst_buffer_list_is_writable         (list)
    #define             gst_buffer_list_make_writable       (list)
    gboolean            (*GstBufferListFunc)                (GstBuffer **buffer,
                                                             guint idx,
                                                             gpointer user_data);
    gboolean            gst_buffer_list_foreach             (GstBufferList *list,
                                                             GstBufferListFunc func,
                                                             gpointer user_data);
    GstBuffer *         gst_buffer_list_get                 (GstBufferList *list,
                                                             guint idx);

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

Last reviewed on 2012-03-28 (0.11.3)

## Details

### GstBufferList

    typedef struct _GstBufferList GstBufferList;

Opaque list of grouped buffers.

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

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

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

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

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

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

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

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

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

`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()`.

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

`buffer` : | pointer the buffer
`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.

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

`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]

## See Also

GstPad, GstMiniObject