## GstBufferList

GstBufferList — Grouped scatter data buffer type for data-passing

## Synopsis

    #include <gst/gst.h>

                        GstBufferList;
                        GstBufferListIterator;
    GstBuffer *         (*GstBufferListDoFunction)          (GstBuffer *buffer,
                                                             gpointer user_data);
    GstBufferList *     gst_buffer_list_new                 (void);
    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)
    guint               gst_buffer_list_n_groups            (GstBufferList *list);
    enum                GstBufferListItem;
    GstBufferListItem   (*GstBufferListFunc)                (GstBuffer **buffer,
                                                             guint group,
                                                             guint idx,
                                                             gpointer user_data);
    void                gst_buffer_list_foreach             (GstBufferList *list,
                                                             GstBufferListFunc func,
                                                             gpointer user_data);
    GstBuffer *         gst_buffer_list_get                 (GstBufferList *list,
                                                             guint group,
                                                             guint idx);
    GstBufferListIterator * gst_buffer_list_iterate         (GstBufferList *list);
    void                gst_buffer_list_iterator_free       (GstBufferListIterator *it);
    guint               gst_buffer_list_iterator_n_buffers  (const GstBufferListIterator *it);
    void                gst_buffer_list_iterator_add        (GstBufferListIterator *it,
                                                             GstBuffer *buffer);
    void                gst_buffer_list_iterator_add_group  (GstBufferListIterator *it);
    void                gst_buffer_list_iterator_add_list   (GstBufferListIterator *it,
                                                             GList *list);
    GstBuffer *         gst_buffer_list_iterator_next       (GstBufferListIterator *it);
    gboolean            gst_buffer_list_iterator_next_group (GstBufferListIterator *it);
    void                gst_buffer_list_iterator_remove     (GstBufferListIterator *it);
    GstBuffer *         gst_buffer_list_iterator_steal      (GstBufferListIterator *it);
    void                gst_buffer_list_iterator_take       (GstBufferListIterator *it,
                                                             GstBuffer *buffer);
    GstBuffer *         gst_buffer_list_iterator_do         (GstBufferListIterator *it,
                                                             GstBufferListDoFunction do_func,
                                                             gpointer user_data);
    GstBuffer *         gst_buffer_list_iterator_merge_group
                                                            (const GstBufferListIterator *it);

## Description

Buffer lists are units of grouped scatter/gather data transfer in GStreamer.

Buffer lists are created with `gst_buffer_list_new()` and filled with data using a GstBufferListIterator. The iterator has no current buffer; its cursor position lies between buffers, immediately before the buffer that would be returned by `gst_buffer_list_iterator_next()`. After iterating to the end of a group the iterator must be advanced to the next group by a call to `gst_buffer_list_iterator_next_group()` before any further calls to `gst_buffer_list_iterator_next()` can return buffers again. The cursor position of a newly created iterator lies before the first group; a call to `gst_buffer_list_iterator_next_group()` is necessary before calls to `gst_buffer_list_iterator_next()` can return buffers.

         +--- group0 ----------------------+--- group1 ------------+
         |   buffer0   buffer1   buffer2   |   buffer3   buffer4   |
       ^   ^         ^         ^         ^   ^         ^         ^
       Iterator positions between buffers

The `gst_buffer_list_iterator_remove()`, `gst_buffer_list_iterator_steal()`, `gst_buffer_list_iterator_take()` and `gst_buffer_list_iterator_do()` functions are not defined in terms of the cursor position; they operate on the last element returned from `gst_buffer_list_iterator_next()`.

The basic use pattern of creating a buffer list with an iterator is as follows:

Example 4. Creating a buffer list

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16

    GstBufferList *list;
    GstBufferListIterator *it;

    list = gst_buffer_list_new ();
    it = gst_buffer_list_iterate (list);
    gst_buffer_list_iterator_add_group (it);
    gst_buffer_list_iterator_add (it, header1);
    gst_buffer_list_iterator_add (it, data1);
    gst_buffer_list_iterator_add_group (it);
    gst_buffer_list_iterator_add (it, header2);
    gst_buffer_list_iterator_add (it, data2);
    gst_buffer_list_iterator_add_group (it);
    gst_buffer_list_iterator_add (it, header3);
    gst_buffer_list_iterator_add (it, data3);
    ...
    gst_buffer_list_iterator_free (it);

The basic use pattern of iterating over a buffer list is as follows:

Example 5. Iterating a buffer list

    1
    2
    3
    4
    5
    6
    7
    8
    9

    GstBufferListIterator *it;

    it = gst_buffer_list_iterate (list);
    while (gst_buffer_list_iterator_next_group (it)) {
      while ((buffer = gst_buffer_list_iterator_next (it)) != NULL) {
        do_something_with_buffer (buffer);
      }
    }
    gst_buffer_list_iterator_free (it);

The basic use pattern of modifying a buffer in a list is as follows:

Example 6. Modifying the data of the first buffer in a list

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15

    GstBufferListIterator *it;

    list = gst_buffer_list_make_writable (list);
    it = gst_buffer_list_iterate (list);
    if (gst_buffer_list_iterator_next_group (it)) {
      GstBuffer *buf

      buf = gst_buffer_list_iterator_next (it);
      if (buf != NULL) {
        buf = gst_buffer_list_iterator_do (it,
            (GstBufferListDoFunction) gst_mini_object_make_writable, NULL);
        modify_data (GST_BUFFER_DATA (buf));
      }
    }
    gst_buffer_list_iterator_free (it);

## Details

### GstBufferList

    typedef struct _GstBufferList GstBufferList;

Opaque list of grouped buffers.

Since 0.10.24

### GstBufferListIterator

    typedef struct _GstBufferListIterator GstBufferListIterator;

Opaque iterator for a GstBufferList.

Since 0.10.24

### GstBufferListDoFunction ()

    GstBuffer *         (*GstBufferListDoFunction)          (GstBuffer *buffer,
                                                             gpointer user_data);

A function for accessing the last buffer returned by `gst_buffer_list_iterator_next()`. The function can leave `buffer` in the list, replace `buffer` in the list or remove `buffer` from the list, depending on the return value. If the function returns NULL, `buffer` will be removed from the list, otherwise `buffer` will be replaced with the returned buffer.

The last buffer returned by `gst_buffer_list_iterator_next()` will be replaced with the buffer returned from the function. The function takes ownership of `buffer` and if a different value than `buffer` is returned, `buffer` must be unreffed. If NULL is returned, the buffer will be removed from the list. The list must be writable.

`buffer` : | the GstBuffer. [transfer full]
`user_data` : | user data
Returns : | the buffer to replace `buffer` in the list, or NULL to remove `buffer` from the list. [transfer full]

Since 0.10.24

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

Since 0.10.24

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

Since 0.10.24

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

Since 0.10.24

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

Since 0.10.24

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

Since 0.10.24

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

Since 0.10.24

### gst_buffer_list_n_groups ()

    guint               gst_buffer_list_n_groups            (GstBufferList *list);

Returns the number of groups in `list`.

`list` : | a GstBufferList
Returns : | the number of groups in the buffer list

Since 0.10.24

### enum GstBufferListItem

    typedef enum {
      GST_BUFFER_LIST_CONTINUE,
      GST_BUFFER_LIST_SKIP_GROUP,
      GST_BUFFER_LIST_END
    } GstBufferListItem;

The result of the GstBufferListFunc.

`GST_BUFFER_LIST_CONTINUE` | Retrieve next buffer
`GST_BUFFER_LIST_SKIP_GROUP` | Skip to next group
`GST_BUFFER_LIST_END` | End iteration

Since 0.10.24

### GstBufferListFunc ()

    GstBufferListItem   (*GstBufferListFunc)                (GstBuffer **buffer,
                                                             guint group,
                                                             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` in `group`.

When this function returns GST_BUFFER_LIST_CONTINUE, the next buffer will be returned. When GST_BUFFER_LIST_SKIP_GROUP is returned, all remaining buffers in the current group will be skipped and the first buffer of the next group is returned (if any). When GST_BUFFER_LIST_END 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
`group` : | the group index of `buffer`
`idx` : | the index in `group` of `buffer`
`user_data` : | user data passed to `gst_buffer_list_foreach()`
Returns : | a GstBufferListItem

Since 0.10.24

### gst_buffer_list_foreach ()

    void                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 a group should be skipped.

`list` : | a GstBufferList
`func` : | a GstBufferListFunc to call. [scope call]
`user_data` : | user data passed to `func`

Since 0.10.24

### gst_buffer_list_get ()

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

Get the buffer at `idx` in `group`.

Note that this function is not efficient for iterating over the entire list. Use an iterator or `gst_buffer_list_foreach()` instead.

`list` : | a GstBufferList
`group` : | the group
`idx` : | the index in `group`
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]

Since 0.10.24

### gst_buffer_list_iterate ()

    GstBufferListIterator * gst_buffer_list_iterate         (GstBufferList *list);

Iterate the buffers in `list`. The owner of the iterator must also be the owner of a reference to `list` while the returned iterator is in use.

Free-function: gst_buffer_list_iterator_free

`list` : | a GstBufferList
Returns : | a new GstBufferListIterator of the buffers in `list`. `gst_buffer_list_iterator_free()` after usage. [transfer full]

Since 0.10.24

### gst_buffer_list_iterator_free ()

    void                gst_buffer_list_iterator_free       (GstBufferListIterator *it);

Free the iterator.

`it` : | the GstBufferListIterator to free. [transfer full]

Since 0.10.24

### gst_buffer_list_iterator_n_buffers ()

    guint               gst_buffer_list_iterator_n_buffers  (const GstBufferListIterator *it);

Returns the number of buffers left to iterate in the current group. I.e. the number of calls that can be made to `gst_buffer_list_iterator_next()` before it returns NULL.

This function will not move the implicit cursor or in any other way affect the state of the iterator `it`.

`it` : | a GstBufferListIterator
Returns : | the number of buffers left to iterate in the current group

Since 0.10.24

### gst_buffer_list_iterator_add ()

    void                gst_buffer_list_iterator_add        (GstBufferListIterator *it,
                                                             GstBuffer *buffer);

Inserts `buffer` into the GstBufferList iterated with `it`. The buffer is inserted into the current group, immediately before the buffer that would be returned by `gst_buffer_list_iterator_next()`. The buffer is inserted before the implicit cursor, a subsequent call to `gst_buffer_list_iterator_next()` will return the buffer after the inserted buffer, if any.

This function takes ownership of `buffer`.

`it` : | a GstBufferListIterator
`buffer` : | a GstBuffer. [transfer full]

Since 0.10.24

### gst_buffer_list_iterator_add_group ()

    void                gst_buffer_list_iterator_add_group  (GstBufferListIterator *it);

Inserts a new, empty group into the GstBufferList iterated with `it`. The group is inserted immediately before the group that would be returned by `gst_buffer_list_iterator_next_group()`. A subsequent call to `gst_buffer_list_iterator_next_group()` will advance the iterator to the group after the inserted group, if any.

`it` : | a GstBufferListIterator

Since 0.10.24

### gst_buffer_list_iterator_add_list ()

    void                gst_buffer_list_iterator_add_list   (GstBufferListIterator *it,
                                                             GList *list);

Inserts `list` of buffers into the GstBufferList iterated with `it`. The list is inserted into the current group, immediately before the buffer that would be returned by `gst_buffer_list_iterator_next()`. The list is inserted before the implicit cursor, a subsequent call to `gst_buffer_list_iterator_next()` will return the buffer after the last buffer of the inserted list, if any.

This function takes ownership of `list` and all its buffers.

`it` : | a GstBufferListIterator
`list` : | a GList of buffers. [transfer full][element-type Gst.Buffer]

Since 0.10.31

### gst_buffer_list_iterator_next ()

    GstBuffer *         gst_buffer_list_iterator_next       (GstBufferListIterator *it);

Returns the next buffer in the list iterated with `it`. If the iterator is at the end of a group, NULL will be returned. This function may be called repeatedly to iterate through the current group.

The caller will not get a new ref to the returned GstBuffer and must not unref it.

`it` : | a GstBufferListIterator
Returns : | the next buffer in the current group of the buffer list, or NULL. [transfer none]

Since 0.10.24

### gst_buffer_list_iterator_next_group ()

    gboolean            gst_buffer_list_iterator_next_group (GstBufferListIterator *it);

Advance the iterator `it` to the first buffer in the next group. If the iterator is at the last group, FALSE will be returned. This function may be called repeatedly to iterate through the groups in a buffer list.

`it` : | a GstBufferListIterator
Returns : | TRUE if the iterator could be advanced to the next group, FALSE if the iterator was already at the last group

Since 0.10.24

### gst_buffer_list_iterator_remove ()

    void                gst_buffer_list_iterator_remove     (GstBufferListIterator *it);

Removes the last buffer returned by `gst_buffer_list_iterator_next()` from the GstBufferList iterated with `it`. `gst_buffer_list_iterator_next()` must have been called on `it` before this function is called. This function can only be called once per call to `gst_buffer_list_iterator_next()`.

The removed buffer is unreffed.

`it` : | a GstBufferListIterator

Since 0.10.24

### gst_buffer_list_iterator_steal ()

    GstBuffer *         gst_buffer_list_iterator_steal      (GstBufferListIterator *it);

Returns the last buffer returned by `gst_buffer_list_iterator_next()` without modifying the refcount of the buffer.

`it` : | a GstBufferListIterator
Returns : | the last buffer returned by `gst_buffer_list_iterator_next()`. [transfer none]

Since 0.10.24

### gst_buffer_list_iterator_take ()

    void                gst_buffer_list_iterator_take       (GstBufferListIterator *it,
                                                             GstBuffer *buffer);

Replaces the last buffer returned by `gst_buffer_list_iterator_next()` with `buffer` in the GstBufferList iterated with `it` and takes ownership of `buffer`. `gst_buffer_list_iterator_next()` must have been called on `it` before this function is called. `gst_buffer_list_iterator_remove()` must not have been called since the last call to `gst_buffer_list_iterator_next()`.

This function unrefs the replaced buffer if it has not been stolen with `gst_buffer_list_iterator_steal()` and takes ownership of `buffer` (i.e. the refcount of `buffer` is not increased).

FIXME 0.11: this conditional taking-ownership is not good for bindings

`it` : | a GstBufferListIterator
`buffer` : | a GstBuffer. [transfer full]

Since 0.10.24

### gst_buffer_list_iterator_do ()

    GstBuffer *         gst_buffer_list_iterator_do         (GstBufferListIterator *it,
                                                             GstBufferListDoFunction do_func,
                                                             gpointer user_data);

Calls the given function for the last buffer returned by `gst_buffer_list_iterator_next()`. `gst_buffer_list_iterator_next()` must have been called on `it` before this function is called. `gst_buffer_list_iterator_remove()` and `gst_buffer_list_iterator_steal()` must not have been called since the last call to `gst_buffer_list_iterator_next()`.

See GstBufferListDoFunction for more details.

`it` : | a GstBufferListIterator
`do_func` : | the function to be called
`user_data` : | the gpointer to optional user data.
Returns : | the return value from `do_func`. [transfer none]

Since 0.10.24

### gst_buffer_list_iterator_merge_group ()

    GstBuffer *         gst_buffer_list_iterator_merge_group
                                                            (const GstBufferListIterator *it);

Merge a buffer list group into a normal GstBuffer by copying its metadata and memcpying its data into consecutive memory. All buffers in the current group after the implicit cursor will be merged into one new buffer. The metadata of the new buffer will be a copy of the metadata of the buffer that would be returned by `gst_buffer_list_iterator_next()`. If there is no buffer in the current group after the implicit cursor, NULL will be returned.

This function will not move the implicit cursor or in any other way affect the state of the iterator `it` or the list.

`it` : | a GstBufferListIterator
Returns : | a new GstBuffer, `gst_buffer_unref()` after usage, or NULL. [transfer full]

Since 0.10.24

## See Also

GstPad, GstMiniObject